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

package/dist/surfaces/css.js

@@ -0,0 +1,287 @@
+/**
+ * CSS / SCSS surface (category G — CSS custom properties, category H — shadow
+ * parts in `::part()` selectors, and category J — utility classes in `@apply`
+ * at-rules). Uses postcss (+ postcss-scss) and mutates the AST in place so
+ * formatting is preserved.
+ *
+ * Custom-property *definitions* are renamed and, when the value format changed
+ * (e.g. hex → `R G B` channels for `-rgb` variables), flagged for manual
+ * conversion. `var(--x)` *references* are renamed everywhere they appear.
+ * Definitions/references of properties removed in v2 with no replacement
+ * (G2, `cssVarRemove`) are reported, not rewritten.
+ */
+import postcss from 'postcss';
+import postcssScss from 'postcss-scss';
+import { ruleId, tagRenamesOf } from '../manifest/registry.js';
+import { classRulesOf, hasClassRules, rewriteClassList } from './shared/class-ops.js';
+import { ruleEnabled } from './shared/transform.js';
+/**
+ * Tag used for the manifest-global CSS-var rules (the `--tone-*-seed` rename and
+ * the surface-candidate reports), which no component owns. They surface in
+ * `--only` / `--skip` as `global/cssVarRename/...` and
+ * `global/cssVarSurfaceReport/...`.
+ */
+const GLOBAL_TAG = 'global';
+/**
+ * A neutral tone used as a *background* is a surface candidate (spec 12): the
+ * `background` / `background-color` property, or a custom property whose name
+ * carries `background` (component `--mds-*-background*` tokens).
+ */
+const isBackgroundContext = (prop) => prop === 'background' ||
+    prop === 'background-color' ||
+    (prop.startsWith('--') && prop.includes('background'));
+const collectRules = (manifest) => {
+    const cssVars = new Map();
+    const removedVars = new Map();
+    const surfaceReports = new Map();
+    const parts = new Map();
+    for (const component of Object.values(manifest.components)) {
+        for (const rule of component.rules) {
+            if (rule.kind === 'cssVarRename')
+                cssVars.set(rule.from, { rule, id: ruleId(component.tag, rule) });
+            else if (rule.kind === 'cssVarRemove')
+                removedVars.set(rule.name, { rule, id: ruleId(component.tag, rule) });
+            else if (rule.kind === 'partRename')
+                parts.set(rule.from, { rule, id: ruleId(component.tag, rule) });
+        }
+    }
+    // Manifest-global CSS-var migrations (not owned by any component): the seed
+    // rename (rewritten) and the surface-candidate reports (reported only).
+    for (const rule of manifest.global.cssVars ?? []) {
+        if (rule.kind === 'cssVarRename')
+            cssVars.set(rule.from, { rule, id: ruleId(GLOBAL_TAG, rule) });
+        else
+            surfaceReports.set(rule.from, { rule, id: ruleId(GLOBAL_TAG, rule) });
+    }
+    return { cssVars, removedVars, surfaceReports, parts };
+};
+const PART_RE = /::part\(\s*([\w-]+)\s*\)/g;
+/**
+ * A class (`.name`, also compounded: `html.name`) or a type selector (`name`) in
+ * a selector. A type selector is a name that no `.`, `#`, `-`, word character,
+ * `[`, `=`, quote or `:` precedes, so a class, an id, an attribute, a
+ * pseudo-class and the tail of a longer name are left alone.
+ */
+const SELECTOR_NAME_RE = /\.([\w-]+)|(?<![\w.#\-[="':])([a-zA-Z][\w-]*)/g;
+const VAR_TOKEN_RE = /--[\w-]+/g;
+export const transformCss = (source, manifest, ctx, options = {}) => {
+    const { cssVars, removedVars, surfaceReports, parts } = collectRules(manifest);
+    const findings = [];
+    let changed = false;
+    /** Warn (once per occurrence) when a removed custom property is defined or referenced. */
+    const warnRemoved = (name, line) => {
+        const entry = removedVars.get(name);
+        if (!entry || !ruleEnabled(ctx, entry.id))
+            return;
+        findings.push({
+            kind: 'warn',
+            surface: 'css',
+            file: ctx.file,
+            line,
+            ruleId: entry.id,
+            message: entry.rule.message,
+        });
+    };
+    const root = options.scss
+        ? postcssScss.parse(source, { from: ctx.file })
+        : postcss.parse(source, { from: ctx.file });
+    const finding = (entry, line, extra) => ({
+        kind: 'change',
+        surface: 'css',
+        file: ctx.file,
+        line,
+        ruleId: entry.id,
+        ...extra,
+    });
+    root.walkDecls((decl) => {
+        const line = decl.source?.start?.line;
+        // Custom-property definition site: `--mds-banner-color: #fff;`.
+        if (decl.prop.startsWith('--')) {
+            const name = decl.prop.slice(2);
+            warnRemoved(name, line);
+            const entry = cssVars.get(name);
+            if (entry && ruleEnabled(ctx, entry.id)) {
+                const before = decl.prop;
+                decl.prop = `--${entry.rule.to}`;
+                changed = true;
+                findings.push(finding(entry, line, { message: `rename custom property`, before, after: decl.prop }));
+                if (entry.rule.valueFormatChanged) {
+                    findings.push({
+                        kind: 'flag',
+                        surface: 'css',
+                        file: ctx.file,
+                        line,
+                        ruleId: entry.id,
+                        message: `value format changed (${entry.rule.note ?? 'e.g. hex → "R G B" channels'}): convert the value of \`${decl.prop}\` by hand`,
+                    });
+                }
+                else if (entry.rule.note) {
+                    findings.push({
+                        kind: 'flag',
+                        surface: 'css',
+                        file: ctx.file,
+                        line,
+                        ruleId: entry.id,
+                        message: entry.rule.note,
+                    });
+                }
+            }
+        }
+        // `var(--x)` references inside any value. A surface candidate used as a
+        // background is REPORTED, not rewritten (the exact role is contextual); this
+        // takes precedence over the seed rename so a background is never
+        // seed-renamed. Everything else follows the plain rename.
+        if (decl.value && decl.value.includes('--')) {
+            for (const token of decl.value.match(VAR_TOKEN_RE) ?? [])
+                warnRemoved(token.slice(2), line);
+            const backgroundContext = isBackgroundContext(decl.prop);
+            const newValue = decl.value.replace(VAR_TOKEN_RE, (token) => {
+                const name = token.slice(2);
+                const report = backgroundContext ? surfaceReports.get(name) : undefined;
+                if (report && ruleEnabled(ctx, report.id)) {
+                    findings.push({
+                        kind: 'warn',
+                        surface: 'css',
+                        file: ctx.file,
+                        line,
+                        ruleId: report.id,
+                        message: `\`${token}\` is used as a background here; migrate it by hand to a semantic surface role (\`--magma-surface-*\`: default / raised / overlay / sunken / muted)${report.rule.note ? ` (${report.rule.note})` : ''}`,
+                    });
+                    return token;
+                }
+                const entry = cssVars.get(name);
+                if (entry && ruleEnabled(ctx, entry.id)) {
+                    changed = true;
+                    findings.push(finding(entry, line, {
+                        message: `rename custom property reference`,
+                        before: token,
+                        after: `--${entry.rule.to}`,
+                    }));
+                    return `--${entry.rule.to}`;
+                }
+                return token;
+            });
+            if (newValue !== decl.value)
+                decl.value = newValue;
+        }
+    });
+    // Utility-class migrations (J) in `@apply` at-rules (Tailwind CSS sources).
+    const classRules = classRulesOf(manifest);
+    if (hasClassRules(classRules)) {
+        root.walkAtRules('apply', (atRule) => {
+            const line = atRule.source?.start?.line;
+            const result = rewriteClassList(atRule.params, classRules, (id) => ruleEnabled(ctx, id), (entry, before, after) => {
+                findings.push({
+                    kind: 'change',
+                    surface: 'css',
+                    file: ctx.file,
+                    line,
+                    ruleId: entry.id,
+                    message: 'rename utility class',
+                    before,
+                    after,
+                });
+                if (entry.rule.note) {
+                    findings.push({
+                        kind: 'flag',
+                        surface: 'css',
+                        file: ctx.file,
+                        line,
+                        ruleId: entry.id,
+                        message: entry.rule.note,
+                    });
+                }
+            }, (entry, token) => {
+                findings.push({
+                    kind: 'warn',
+                    surface: 'css',
+                    file: ctx.file,
+                    line,
+                    ruleId: entry.id,
+                    message: `\`${token}\`: ${entry.rule.message}`,
+                });
+            });
+            if (result.changed) {
+                atRule.params = result.value;
+                changed = true;
+            }
+        });
+    }
+    root.walkRules((rule) => {
+        if (!rule.selector.includes('::part('))
+            return;
+        const line = rule.source?.start?.line;
+        const newSelector = rule.selector.replace(PART_RE, (match, partName) => {
+            const entry = parts.get(partName);
+            if (entry && ruleEnabled(ctx, entry.id)) {
+                changed = true;
+                findings.push(finding(entry, line, {
+                    message: `rename shadow part`,
+                    before: `::part(${partName})`,
+                    after: `::part(${entry.rule.to})`,
+                }));
+                return `::part(${entry.rule.to})`;
+            }
+            return match;
+        });
+        if (newSelector !== rule.selector)
+            rule.selector = newSelector;
+    });
+    // K and J in selectors: a renamed element (`mds-pref-theme`) as a type
+    // selector, and a renamed state class that consumer stylesheets select
+    // (`.pref-theme-dark`, only the class rules with `selectors: true`). One
+    // lookup per token, so a v1 name that another one takes in v2 is renamed
+    // once.
+    const tagRenames = tagRenamesOf(manifest);
+    const selectorClasses = [...classRules.renames.values()].filter((e) => e.rule.selectors);
+    if (tagRenames.size > 0 || selectorClasses.length > 0) {
+        const classByName = new Map(selectorClasses.map((e) => [e.rule.from, e]));
+        root.walkRules((rule) => {
+            const line = rule.source?.start?.line;
+            const newSelector = rule.selector.replace(SELECTOR_NAME_RE, (match, className, typeName) => {
+                if (className !== undefined) {
+                    const name = className;
+                    const entry = classByName.get(name);
+                    if (!entry || !ruleEnabled(ctx, entry.id))
+                        return match;
+                    findings.push({
+                        kind: 'change',
+                        surface: 'css',
+                        file: ctx.file,
+                        line,
+                        ruleId: entry.id,
+                        message: 'rename class selector',
+                        before: `.${name}`,
+                        after: `.${entry.rule.to}`,
+                    });
+                    return `.${entry.rule.to}`;
+                }
+                const name = typeName;
+                const tagRule = tagRenames.get(name);
+                const id = `${name}/tagRename`;
+                if (!tagRule || !ruleEnabled(ctx, id))
+                    return match;
+                findings.push({
+                    kind: 'change',
+                    surface: 'css',
+                    file: ctx.file,
+                    line,
+                    component: name,
+                    ruleId: id,
+                    message: 'rename type selector',
+                    before: name,
+                    after: tagRule.to,
+                });
+                return tagRule.to;
+            });
+            if (newSelector !== rule.selector) {
+                rule.selector = newSelector;
+                changed = true;
+            }
+        });
+    }
+    if (!changed)
+        return { output: source, changed: false, findings };
+    const output = options.scss ? root.toString(postcssScss) : root.toString();
+    return { output, changed: true, findings };
+};

package/dist/surfaces/html.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 transformHtml: (source: string, manifest: Manifest, ctx: TransformContext) => TransformResult;

package/dist/surfaces/html.js

@@ -0,0 +1,402 @@
+/**
+ * HTML surface. Parses with parse5 (location info on) and applies offset-based
+ * edits to the original source so formatting and quoting are preserved.
+ *
+ * Handles, for `mds-*` elements: boolean inversion (B), prop rename (D), prop
+ * removal (C, inline comment), enum remap (A/E), the preferred slot→attr
+ * lift (F2, e.g. `mds-button` text → `label`), and removed named slots (F,
+ * children using them are reported). The global `slot="default"` removal (F)
+ * applies to any element.
+ */
+import { parseFragment } from 'parse5';
+import { getByTag, ruleId, rulesForComponent } from '../manifest/registry.js';
+import { classRulesOf, hasClassRules, rewriteClassList } from './shared/class-ops.js';
+import { invertBoolean, remapEnum } from './shared/attribute-ops.js';
+import { bareTrue, stringLiteral } from './shared/value-model.js';
+import { applyEdits, lineIndentAt } from './shared/edits.js';
+import { ruleEnabled } from './shared/transform.js';
+const isElement = (node) => Array.isArray(node.attrs);
+const escapeHtmlAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+const collapseWhitespace = (s) => s.replace(/\s+/g, ' ').trim();
+const parseRawAttr = (raw) => {
+    const eq = raw.indexOf('=');
+    if (eq === -1)
+        return { name: raw.trim(), hasValue: false, quote: '"' };
+    const rest = raw.slice(eq + 1).trim();
+    const quote = rest[0] === "'" || rest[0] === '"' ? rest[0] : '"';
+    return { name: raw.slice(0, eq).trim(), hasValue: true, quote };
+};
+export const transformHtml = (source, manifest, ctx) => {
+    const fragment = parseFragment(source, { sourceCodeLocationInfo: true });
+    const edits = [];
+    const findings = [];
+    const classRules = classRulesOf(manifest);
+    const pushFinding = (f) => {
+        findings.push(f);
+    };
+    /** Remove an attribute (and one leading space) by its source location. */
+    const removeAttrEdit = (loc) => {
+        const start = loc.startOffset > 0 && source[loc.startOffset - 1] === ' '
+            ? loc.startOffset - 1
+            : loc.startOffset;
+        return { start, end: loc.endOffset, text: '' };
+    };
+    const visit = (node) => {
+        if (isElement(node))
+            processElement(node);
+        for (const child of node.childNodes ?? [])
+            visit(child);
+        if (node.content)
+            visit(node.content); // <template>
+    };
+    const processElement = (node) => {
+        const tag = node.tagName ?? '';
+        const loc = node.sourceCodeLocation;
+        const attrLocs = loc?.attrs ?? {};
+        const attrs = node.attrs ?? [];
+        const hasAttr = (name) => attrs.some((a) => a.name === name);
+        const getAttr = (name) => attrs.find((a) => a.name === name);
+        // Global: remove `slot="default"` on any element.
+        if (manifest.global.removeDefaultSlot) {
+            const slot = getAttr('slot');
+            if (slot && slot.value === 'default' && ruleEnabled(ctx, 'global/removeDefaultSlot')) {
+                const l = attrLocs['slot'];
+                if (l) {
+                    edits.push(removeAttrEdit(l));
+                    pushFinding({
+                        kind: 'change',
+                        surface: 'html',
+                        file: ctx.file,
+                        line: l.startLine,
+                        ruleId: 'global/removeDefaultSlot',
+                        message: 'remove slot="default"',
+                        before: 'slot="default"',
+                        after: '',
+                    });
+                }
+            }
+        }
+        // Global: utility-class migrations (J) on any element's `class` attribute.
+        // The raw source value is rewritten (not the entity-decoded one), so
+        // arbitrary variants written with references (`[&gt;li]:`) round-trip.
+        if (hasClassRules(classRules)) {
+            const l = attrLocs['class'];
+            if (l && hasAttr('class')) {
+                const raw = source.slice(l.startOffset, l.endOffset);
+                const parsed = parseRawAttr(raw);
+                if (parsed.hasValue) {
+                    const open = raw.indexOf(parsed.quote) + 1;
+                    const close = raw.lastIndexOf(parsed.quote);
+                    const rawValue = open > 0 && close > open ? raw.slice(open, close) : '';
+                    const result = rewriteClassList(rawValue, classRules, (id) => ruleEnabled(ctx, id), (entry, before, after) => {
+                        pushFinding({
+                            kind: 'change',
+                            surface: 'html',
+                            file: ctx.file,
+                            line: l.startLine,
+                            ruleId: entry.id,
+                            message: 'rename utility class',
+                            before,
+                            after,
+                        });
+                        if (entry.rule.note) {
+                            pushFinding({
+                                kind: 'flag',
+                                surface: 'html',
+                                file: ctx.file,
+                                line: l.startLine,
+                                ruleId: entry.id,
+                                message: entry.rule.note,
+                            });
+                        }
+                    }, (entry, token) => {
+                        pushFinding({
+                            kind: 'warn',
+                            surface: 'html',
+                            file: ctx.file,
+                            line: l.startLine,
+                            ruleId: entry.id,
+                            message: `\`${token}\`: ${entry.rule.message}`,
+                        });
+                    });
+                    if (result.changed) {
+                        edits.push({
+                            start: l.startOffset + open,
+                            end: l.startOffset + close,
+                            text: result.value,
+                        });
+                    }
+                }
+            }
+        }
+        const component = getByTag(manifest, tag);
+        if (!component)
+            return;
+        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;
+                case 'tagRename':
+                    applyTagRename(rule, id);
+                    break;
+                // slotRename/cssVarRename/cssVarRemove/partRename/eventRename: not applicable to plain HTML attributes.
+                default:
+                    break;
+            }
+        }
+        /** Rename the start tag and, when written, the end tag; the name sits right after `<` / `</`. */
+        function applyTagRename(rule, id) {
+            if (!loc?.startTag)
+                return;
+            const nameEdit = (at) => ({ start: at, end: at + tag.length, text: rule.to });
+            edits.push(nameEdit(loc.startTag.startOffset + 1));
+            if (loc.endTag)
+                edits.push(nameEdit(loc.endTag.startOffset + 2));
+            pushFinding({
+                kind: 'change',
+                surface: 'html',
+                file: ctx.file,
+                line: loc.startLine,
+                component: tag,
+                ruleId: id,
+                message: `rename <${tag}> to <${rule.to}>`,
+                before: tag,
+                after: rule.to,
+            });
+        }
+        function attrValueOf(attr, hasValueRaw) {
+            return hasValueRaw ? stringLiteral(attr.value) : bareTrue();
+        }
+        function applyBooleanInvert(rule, id) {
+            const attr = getAttr(rule.from.attr);
+            const l = attrLocs[rule.from.attr];
+            if (!attr || !l)
+                return;
+            const raw = source.slice(l.startOffset, l.endOffset);
+            const parsed = parseRawAttr(raw);
+            const outcome = invertBoolean(attrValueOf(attr, parsed.hasValue), rule.newDefault);
+            let after = '';
+            if (outcome.action === 'omit') {
+                edits.push(removeAttrEdit(l));
+            }
+            else if (outcome.action === 'shorthandTrue') {
+                after = rule.to.attr;
+                edits.push({ start: l.startOffset, end: l.endOffset, text: after });
+            }
+            else if (outcome.action === 'explicitFalse') {
+                after = `${rule.to.attr}="false"`;
+                edits.push({ start: l.startOffset, end: l.endOffset, text: after });
+            }
+            pushFinding({
+                kind: 'change',
+                surface: 'html',
+                file: ctx.file,
+                line: l.startLine,
+                ruleId: id,
+                component: tag,
+                message: `invert ${rule.from.prop} → ${rule.to.prop}`,
+                before: raw,
+                after,
+            });
+        }
+        function applyPropRename(rule, id) {
+            const l = attrLocs[rule.from.attr];
+            if (!l)
+                return;
+            const raw = source.slice(l.startOffset, l.endOffset);
+            const parsed = parseRawAttr(raw);
+            edits.push({
+                start: l.startOffset,
+                end: l.startOffset + parsed.name.length,
+                text: rule.to.attr,
+            });
+            pushFinding({
+                kind: 'change',
+                surface: 'html',
+                file: ctx.file,
+                line: l.startLine,
+                ruleId: id,
+                component: tag,
+                message: `rename ${rule.from.prop} → ${rule.to.prop}`,
+                before: parsed.name,
+                after: rule.to.attr,
+            });
+        }
+        function applyPropRemove(rule, id) {
+            const l = attrLocs[rule.prop.attr];
+            if (!l)
+                return;
+            edits.push(removeAttrEdit(l));
+            if (rule.strategy === 'comment' && loc) {
+                const indent = lineIndentAt(source, loc.startOffset);
+                edits.push({
+                    start: loc.startOffset,
+                    end: loc.startOffset,
+                    text: `<!-- TODO magma v2: ${rule.message} -->\n${indent}`,
+                });
+            }
+            pushFinding({
+                kind: 'warn',
+                surface: 'html',
+                file: ctx.file,
+                line: l.startLine,
+                ruleId: id,
+                component: tag,
+                message: rule.message,
+            });
+        }
+        function applyEnumRemap(rule, id) {
+            const attr = getAttr(rule.prop.attr);
+            const l = attrLocs[rule.prop.attr];
+            if (!attr || !l)
+                return;
+            const raw = source.slice(l.startOffset, l.endOffset);
+            const parsed = parseRawAttr(raw);
+            const v2set = rule.v2set ? component.v2EnumSets?.[rule.v2set] : undefined;
+            const outcome = remapEnum(attrValueOf(attr, parsed.hasValue), rule.map, v2set);
+            if (outcome.action === 'rename') {
+                const q = parsed.quote;
+                edits.push({
+                    start: l.startOffset,
+                    end: l.endOffset,
+                    text: `${rule.prop.attr}=${q}${outcome.value}${q}`,
+                });
+                pushFinding({
+                    kind: 'change',
+                    surface: 'html',
+                    file: ctx.file,
+                    line: l.startLine,
+                    ruleId: id,
+                    component: tag,
+                    message: `remap ${rule.prop.prop}`,
+                    before: attr.value,
+                    after: outcome.value,
+                });
+            }
+            else if (outcome.action === 'flag') {
+                pushFinding({
+                    kind: 'flag',
+                    surface: 'html',
+                    file: ctx.file,
+                    line: l.startLine,
+                    ruleId: id,
+                    component: tag,
+                    message: `${rule.prop.prop}="${attr.value}": ${outcome.reason}`,
+                });
+            }
+        }
+        function applyEnsureAttr(rule, id) {
+            if (!loc?.startTag)
+                return;
+            if (rule.unless.some((p) => hasAttr(p.attr)))
+                return;
+            const insertAt = loc.startTag.endOffset - 1;
+            const after = rule.value === undefined
+                ? rule.attr.attr
+                : `${rule.attr.attr}="${escapeHtmlAttr(rule.value)}"`;
+            edits.push({ start: insertAt, end: insertAt, text: ` ${after}` });
+            pushFinding({
+                kind: 'change',
+                surface: 'html',
+                file: ctx.file,
+                line: loc.startLine,
+                ruleId: id,
+                component: tag,
+                message: rule.reason,
+                after,
+            });
+        }
+        function applySlotRemove(rule, id) {
+            for (const child of node.childNodes ?? []) {
+                if (!isElement(child))
+                    continue;
+                const slot = (child.attrs ?? []).find((a) => a.name === 'slot' && a.value === rule.from);
+                if (!slot)
+                    continue;
+                pushFinding({
+                    kind: 'warn',
+                    surface: 'html',
+                    file: ctx.file,
+                    line: child.sourceCodeLocation?.startLine,
+                    ruleId: id,
+                    component: tag,
+                    message: `the \`${rule.from}\` slot of ${tag} was removed in v2; migrate the slotted content manually`,
+                });
+            }
+        }
+        function applySlotToAttr(rule, id) {
+            if (rule.slot !== 'default')
+                return; // only default-slot text supported for now
+            if (hasAttr(rule.to.attr))
+                return; // explicit attribute wins
+            if (!loc?.startTag || !loc.endTag)
+                return;
+            const children = node.childNodes ?? [];
+            const elementChildren = children.filter((c) => isElement(c) || c.content !== undefined);
+            const line = loc.startLine;
+            if (elementChildren.length > 0) {
+                pushFinding({
+                    kind: 'dynamic',
+                    surface: 'html',
+                    file: ctx.file,
+                    line,
+                    ruleId: id,
+                    component: tag,
+                    message: `${tag} content contains markup; move the text into \`${rule.to.attr}\` manually`,
+                });
+                return;
+            }
+            const text = collapseWhitespace(children
+                .filter((c) => c.nodeName === '#text')
+                .map((c) => c.value ?? '')
+                .join(''));
+            if (text === '')
+                return;
+            // Insert the attribute just before the start tag's closing `>` and clear the content.
+            const insertAt = loc.startTag.endOffset - 1;
+            edits.push({
+                start: insertAt,
+                end: insertAt,
+                text: ` ${rule.to.attr}="${escapeHtmlAttr(text)}"`,
+            });
+            edits.push({ start: loc.startTag.endOffset, end: loc.endTag.startOffset, text: '' });
+            pushFinding({
+                kind: 'change',
+                surface: 'html',
+                file: ctx.file,
+                line,
+                ruleId: id,
+                component: tag,
+                message: `lift slotted text into \`${rule.to.attr}\``,
+                before: text,
+                after: `${rule.to.attr}="${text}"`,
+            });
+        }
+    };
+    visit(fragment);
+    if (edits.length === 0)
+        return { output: source, changed: false, findings };
+    return { output: applyEdits(source, edits), changed: true, findings };
+};