@maggioli-design-system/magma-codemods 2.0.0-beta.0

package/dist/surfaces/inline-templates.d.ts

@@ -0,0 +1,3 @@
+import { type Manifest } from '../manifest/schema.js';
+import { type TransformContext, type TransformResult } from './shared/transform.js';
+export declare const transformInlineTemplates: (source: string, manifest: Manifest, ctx: TransformContext) => TransformResult;

package/dist/surfaces/inline-templates.js

@@ -0,0 +1,98 @@
+/**
+ * Inline-template surface for `.ts` files. Extracts and rewrites:
+ *
+ *  - Angular `@Component({ template: `…` })` inline templates → {@link transformAngular}.
+ *  - Generic inline HTML in no-substitution template literals that contain
+ *    `<mds-…>` tags or migrated utility classes (e.g. `el.innerHTML = `…``)
+ *    → {@link transformHtml}.
+ *
+ * Template literals with `${…}` substitutions are reported under `dynamic`
+ * (the holes make the markup unsafe to parse) rather than rewritten. Host
+ * bindings (`@Component({ host: {…} })`) are intentionally not rewritten:
+ * applying `mds-*` rules to a consumer component's own host is almost never
+ * correct, so it is left for manual review.
+ */
+import { Node, Project, SyntaxKind, ts } from 'ts-morph';
+import { applyEdits } from './shared/edits.js';
+import { classRulesOf } from './shared/class-ops.js';
+import { transformAngular } from './angular.js';
+import { transformHtml } from './html.js';
+const MDS_TAG_RE = /<mds-[a-z-]/;
+export const transformInlineTemplates = (source, manifest, ctx) => {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        skipFileDependencyResolution: true,
+        compilerOptions: { jsx: ts.JsxEmit.Preserve, allowJs: true },
+    });
+    const sf = project.createSourceFile('__codemod__.ts', source, { overwrite: true });
+    const edits = [];
+    const findings = [];
+    const handled = new Set();
+    // A literal is worth parsing when it contains mds-* markup OR mentions a
+    // migrated utility class (J) — those live on any element, not just mds-*.
+    const classRules = classRulesOf(manifest);
+    const relevant = (chunk) => MDS_TAG_RE.test(chunk) || (classRules.candidateRe?.test(chunk) ?? false);
+    /** Transform the raw inner text of a no-substitution template literal node. */
+    const transformLiteral = (node, run) => {
+        handled.add(node.getStart());
+        const innerStart = node.getStart() + 1;
+        const innerEnd = node.getEnd() - 1;
+        const inner = source.slice(innerStart, innerEnd);
+        if (!relevant(inner))
+            return;
+        const sub = run(inner, manifest, ctx);
+        const baseLine = node.getStartLineNumber();
+        for (const f of sub.findings) {
+            findings.push({ ...f, file: ctx.file, line: f.line ? baseLine + f.line - 1 : baseLine });
+        }
+        if (sub.changed)
+            edits.push({ start: innerStart, end: innerEnd, text: sub.output });
+    };
+    const flagDynamic = (node, message) => {
+        handled.add(node.getStart());
+        if (!relevant(node.getText()))
+            return;
+        findings.push({
+            kind: 'dynamic',
+            surface: 'html',
+            file: ctx.file,
+            line: node.getStartLineNumber(),
+            message,
+        });
+    };
+    // 1. Angular @Component({ template: `…` }) inline templates.
+    for (const dec of sf.getDescendantsOfKind(SyntaxKind.Decorator)) {
+        if (dec.getName() !== 'Component')
+            continue;
+        const call = dec.getCallExpression();
+        const arg = call?.getArguments()[0];
+        if (!arg || !Node.isObjectLiteralExpression(arg))
+            continue;
+        const templateProp = arg.getProperty('template');
+        if (!templateProp || !Node.isPropertyAssignment(templateProp))
+            continue;
+        const init = templateProp.getInitializer();
+        if (!init)
+            continue;
+        if (init.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+            transformLiteral(init, transformAngular);
+        }
+        else if (init.getKind() === SyntaxKind.TemplateExpression) {
+            flagDynamic(init, 'inline Angular template contains ${} interpolation; migrate it manually');
+        }
+    }
+    // 2. Generic inline HTML in no-substitution template literals with <mds-…>.
+    for (const lit of sf.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
+        if (handled.has(lit.getStart()))
+            continue;
+        transformLiteral(lit, transformHtml);
+    }
+    for (const te of sf.getDescendantsOfKind(SyntaxKind.TemplateExpression)) {
+        if (handled.has(te.getStart()))
+            continue;
+        flagDynamic(te, 'inline HTML template contains ${} interpolation; migrate it manually');
+    }
+    if (edits.length === 0)
+        return { output: source, changed: false, findings };
+    return { output: applyEdits(source, edits), changed: true, findings };
+};

package/dist/surfaces/react.d.ts

@@ -0,0 +1,3 @@
+import { type Manifest } from '../manifest/schema.js';
+import { type TransformContext, type TransformResult } from './shared/transform.js';
+export declare const transformReact: (source: string, manifest: Manifest, ctx: TransformContext) => TransformResult;

package/dist/surfaces/react.js

@@ -0,0 +1,496 @@
+/**
+ * React (JSX/TSX) surface. ts-morph is used purely as a parser to locate JSX
+ * elements and read their attribute/children shapes; transformations are
+ * emitted as offset edits on the original source (via {@link applyEdits}) so
+ * formatting is preserved and node invalidation is a non-issue.
+ *
+ * Both the PascalCase React components (`<MdsButton>`) and the custom elements
+ * used directly as intrinsic JSX tags (`<mds-button>`) are matched; intrinsic
+ * elements are matched and emitted with the kebab-case attribute spelling.
+ *
+ * Unanalyzable usage — spread props (`{...props}`), aliased components, computed
+ * names, dynamic children — is reported under the `dynamic` category instead of
+ * being rewritten.
+ */
+import { Project, SyntaxKind, ts, } from 'ts-morph';
+import { getByReactName, getByTag, ruleId, rulesForComponent, tagRenamesOf, } from '../manifest/registry.js';
+import { classRulesOf, hasClassRules, rewriteClassList } from './shared/class-ops.js';
+import { invertBoolean, remapEnum } from './shared/attribute-ops.js';
+import { bareTrue, boolLiteral, dynamic, stringLiteral, } from './shared/value-model.js';
+import { applyEdits } from './shared/edits.js';
+import { ruleEnabled } from './shared/transform.js';
+const jsxStringFor = (text) => /["&<>\n]/.test(text) ? `{${JSON.stringify(text)}}` : `"${text}"`;
+const collapseWhitespace = (s) => s.replace(/\s+/g, ' ').trim();
+export const transformReact = (source, manifest, ctx) => {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        skipFileDependencyResolution: true,
+        compilerOptions: { jsx: ts.JsxEmit.Preserve, allowJs: true },
+    });
+    const sf = project.createSourceFile('__codemod__.tsx', source, { overwrite: true });
+    const edits = [];
+    const findings = [];
+    const openings = [
+        ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+        ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+    ];
+    for (const opening of openings) {
+        const tagName = opening.getTagNameNode().getText();
+        // A dash can only appear in a plain intrinsic tag (member expressions
+        // contain `.`, namespaced names `:`), so it safely discriminates
+        // `<mds-button>` from `<MdsButton>`.
+        const isIntrinsic = tagName.includes('-');
+        const component = isIntrinsic ? getByTag(manifest, tagName) : getByReactName(manifest, tagName);
+        if (!component)
+            continue;
+        const tag = component.tag;
+        const line = opening.getStartLineNumber();
+        // Intrinsic custom elements take the kebab-case attribute spelling (React
+        // sets attributes on unknown elements); React components take the prop.
+        const nameOf = (p) => (isIntrinsic ? p.attr : p.prop);
+        const attributes = opening.getAttributes();
+        const hasSpread = attributes.some((a) => a.getKind() === SyntaxKind.JsxSpreadAttribute);
+        const jsxAttrs = attributes.filter((a) => a.getKind() === SyntaxKind.JsxAttribute);
+        const findAttr = (name) => jsxAttrs.find((a) => a.getNameNode().getText() === name);
+        const hasAttr = (name) => findAttr(name) !== undefined;
+        if (hasSpread) {
+            findings.push({
+                kind: 'dynamic',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                component: tag,
+                message: `<${tagName}> uses spread props ({...}); verify v2 props by hand`,
+            });
+        }
+        for (const rule of rulesForComponent(manifest, component)) {
+            const id = ruleId(tag, rule);
+            if (!ruleEnabled(ctx, id))
+                continue;
+            switch (rule.kind) {
+                case 'booleanInvert':
+                    applyBooleanInvert(rule, id);
+                    break;
+                case 'propRename':
+                    applyPropRename(rule, id);
+                    break;
+                case 'propRemove':
+                    applyPropRemove(rule, id);
+                    break;
+                case 'enumRemap':
+                    applyEnumRemap(rule, id);
+                    break;
+                case 'slotToAttr':
+                    applySlotToAttr(rule, id);
+                    break;
+                case 'ensureAttr':
+                    applyEnsureAttr(rule, id);
+                    break;
+                case 'slotRemove':
+                    applySlotRemove(rule, id);
+                    break;
+                default:
+                    break;
+            }
+        }
+        function applyEnsureAttr(rule, id) {
+            if (hasSpread)
+                return; // a spread may already set the prop; don't risk a duplicate
+            if (rule.unless.some((p) => hasAttr(nameOf(p))))
+                return;
+            const nameEnd = opening.getTagNameNode().getEnd();
+            const after = rule.value === undefined ? nameOf(rule.attr) : `${nameOf(rule.attr)}="${rule.value}"`;
+            edits.push({ start: nameEnd, end: nameEnd, text: ` ${after}` });
+            findings.push({
+                kind: 'change',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: rule.reason,
+                after,
+            });
+        }
+        function applySlotRemove(rule, id) {
+            const element = opening.getParentIfKind(SyntaxKind.JsxElement);
+            if (!element)
+                return;
+            for (const child of element.getJsxChildren()) {
+                let childOpening;
+                if (child.getKind() === SyntaxKind.JsxElement)
+                    childOpening = child.asKindOrThrow(SyntaxKind.JsxElement).getOpeningElement();
+                else if (child.getKind() === SyntaxKind.JsxSelfClosingElement)
+                    childOpening = child.asKindOrThrow(SyntaxKind.JsxSelfClosingElement);
+                else
+                    continue;
+                const slotAttr = childOpening
+                    .getAttributes()
+                    .filter((a) => a.getKind() === SyntaxKind.JsxAttribute)
+                    .find((a) => a.getNameNode().getText() === 'slot');
+                const init = slotAttr?.getInitializer();
+                if (!init || init.getKind() !== SyntaxKind.StringLiteral)
+                    continue;
+                if (init.getText().slice(1, -1) !== rule.from)
+                    continue;
+                findings.push({
+                    kind: 'warn',
+                    surface: 'react',
+                    file: ctx.file,
+                    line: child.getStartLineNumber(),
+                    ruleId: id,
+                    component: tag,
+                    message: `the \`${rule.from}\` slot of ${tag} was removed in v2; migrate the slotted content manually`,
+                });
+            }
+        }
+        function removeAttrEdit(attr) {
+            const start = attr.getStart();
+            const realStart = start > 0 && source[start - 1] === ' ' ? start - 1 : start;
+            return { start: realStart, end: attr.getEnd(), text: '' };
+        }
+        function valueOf(attr) {
+            const init = attr.getInitializer();
+            if (!init)
+                return bareTrue();
+            if (init.getKind() === SyntaxKind.StringLiteral)
+                return stringLiteral(init.getText().slice(1, -1));
+            if (init.getKind() === SyntaxKind.JsxExpression) {
+                const expr = init.getExpression();
+                if (!expr)
+                    return dynamic('');
+                if (expr.getKind() === SyntaxKind.TrueKeyword)
+                    return boolLiteral(true);
+                if (expr.getKind() === SyntaxKind.FalseKeyword)
+                    return boolLiteral(false);
+                return dynamic(expr.getText());
+            }
+            return dynamic(init.getText());
+        }
+        function applyBooleanInvert(rule, id) {
+            const attr = findAttr(nameOf(rule.from));
+            if (!attr)
+                return;
+            const outcome = invertBoolean(valueOf(attr), rule.newDefault);
+            let after = '';
+            if (outcome.action === 'omit') {
+                edits.push(removeAttrEdit(attr));
+            }
+            else if (outcome.action === 'shorthandTrue') {
+                after = nameOf(rule.to);
+                edits.push({ start: attr.getStart(), end: attr.getEnd(), text: after });
+            }
+            else if (outcome.action === 'explicitFalse') {
+                // Stencil parses the attribute string "false" as false (see resolveBoolean).
+                after = isIntrinsic ? `${rule.to.attr}="false"` : `${rule.to.prop}={false}`;
+                edits.push({ start: attr.getStart(), end: attr.getEnd(), text: after });
+            }
+            else {
+                after = `${nameOf(rule.to)}={${outcome.expr}}`;
+                edits.push({ start: attr.getStart(), end: attr.getEnd(), text: after });
+            }
+            findings.push({
+                kind: 'change',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: `invert ${rule.from.prop} → ${rule.to.prop}`,
+                before: attr.getText(),
+                after,
+            });
+        }
+        function applyPropRename(rule, id) {
+            const attr = findAttr(nameOf(rule.from));
+            if (!attr)
+                return;
+            const nameNode = attr.getNameNode();
+            edits.push({ start: nameNode.getStart(), end: nameNode.getEnd(), text: nameOf(rule.to) });
+            findings.push({
+                kind: 'change',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: `rename ${rule.from.prop} → ${rule.to.prop}`,
+                before: nameOf(rule.from),
+                after: nameOf(rule.to),
+            });
+        }
+        function applyPropRemove(rule, id) {
+            const attr = findAttr(nameOf(rule.prop));
+            if (!attr)
+                return;
+            edits.push(removeAttrEdit(attr));
+            findings.push({
+                kind: 'warn',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: rule.message,
+            });
+        }
+        function applyEnumRemap(rule, id) {
+            const attr = findAttr(nameOf(rule.prop));
+            if (!attr)
+                return;
+            const v2set = rule.v2set ? component.v2EnumSets?.[rule.v2set] : undefined;
+            const outcome = remapEnum(valueOf(attr), rule.map, v2set);
+            if (outcome.action === 'rename') {
+                edits.push({
+                    start: attr.getStart(),
+                    end: attr.getEnd(),
+                    text: `${nameOf(rule.prop)}="${outcome.value}"`,
+                });
+                findings.push({
+                    kind: 'change',
+                    surface: 'react',
+                    file: ctx.file,
+                    line,
+                    ruleId: id,
+                    component: tag,
+                    message: `remap ${rule.prop.prop}`,
+                    after: outcome.value,
+                });
+            }
+            else if (outcome.action === 'flag') {
+                const kind = valueOf(attr).kind === 'dynamic' ? 'dynamic' : 'flag';
+                findings.push({
+                    kind,
+                    surface: 'react',
+                    file: ctx.file,
+                    line,
+                    ruleId: id,
+                    component: tag,
+                    message: `${rule.prop.prop}: ${outcome.reason}`,
+                });
+            }
+        }
+        function applySlotToAttr(rule, id) {
+            if (rule.slot !== 'default')
+                return;
+            if (hasAttr(nameOf(rule.to)))
+                return;
+            const element = opening.getParentIfKind(SyntaxKind.JsxElement);
+            if (!element)
+                return; // self-closing → no children to lift
+            const children = element.getJsxChildren();
+            const elems = children.filter((c) => c.getKind() === SyntaxKind.JsxElement ||
+                c.getKind() === SyntaxKind.JsxSelfClosingElement ||
+                c.getKind() === SyntaxKind.JsxFragment);
+            const exprs = children.filter((c) => c.getKind() === SyntaxKind.JsxExpression);
+            const text = collapseWhitespace(children
+                .filter((c) => c.getKind() === SyntaxKind.JsxText)
+                .map((c) => c.getText())
+                .join(''));
+            const flag = (message) => {
+                findings.push({
+                    kind: 'dynamic',
+                    surface: 'react',
+                    file: ctx.file,
+                    line,
+                    ruleId: id,
+                    component: tag,
+                    message,
+                });
+            };
+            let labelAttr;
+            let before = '';
+            if (elems.length > 0) {
+                flag(`<${tagName}> content contains elements; move the text into \`${nameOf(rule.to)}\` manually`);
+                return;
+            }
+            else if (exprs.length === 0 && text !== '') {
+                labelAttr = `${nameOf(rule.to)}=${jsxStringFor(text)}`;
+                before = text;
+            }
+            else if (exprs.length === 1 && text === '') {
+                const expr = exprs[0].getExpression();
+                if (!expr)
+                    return;
+                labelAttr = `${nameOf(rule.to)}={${expr.getText()}}`;
+                before = `{${expr.getText()}}`;
+            }
+            else if (exprs.length === 0 && text === '') {
+                return; // empty element
+            }
+            else {
+                flag(`<${tagName}> has mixed text/expression content; move it into \`${nameOf(rule.to)}\` manually`);
+                return;
+            }
+            // Replace `>children</Tag>` with ` label=... />` (one edit; attribute edits sit before this range).
+            const start = opening.getEnd() - 1;
+            edits.push({ start, end: element.getEnd(), text: ` ${labelAttr} />` });
+            findings.push({
+                kind: 'change',
+                surface: 'react',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: `lift content into \`${nameOf(rule.to)}\``,
+                before,
+                after: labelAttr,
+            });
+        }
+    }
+    // Global: utility-class migrations (J) on `className` / `class` of ANY JSX
+    // element (the classes are not tied to an mds-* component). String literals
+    // and no-substitution templates anywhere in the attribute expression are
+    // rewritten (covers clsx()/classnames(), ternaries, `||` fallbacks);
+    // substitution templates can split a class across chunks, so they are
+    // reported instead.
+    const classRules = classRulesOf(manifest);
+    if (hasClassRules(classRules)) {
+        const rewriteLiteralContent = (node) => {
+            const inner = source.slice(node.getStart() + 1, node.getEnd() - 1);
+            const line = node.getStartLineNumber();
+            const result = rewriteClassList(inner, classRules, (id) => ruleEnabled(ctx, id), (entry, before, after) => {
+                findings.push({
+                    kind: 'change',
+                    surface: 'react',
+                    file: ctx.file,
+                    line,
+                    ruleId: entry.id,
+                    message: 'rename utility class',
+                    before,
+                    after,
+                });
+                if (entry.rule.note) {
+                    findings.push({
+                        kind: 'flag',
+                        surface: 'react',
+                        file: ctx.file,
+                        line,
+                        ruleId: entry.id,
+                        message: entry.rule.note,
+                    });
+                }
+            }, (entry, token) => {
+                findings.push({
+                    kind: 'warn',
+                    surface: 'react',
+                    file: ctx.file,
+                    line,
+                    ruleId: entry.id,
+                    message: `\`${token}\`: ${entry.rule.message}`,
+                });
+            });
+            if (result.changed)
+                edits.push({ start: node.getStart() + 1, end: node.getEnd() - 1, text: result.value });
+        };
+        const isPlainLiteral = (node) => node.getKind() === SyntaxKind.StringLiteral ||
+            node.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral;
+        for (const attr of sf.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+            const name = attr.getNameNode().getText();
+            if (name !== 'className' && name !== 'class')
+                continue;
+            const init = attr.getInitializer();
+            if (!init)
+                continue;
+            if (isPlainLiteral(init)) {
+                rewriteLiteralContent(init);
+                continue;
+            }
+            if (init.getKind() !== SyntaxKind.JsxExpression)
+                continue;
+            const expr = init.getExpression();
+            if (!expr)
+                continue;
+            const literals = [
+                ...(isPlainLiteral(expr) ? [expr] : []),
+                ...expr.getDescendantsOfKind(SyntaxKind.StringLiteral),
+                ...expr.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral),
+            ];
+            for (const literal of literals)
+                rewriteLiteralContent(literal);
+            const templates = [
+                ...(expr.getKind() === SyntaxKind.TemplateExpression ? [expr] : []),
+                ...expr.getDescendantsOfKind(SyntaxKind.TemplateExpression),
+            ];
+            for (const template of templates) {
+                if (!classRules.candidateRe?.test(template.getText()))
+                    continue;
+                findings.push({
+                    kind: 'dynamic',
+                    surface: 'react',
+                    file: ctx.file,
+                    line: template.getStartLineNumber(),
+                    message: `template literal in \`${name}\` mentions a migrated utility class; rewrite it manually`,
+                });
+            }
+        }
+    }
+    // K: tag renames. A separate pass over the tag names, so a component the
+    // manifest does not otherwise touch is renamed too. Every rename is looked up
+    // by the name AS WRITTEN, so a v1 name that another component takes in v2 is
+    // never renamed twice.
+    const tagRenames = tagRenamesOf(manifest);
+    if (tagRenames.size > 0) {
+        const byReact = new Map();
+        for (const [tag, rule] of tagRenames) {
+            const component = getByTag(manifest, tag);
+            if (component)
+                byReact.set(component.react, { tag, rule });
+        }
+        const renamedAt = new Set();
+        const renameNode = (node, tag, from, to) => {
+            const start = node.getStart();
+            if (renamedAt.has(start))
+                return;
+            renamedAt.add(start);
+            edits.push({ start, end: node.getEnd(), text: to });
+            findings.push({
+                kind: 'change',
+                surface: 'react',
+                file: ctx.file,
+                line: node.getStartLineNumber(),
+                component: tag,
+                ruleId: `${tag}/tagRename`,
+                message: `rename ${from} to ${to}`,
+                before: from,
+                after: to,
+            });
+        };
+        const tagNodes = [...openings, ...sf.getDescendantsOfKind(SyntaxKind.JsxClosingElement)].map((el) => el.getTagNameNode());
+        for (const nameNode of tagNodes) {
+            const name = nameNode.getText();
+            const hit = name.includes('-')
+                ? tagRenames.has(name)
+                    ? { tag: name, to: tagRenames.get(name).to }
+                    : undefined
+                : byReact.has(name)
+                    ? { tag: byReact.get(name).tag, to: byReact.get(name).rule.toReact }
+                    : undefined;
+            if (hit && ruleEnabled(ctx, `${hit.tag}/tagRename`))
+                renameNode(nameNode, hit.tag, name, hit.to);
+        }
+        // The named import from the React wrapper, and every other reference to it
+        // (`typeof MdsPrefTheme`, a re-export). An aliased import renames only the
+        // imported name: the local alias stays valid.
+        for (const decl of sf.getImportDeclarations()) {
+            if (!decl.getModuleSpecifierValue().startsWith('@maggioli-design-system/magma-react'))
+                continue;
+            for (const spec of decl.getNamedImports()) {
+                const name = spec.getName();
+                const hit = byReact.get(name);
+                if (!hit || !ruleEnabled(ctx, `${hit.tag}/tagRename`))
+                    continue;
+                renameNode(spec.getNameNode(), hit.tag, name, hit.rule.toReact);
+                if (spec.getAliasNode())
+                    continue;
+                for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
+                    if (id.getText() === name)
+                        renameNode(id, hit.tag, name, hit.rule.toReact);
+                }
+            }
+        }
+    }
+    if (edits.length === 0)
+        return { output: source, changed: false, findings };
+    return { output: applyEdits(source, edits), changed: true, findings };
+};

package/dist/surfaces/shared/attribute-ops.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Surface-agnostic transformation core. These functions take a parsed value
+ * (see {@link AttrValue}) plus the primitive parameters of a manifest rule and
+ * return an *outcome* describing what the surface should render — they never
+ * touch a concrete AST, so the logic is written and tested once.
+ */
+import { type AttrValue } from './value-model.js';
+/** What to do with the renamed boolean prop after inverting its value. */
+export type InvertOutcome = 
+/** New value equals the v2 default → drop the prop entirely. */
+{
+    action: 'omit';
+}
+/** New value is `true` → emit the prop in shorthand form. */
+ | {
+    action: 'shorthandTrue';
+}
+/** New value is `false` but the v2 default is `true` → emit an explicit `false`. */
+ | {
+    action: 'explicitFalse';
+}
+/** New value is dynamic → emit the prop with the negated expression text. */
+ | {
+    action: 'expr';
+    expr: string;
+};
+/**
+ * Invert a boolean prop's value (category B). The new prop's value is the
+ * logical negation of the old one; `newDefault` decides whether that value can
+ * be omitted. `oldDefault` is intentionally unused — for a boolean prop the
+ * shorthand always means `true` regardless of the declared default.
+ */
+export declare const invertBoolean: (current: AttrValue, newDefault: boolean) => InvertOutcome;
+/** Outcome of remapping an enum value (categories A and E). */
+export type EnumRemapOutcome = 
+/** Map the literal to a new v2 value. */
+{
+    action: 'rename';
+    value: string;
+}
+/** The value is already a valid v2 literal not covered by the map → leave it. */
+ | {
+    action: 'keep';
+}
+/** Cannot transform safely; surface should report it for manual review. */
+ | {
+    action: 'flag';
+    reason: string;
+};
+/**
+ * Remap an enum literal, validating the target against the component's v2 enum
+ * set when available. Dynamic values, map targets that are `null` (no 1:1
+ * replacement) and literals absent from the v2 set are flagged for the report
+ * instead of being rewritten blindly.
+ */
+export declare const remapEnum: (current: AttrValue, map: Record<string, string | null>, v2set?: readonly string[]) => EnumRemapOutcome;