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

package/dist/manifest/registry.js

@@ -0,0 +1,102 @@
+/** camelCase prop → kebab-case attribute: `autoPlacement` → `auto-placement`. */
+export const propToAttr = (prop) => prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+/** kebab-case attribute → camelCase prop: `auto-placement` → `autoPlacement`. */
+export const attrToProp = (attr) => attr.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+/** Custom-element tag → React component name: `mds-dropdown` → `MdsDropdown`. */
+export const tagToReactName = (tag) => tag
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+/** Stencil event name → React handler prop: `mdsChange` → `onMdsChange`. */
+export const eventToReactProp = (event) => `on${event.charAt(0).toUpperCase()}${event.slice(1)}`;
+/** A stable identifier for a rule, used by `--only`/`--skip` and the report. */
+export const ruleId = (tag, rule) => {
+    switch (rule.kind) {
+        case 'propRename':
+        case 'booleanInvert':
+            return `${tag}/${rule.kind}/${rule.from.prop}`;
+        case 'propRemove':
+            return `${tag}/${rule.kind}/${rule.prop.prop}`;
+        case 'enumRemap':
+            return `${tag}/${rule.kind}/${rule.prop.prop}`;
+        case 'slotRemove':
+        case 'slotRename':
+            return `${tag}/${rule.kind}/${rule.from}`;
+        case 'slotToAttr':
+            return `${tag}/${rule.kind}/${rule.slot}`;
+        case 'ensureAttr':
+            return `${tag}/${rule.kind}/${rule.attr.prop}`;
+        case 'tagRename':
+            return `${tag}/${rule.kind}`;
+        case 'cssVarRemove':
+        case 'classReport':
+            return `${tag}/${rule.kind}/${rule.name}`;
+        case 'cssVarRename':
+        case 'cssVarSurfaceReport':
+        case 'classRename':
+        case 'partRename':
+        case 'eventRename':
+            return `${tag}/${rule.kind}/${rule.from}`;
+    }
+};
+export const getByTag = (manifest, tag) => manifest.components[tag];
+/** Lazily-built React-name → component index. */
+const reactIndexCache = new WeakMap();
+export const getByReactName = (manifest, react) => {
+    let index = reactIndexCache.get(manifest);
+    if (!index) {
+        index = new Map();
+        for (const component of Object.values(manifest.components))
+            index.set(component.react, component);
+        reactIndexCache.set(manifest, index);
+    }
+    return index.get(react);
+};
+/**
+ * The effective rule list for a component: the global per-component rules
+ * (currently `tone`) resolved against this component, followed by its own
+ * rules. Global `tone` only materialises for components that declare the
+ * referenced v2 enum set.
+ *
+ * Note: `removeDefaultSlot` is intentionally *not* expanded here — `slot="default"`
+ * lives on the projected child (any tag), not on the `mds-*` element, so each
+ * surface applies it globally by reading `manifest.global.removeDefaultSlot`.
+ */
+export const rulesForComponent = (manifest, component) => {
+    const rules = [];
+    const tone = manifest.global.tone;
+    if (tone && component.v2EnumSets?.[tone.toneSet]) {
+        const toneRule = {
+            kind: 'enumRemap',
+            prop: tone.prop,
+            map: tone.overrides?.[component.tag] ?? tone.map,
+            v2set: tone.toneSet,
+            confidence: 'review',
+        };
+        rules.push(toneRule);
+    }
+    rules.push(...component.rules);
+    return rules;
+};
+/** Resolve the v2 enum set referenced by an `enumRemap` rule, if any. */
+export const v2SetFor = (component, rule) => (rule.v2set ? component.v2EnumSets?.[rule.v2set] : undefined);
+/**
+ * The v1 → v2 tag renames of the manifest, keyed by v1 tag. Read in one lookup
+ * per element so the renames are simultaneous: `mds-pref-theme` becomes
+ * `mds-pref-mode` while `mds-pref-theme-variant` becomes `mds-pref-theme`, and
+ * neither result is looked up again.
+ */
+const tagRenameCache = new WeakMap();
+export const tagRenamesOf = (manifest) => {
+    let renames = tagRenameCache.get(manifest);
+    if (!renames) {
+        renames = new Map();
+        for (const component of Object.values(manifest.components)) {
+            const rule = component.rules.find((r) => r.kind === 'tagRename');
+            if (rule)
+                renames.set(component.tag, rule);
+        }
+        tagRenameCache.set(manifest, renames);
+    }
+    return renames;
+};

package/dist/manifest/schema.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Manifest schema: the curated, per-component description of every v1 → v2
+ * breaking change. The manifest is the single runtime artifact the transformers
+ * consume; it is self-contained (carries attr↔prop pairs, the React component
+ * name and the v2 enum sets) so a surface never has to look anything up
+ * elsewhere. It is produced semi-automatically by the generator (see
+ * `generate/diff-docs.ts`) and ratified by hand.
+ */
+/** How confident we are that a rule can be applied without human review. */
+export type Confidence = 'safe' | 'review' | 'manual';
+/** A prop identified by both of its surface spellings. */
+export interface PropId {
+    /** kebab-case attribute name, e.g. `auto-placement` (HTML). */
+    attr: string;
+    /** camelCase property / JSX prop name, e.g. `autoPlacement` (React, Angular). */
+    prop: string;
+}
+/** Category D — rename a prop, value preserved. */
+export interface PropRenameRule {
+    kind: 'propRename';
+    from: PropId;
+    to: PropId;
+    confidence: Confidence;
+    note?: string;
+}
+/** Category C — prop removed with no replacement; warn the consumer. */
+export interface PropRemoveRule {
+    kind: 'propRemove';
+    prop: PropId;
+    /** `comment`: inject an inline note next to the attribute. `delete`: drop it. */
+    strategy: 'comment' | 'delete';
+    message: string;
+}
+/** Categories A and E — remap enum literals (validated against the v2 set). */
+export interface EnumRemapRule {
+    kind: 'enumRemap';
+    prop: PropId;
+    /** `value → newValue`; a `null` target means "no v2 equivalent, migrate manually". */
+    map: Record<string, string | null>;
+    /** Name of the entry in the component's `v2EnumSets` to validate targets/literals against. */
+    v2set?: string;
+    confidence: Confidence;
+}
+/** Category B — rename a boolean prop and negate its value. */
+export interface BooleanInvertRule {
+    kind: 'booleanInvert';
+    from: PropId;
+    to: PropId;
+    oldDefault: boolean;
+    newDefault: boolean;
+    confidence: Confidence;
+}
+/** Category F — remove or rename a named slot. */
+export interface SlotRule {
+    kind: 'slotRemove' | 'slotRename';
+    from: string;
+    to?: string;
+}
+/**
+ * Category F (preferred form) — lift the text content of a slot into an
+ * attribute. v2 `mds-button` keeps reading slotted text for backward compat,
+ * but the preferred shape moves it to `label`:
+ * `<mds-button>Save</mds-button>` → `<mds-button label="Save"></mds-button>`.
+ *
+ * Only pure-text / single-expression content can be lifted; content with
+ * element children is reported for manual migration instead.
+ */
+export interface SlotToAttrRule {
+    kind: 'slotToAttr';
+    /** Slot whose content is lifted; `default` = the unnamed slot (plain text content). */
+    slot: string;
+    to: PropId;
+    confidence: Confidence;
+}
+/** Category G — rename a CSS custom property (optionally flagging a value-format change). */
+export interface CssVarRenameRule {
+    kind: 'cssVarRename';
+    /** Without the leading `--`. */
+    from: string;
+    to: string;
+    /** e.g. hex → `R G B` channels; the value cannot be migrated automatically. */
+    valueFormatChanged?: boolean;
+    /**
+     * Extra context surfaced as a flag on the definition site: the value-format
+     * details, or the fact that the v1 name was documented but never shipped
+     * (renaming it activates an override that was silently inert).
+     */
+    note?: string;
+}
+/** Category G2 — a CSS custom property was removed with no v2 replacement; usages are reported. */
+export interface CssVarRemoveRule {
+    kind: 'cssVarRemove';
+    /** Without the leading `--`. */
+    name: string;
+    message: string;
+}
+/**
+ * Category G3 (report-only). A neutral tone/primitive used as a *background* is
+ * a surface under the semantic color system, but the exact role (default /
+ * raised / overlay / sunken / muted) is contextual and often the component's own
+ * default (C2 territory), so the codemod REPORTS the site for manual migration
+ * to a `--magma-surface-*` role instead of rewriting it. "Background context" =
+ * a `background` / `background-color` property, OR a custom property whose name
+ * contains `background` (component `--mds-*-background*` tokens). CSS-only; the
+ * value is never rewritten.
+ */
+export interface CssVarSurfaceReportRule {
+    kind: 'cssVarSurfaceReport';
+    /** Without the leading `--`: the token that is a surface candidate as a background. */
+    from: string;
+    /** Optional extra guidance appended to the report message. */
+    note?: string;
+}
+/**
+ * Category J — rename a utility class of the styles package (the Tailwind
+ * design-token contract: `shadow-*`, `rounded-*`, `border-*`, `gap-*`), value
+ * preserved. `from`/`to` are the bare utility names; the surfaces match them
+ * under any variant prefixes (`hover:`, `md:`, arbitrary variants) and the
+ * important marker, and rewrite only the utility segment.
+ */
+export interface ClassRenameRule {
+    kind: 'classRename';
+    /** Bare utility name, without variant prefixes: `shadow-outline-light`. */
+    from: string;
+    to: string;
+    /** Extra context surfaced as a flag next to the rename. */
+    note?: string;
+    /**
+     * Also rename the class in CSS class selectors (`.pref-theme-dark .x`). Off
+     * for the utility classes, which a stylesheet applies with `@apply` rather
+     * than selects; on for the state classes the design system writes on
+     * `<html>`, which consumer stylesheets select.
+     */
+    selectors?: boolean;
+}
+/** Category J (report-only) — a v1 utility class with no exact v2 equivalent; usages are reported. */
+export interface ClassReportRule {
+    kind: 'classReport';
+    /** Bare utility name, without variant prefixes. */
+    name: string;
+    message: string;
+}
+/** Category H — rename a shadow part referenced in `::part()`. */
+export interface PartRenameRule {
+    kind: 'partRename';
+    from: string;
+    to: string;
+}
+/**
+ * Category K — rename the element itself. The component keeps its v1 tag as its
+ * manifest key, so every other rule of the component still matches the source
+ * as written; the surfaces rename the tag (HTML / Angular start and end tags,
+ * CSS type selectors) and the React component name (JSX tags and the named
+ * import) in the same single pass. All renames are applied at once, so a v1
+ * name that another component takes in v2 (`mds-pref-theme`) is never renamed
+ * twice.
+ */
+export interface TagRenameRule {
+    kind: 'tagRename';
+    /** v2 tag, `mds-pref-mode`. */
+    to: string;
+    /** v2 React component name, `MdsPrefMode`. */
+    toReact: string;
+}
+/** Category I — rename an event (raw event name, e.g. `mdsChange`). */
+export interface EventRenameRule {
+    kind: 'eventRename';
+    from: string;
+    to: string;
+}
+/**
+ * Behavior-preservation guard. Adds `attr` (as a shorthand boolean) to the
+ * element **only when none of the `unless` props are already present**. Used
+ * when a v2 default flips relative to v1: e.g. `mds-dropdown` auto-placement was
+ * off by default in v1 but is on in v2, so adding `disable-auto-placement` to
+ * dropdowns that never set it preserves the v1 behavior.
+ */
+export interface EnsureAttrRule {
+    kind: 'ensureAttr';
+    /** Attribute/prop to add (shorthand boolean unless `value` is set). */
+    attr: PropId;
+    /** Literal value to set (`variant="light"`); omitted → boolean shorthand. */
+    value?: string;
+    /** Skip the insertion when any of these props is already on the element. */
+    unless: PropId[];
+    confidence: Confidence;
+    /** Human-readable reason, shown in the report. */
+    reason: string;
+}
+export type Rule = PropRenameRule | PropRemoveRule | EnumRemapRule | BooleanInvertRule | SlotRule | SlotToAttrRule | CssVarRenameRule | CssVarRemoveRule | CssVarSurfaceReportRule | ClassRenameRule | ClassReportRule | PartRenameRule | EventRenameRule | TagRenameRule | EnsureAttrRule;
+export type RuleKind = Rule['kind'];
+export interface ComponentManifest {
+    /** `mds-dropdown`. */
+    tag: string;
+    /** React component name, `MdsDropdown`. */
+    react: string;
+    /** v2 enum sets referenced by this component's `enumRemap` rules, keyed by set name. */
+    v2EnumSets?: Record<string, readonly string[]>;
+    rules: Rule[];
+}
+/** Rules applied to every component (still validated per-component). */
+export interface GlobalRules {
+    /**
+     * `tone` enum remap applied to any component that has a `tone` prop. Targets
+     * are validated against each component's own v2 enum set named `toneSet`.
+     */
+    tone?: {
+        prop: PropId;
+        map: Record<string, string | null>;
+        /** Name of the per-component `v2EnumSets` entry holding that component's valid tone values. */
+        toneSet: string;
+        /**
+         * Per-tag replacement maps for components whose v2 tone set supports a
+         * closer target than the global one (e.g. `quiet → text` where `text`
+         * exists). A tag listed here uses its map *instead of* `map`.
+         */
+        overrides?: Record<string, Record<string, string | null>>;
+    };
+    /** Remove `slot="default"` everywhere (v2 uses the unnamed default slot). */
+    removeDefaultSlot?: boolean;
+    /**
+     * CSS custom-property migrations that are not tied to a single component:
+     * primitive-token renames (the `--tone-*` -> `--tone-*-seed` seed rename from
+     * A2) and report-only surface candidates (a neutral tone used as a background,
+     * migrated by hand to a `--magma-surface-*` role). CSS-only; the
+     * HTML/React/Angular surfaces ignore them.
+     */
+    cssVars?: Array<CssVarRenameRule | CssVarSurfaceReportRule>;
+    /**
+     * Utility-class migrations of the styles package (category J): the Tailwind
+     * design-token contract that changed between v1 and v2 (`shadow-*` ring
+     * family, retuned `rounded-*` scale, `border-*` widths, named `gap-*`
+     * steps). Applied to `class` / `className` values on ANY element (the
+     * classes are global, not tied to an `mds-*` component) and to `@apply` in
+     * CSS/SCSS.
+     */
+    classes?: Array<ClassRenameRule | ClassReportRule>;
+}
+export interface Manifest {
+    fromVersion: string;
+    toVersion: string;
+    global: GlobalRules;
+    /** Keyed by tag. */
+    components: Record<string, ComponentManifest>;
+}

package/dist/manifest/schema.js

@@ -0,0 +1,9 @@
+/**
+ * Manifest schema: the curated, per-component description of every v1 → v2
+ * breaking change. The manifest is the single runtime artifact the transformers
+ * consume; it is self-contained (carries attr↔prop pairs, the React component
+ * name and the v2 enum sets) so a surface never has to look anything up
+ * elsewhere. It is produced semi-automatically by the generator (see
+ * `generate/diff-docs.ts`) and ratified by hand.
+ */
+export {};

package/dist/report/diff.d.ts

@@ -0,0 +1,2 @@
+/** Produce a unified diff for two strings, or `''` when they are identical. */
+export declare const unifiedDiff: (fileName: string, before: string, after: string, context?: number) => string;

package/dist/report/diff.js

@@ -0,0 +1,95 @@
+const LARGE = 5000;
+const diffLines = (a, b) => {
+    if (a.length > LARGE || b.length > LARGE) {
+        return [
+            ...a.map((line) => ({ type: 'del', line })),
+            ...b.map((line) => ({ type: 'add', line })),
+        ];
+    }
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = length of LCS of a[i:] and b[j:]
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] =
+                a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ type: 'eq', line: a[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ type: 'del', line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ type: 'add', line: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ type: 'del', line: a[i++] });
+    while (j < m)
+        ops.push({ type: 'add', line: b[j++] });
+    return ops;
+};
+/** Produce a unified diff for two strings, or `''` when they are identical. */
+export const unifiedDiff = (fileName, before, after, context = 3) => {
+    if (before === after)
+        return '';
+    const ops = diffLines(before.split('\n'), after.split('\n'));
+    // Indices of ops that are changes (non-eq).
+    const changeIdx = ops.map((op, idx) => (op.type === 'eq' ? -1 : idx)).filter((idx) => idx >= 0);
+    if (changeIdx.length === 0)
+        return '';
+    const ranges = [];
+    for (const idx of changeIdx) {
+        const start = Math.max(0, idx - context);
+        const end = Math.min(ops.length - 1, idx + context);
+        const last = ranges[ranges.length - 1];
+        if (last && start <= last.end + 1)
+            last.end = Math.max(last.end, end);
+        else
+            ranges.push({ start, end });
+    }
+    const lines = [`--- a/${fileName}`, `+++ b/${fileName}`];
+    for (const range of ranges) {
+        let aStart = 0;
+        let bStart = 0;
+        for (let k = 0; k < range.start; k++) {
+            if (ops[k].type !== 'add')
+                aStart++;
+            if (ops[k].type !== 'del')
+                bStart++;
+        }
+        let aLen = 0;
+        let bLen = 0;
+        const body = [];
+        for (let k = range.start; k <= range.end; k++) {
+            const op = ops[k];
+            if (op.type === 'eq') {
+                body.push(` ${op.line}`);
+                aLen++;
+                bLen++;
+            }
+            else if (op.type === 'del') {
+                body.push(`-${op.line}`);
+                aLen++;
+            }
+            else {
+                body.push(`+${op.line}`);
+                bLen++;
+            }
+        }
+        lines.push(`@@ -${aStart + 1},${aLen} +${bStart + 1},${bLen} @@`);
+        lines.push(...body);
+    }
+    return lines.join('\n');
+};

package/dist/report/reporter.d.ts

@@ -0,0 +1,27 @@
+import { type FileReport, type Report, type Surface } from './types.js';
+export interface ParseError {
+    file: string;
+    surface: Surface;
+    message: string;
+}
+export interface ReporterMeta {
+    fromVersion: string;
+    toVersion: string;
+    dryRun: boolean;
+}
+export declare class Reporter {
+    private readonly meta;
+    private readonly files;
+    private readonly errors;
+    constructor(meta: ReporterMeta);
+    addFile(report: FileReport): void;
+    addError(error: ParseError): void;
+    build(): Report;
+    private countKind;
+    /** Plain JSON report (errors included under a top-level key). */
+    toJSON(report: Report): string;
+    renderHuman(report: Report, options?: {
+        showDiff: boolean;
+    }): string;
+}
+export declare const exitCode: (report: Report) => number;

package/dist/report/reporter.js

@@ -0,0 +1,118 @@
+/**
+ * Collects per-file results and renders them for humans (diff + grouped
+ * findings + summary table) and for machines (JSON). Exit-code policy: `0` on
+ * success (with or without warnings/flags/dynamic notes), `2` if any file
+ * failed to parse.
+ */
+import chalk from 'chalk';
+export class Reporter {
+    meta;
+    files = [];
+    errors = [];
+    constructor(meta) {
+        this.meta = meta;
+    }
+    addFile(report) {
+        this.files.push(report);
+    }
+    addError(error) {
+        this.errors.push(error);
+    }
+    build() {
+        const summary = {
+            filesScanned: this.files.length + this.errors.length,
+            filesChanged: this.files.filter((f) => f.changed).length,
+            changes: this.countKind('change'),
+            warnings: this.countKind('warn'),
+            flags: this.countKind('flag'),
+            dynamic: this.countKind('dynamic'),
+            errors: this.errors.length,
+        };
+        return {
+            fromVersion: this.meta.fromVersion,
+            toVersion: this.meta.toVersion,
+            dryRun: this.meta.dryRun,
+            files: this.files,
+            summary,
+        };
+    }
+    countKind(kind) {
+        return this.files.reduce((total, file) => total + file.findings.filter((f) => f.kind === kind).length, 0);
+    }
+    /** Plain JSON report (errors included under a top-level key). */
+    toJSON(report) {
+        return JSON.stringify({ ...report, parseErrors: this.errors }, null, 2);
+    }
+    renderHuman(report, options = { showDiff: true }) {
+        const out = [];
+        for (const file of report.files) {
+            if (!file.changed && file.findings.length === 0)
+                continue;
+            out.push(chalk.bold.underline(file.file));
+            if (options.showDiff && file.diff)
+                out.push(colorizeDiff(file.diff));
+            for (const finding of file.findings)
+                out.push(`  ${renderFinding(finding)}`);
+            out.push('');
+        }
+        for (const error of this.errors) {
+            out.push(`${chalk.red('✖ parse error')} ${chalk.bold(error.file)}: ${error.message}`);
+        }
+        if (this.errors.length)
+            out.push('');
+        out.push(renderSummary(report));
+        return out.join('\n');
+    }
+}
+export const exitCode = (report) => (report.summary.errors > 0 ? 2 : 0);
+const KIND_LABEL = {
+    change: (s) => chalk.green(s),
+    warn: (s) => chalk.yellow(s),
+    flag: (s) => chalk.yellow(s),
+    dynamic: (s) => chalk.magenta(s),
+};
+const KIND_GLYPH = {
+    change: '✓',
+    warn: '⚠',
+    flag: '⚠',
+    dynamic: '✋',
+};
+const renderFinding = (finding) => {
+    const color = KIND_LABEL[finding.kind];
+    const loc = finding.line ? chalk.dim(`:${finding.line}`) : '';
+    const rule = finding.ruleId ? chalk.dim(` [${finding.ruleId}]`) : '';
+    const head = `${color(KIND_GLYPH[finding.kind])}${loc} ${finding.message}${rule}`;
+    if (finding.before !== undefined && finding.after !== undefined) {
+        return `${head}\n      ${chalk.red(finding.before)} ${chalk.dim('→')} ${chalk.green(finding.after)}`;
+    }
+    return head;
+};
+const colorizeDiff = (diff) => diff
+    .split('\n')
+    .map((line) => {
+    if (line.startsWith('+++') || line.startsWith('---'))
+        return chalk.bold(line);
+    if (line.startsWith('@@'))
+        return chalk.cyan(line);
+    if (line.startsWith('+'))
+        return chalk.green(line);
+    if (line.startsWith('-'))
+        return chalk.red(line);
+    return chalk.dim(line);
+})
+    .join('\n');
+const renderSummary = (report) => {
+    const s = report.summary;
+    const mode = report.dryRun ? chalk.yellow('dry-run (no files written)') : chalk.green('write');
+    const parts = [
+        `${chalk.bold('Magma codemods')} ${report.fromVersion} → ${report.toVersion}  ${chalk.dim(`[${mode}]`)}`,
+        `  files scanned : ${s.filesScanned}`,
+        `  files changed : ${s.filesChanged}`,
+        `  changes       : ${chalk.green(String(s.changes))}`,
+        `  warnings      : ${s.warnings ? chalk.yellow(String(s.warnings)) : '0'}`,
+        `  flags         : ${s.flags ? chalk.yellow(String(s.flags)) : '0'}`,
+        `  dynamic (manual): ${s.dynamic ? chalk.magenta(String(s.dynamic)) : '0'}`,
+        `  parse errors  : ${s.errors ? chalk.red(String(s.errors)) : '0'}`,
+    ];
+    return parts.join('\n');
+};

package/dist/report/types.d.ts

@@ -0,0 +1,51 @@
+/** Report data model shared by the transformers, the reporter and the JSON output. */
+export type Surface = 'html' | 'react' | 'angular' | 'css';
+export type FindingKind = 
+/** A transformation that was applied (or would be, in dry-run). */
+'change'
+/** A removed prop: an inline comment is injected and the consumer warned. */
+ | 'warn'
+/** Applied but needs a look: enum literal outside the v2 set, CSS value-format change. */
+ | 'flag'
+/** Dynamic / unanalyzable usage the tool cannot rewrite safely — manual action required. */
+ | 'dynamic';
+export interface Finding {
+    kind: FindingKind;
+    surface: Surface;
+    file: string;
+    /** 1-based line, when known. */
+    line?: number;
+    column?: number;
+    /** The rule that produced (or would have produced) this finding. */
+    ruleId?: string;
+    /** Component tag, e.g. `mds-dropdown`. */
+    component?: string;
+    message: string;
+    before?: string;
+    after?: string;
+}
+export interface FileReport {
+    file: string;
+    surface: Surface;
+    changed: boolean;
+    findings: Finding[];
+    /** Unified diff of the file, present when `changed` and source/output are available. */
+    diff?: string;
+}
+export interface ReportSummary {
+    filesScanned: number;
+    filesChanged: number;
+    changes: number;
+    warnings: number;
+    flags: number;
+    dynamic: number;
+    /** Files that failed to parse. */
+    errors: number;
+}
+export interface Report {
+    fromVersion: string;
+    toVersion: string;
+    dryRun: boolean;
+    files: FileReport[];
+    summary: ReportSummary;
+}

package/dist/report/types.js

@@ -0,0 +1,2 @@
+/** Report data model shared by the transformers, the reporter and the JSON output. */
+export {};

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