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

package/README.md

@@ -0,0 +1,193 @@
+# @maggioli-design-system/magma-codemods
+
+Codemods to migrate consumer code of [`@maggioli-design-system/magma`](https://www.npmjs.com/package/@maggioli-design-system/magma)
+from **v1** to **v2**. They rewrite HTML, React (JSX/TSX), Angular templates (external `.html` and inline
+`@Component({ template })`) and CSS/SCSS, applying the breaking changes automatically and reporting the cases that
+need a human decision.
+
+ESM package, Node ≥ 22.
+
+## Usage
+
+```bash
+npx @maggioli-design-system/magma-codemods --path ./src
+```
+
+By default the tool runs in **dry-run** (prints a coloured diff + a summary, writes nothing). Pass `--write` to
+apply the changes in place.
+
+```
+--framework <react|angular|html|css|auto>   surface (default: auto, inferred from the extension)
+--path <file|dir>                            file or directory to scan (repeatable; positional args also work)
+--dry-run                                    print a diff and report, write nothing (DEFAULT)
+--write                                      apply changes in place
+--force                                      allow --write on a dirty git working tree
+--ignore <glob>                              extra ignore globs (repeatable)
+--report <path>                              write the JSON report
+--only <ruleId,...> / --skip <ruleId,...>    run/skip specific rules (see the ids in the report)
+--manifest <path>                            override the bundled manifest (JSON)
+-h, --help
+```
+
+Notes:
+
+- `auto` maps `.css/.scss → css`, `.tsx/.jsx → react`, `.ts → Angular inline templates`, `.html → html`. For
+  **Angular external templates** (`.html`), pass `--framework angular`.
+- `--write` refuses to run on a dirty git working tree unless `--force`, so the undo is always `git checkout`.
+- `node_modules`, `dist`, `.git`, `build`, `.next` and `coverage` are ignored by default.
+
+## Migration matrix
+
+| #   | Category                        | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Confidence                    |
+| --- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| A   | Enum remap (`tone`)             | `ghost → outline`, `quiet → weak`; on the three components whose v2 tone set gained `text` (`mds-button`, `mds-radial-menu`, `mds-radial-menu-item`) the documented intent applies instead: `quiet → text`. Validated against each component's v2 set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | safe with validation          |
+| B   | Boolean inversion               | rename + negate value: `arrow → hideArrow` (dropdown **and tooltip**), `autoPlacement → disableAutoPlacement`, `backdrop → hideBackdrop`, `cockade → hideCockade`, `showDownloadedIcon → hideDownloadedIcon`, … plus the curated pairs the name heuristic cannot see: `closable → disableClose`, `visible → dismissed`, and the `mds-calendar` set inverted after the docs snapshot (#685): `rangePicker → singlePicker`, `showPreviousButton → hidePreviousButton`, `showNextButton → hideNextButton`, `showPreselection → hidePreselection`                                                                                                                                                                                                 | safe                          |
+| C   | Prop removal                    | warn + inline comment (HTML) / report (JSX, Angular): e.g. `mds-button hasText`, `mds-modal animating`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | report                        |
+| D   | Prop rename                     | `mds-label labelAction → label`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | curated                       |
+| E   | Misc enum shifts                | remap or flag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | mixed                         |
+| F   | `slot="default"` removal        | drop the attribute (v2 uses the unnamed default slot)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | safe                          |
+| F2  | Slot → attribute                | lift slotted text into an attribute: `Save` → `label="Save"` (`label={expr}` / `[label]="expr"` for dynamic). Preferred form on `mds-button` (v2 still reads slotted text); **mandatory** on `mds-breadcrumb-item` and `mds-tab-item`, whose v2 render dropped the slot entirely. Element/mixed content → reported                                                                                                                                                                                                                                                                                                                                                                                                                            | text: safe · markup: manual   |
+| F3  | Removed named slot              | report children using a slot dropped in v2: `mds-push-notification` `slot="top"` / `slot="bottom"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | report                        |
+| G   | CSS custom property rename      | `--mds-*-ghost-* → --mds-*-outline-*`, `--mds-*-color → --mds-*-color-rgb` (value hex → `R G B` flagged), plus the curated renames the docs diff saw as removals: `--mds-banner-gap → --mds-banner-content-gap`, `--mds-header-backdrop-filter → --mds-header-backdrop-blur-strength` (both value-flagged), the `shodow → shadow` / triple-dash typo fixes on `mds-filter(-item)`, `--mds-tab-item-transition-* → --mds-tab-transition-*`, and the v1 typo'd names corrected in v2 (#566, plus #328's property registration): `--mds-video-wall-noise-fitler → --mds-video-wall-noise-filter`, `--mds-file-preview-icon-bacground → --mds-file-preview-icon-background`, `--mds-stepper-bar-item-duaration → --mds-stepper-bar-item-duration` | name: safe · value: manual    |
+| G2  | CSS custom property removal     | warn on definitions/`var()` references of the ~11 properties removed with no replacement (e.g. `--mds-entity-shadow`, `--mds-table-cell-*`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | report                        |
+| G3  | Semantic color migration (#576) | seed rename `--tone-<family> → --tone-<family>-seed` (A2), rewritten; plus report-only surface candidates: a neutral tone (bare token or any scale step) used as a _background_ (a `background`/`background-color` property, or a `--mds-*-background*` token) is reported for manual migration to a `--magma-surface-*` role (the exact role, default/raised/overlay, is contextual)                                                                                                                                                                                                                                                                                                                                                         | seed: safe · surface: report  |
+| H   | Shadow part rename              | rename in `::part()` selectors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | safe                          |
+| I   | Event rename                    | declared in the manifest schema, but **not implemented by any surface yet** — no event was renamed between v1.12 and v2.0.0-beta, so no rule currently exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | n/a                           |
+| J   | Utility-class migration         | the styles-package Tailwind contract that changed between v1 and v2: the `shadow-outline-*` ring family → `shadow-ring-*`, the retuned `rounded-*` / `border-*` / named `gap-*` scales. Value-exact renames are rewritten; combos with no v2 token are reported (see below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | rename: safe · report: manual |
+| K   | Tag rename (mode vs theme)      | the light / dark / system control `mds-pref-theme` becomes `mds-pref-mode` (#702): the tag in HTML / Angular (start and end tag) and in CSS type selectors, the React component in JSX and in the named import from `magma-react` (with its other references, e.g. `typeof MdsPrefTheme`), the mode classes `pref-theme-{light,dark,system}` -> `pref-mode-*` in markup AND in CSS selectors, `--magma-pref-theme` -> `--magma-pref-mode`, the overlay properties and class `--mds-pref-theme-overlay-*` / `.mds-pref-theme-overlay` -> `mds-pref-mode-overlay`. Code written against a v2 beta also gets `mds-pref-theme-variant(-item)` -> `mds-pref-theme(-item)` and `--magma-pref-theme-name` -> `--magma-pref-theme`, applied in the same pass| safe (run once)               |
+
+The bundled manifest is built by diffing the two `documentation.json` builds (`manifest.generated.ts`) with curated
+corrections layered on top in `src/manifest/manifest.ts`.
+
+### Behaviour guards (preserving v1 defaults)
+
+Some inversions also flip the _default_ behaviour. On `mds-dropdown`, v1 had auto-placement **off** by default
+(`auto-placement` opt-in) while v2 has it **on** (`disable-auto-placement` opt-out). To keep the v1 behaviour, the
+codemod adds `disable-auto-placement` to dropdowns that set neither prop:
+
+| Input                                     | Output                                              |
+| ----------------------------------------- | --------------------------------------------------- |
+| `<mds-dropdown>` (auto-placement was off) | `<mds-dropdown disable-auto-placement>` (stays off) |
+| `<mds-dropdown auto-placement>` (was on)  | `<mds-dropdown>` (stays on — v2 default)            |
+
+(`mds-tooltip`'s auto-placement default did not change, so no guard is applied there. Likewise `mds-calendar`'s
+`show-preselection → hide-preselection`: the preselection area already appeared automatically whenever the slot had
+content, and still does, so dropping the v1 opt-in flips nothing.)
+
+The same guard covers other default flips (same prop, new default — invisible to the docs diff):
+
+| Component                    | v1 default        | v2 default        | Guard                  |
+| ---------------------------- | ----------------- | ----------------- | ---------------------- |
+| `mds-push-notification-item` | `deletable` on    | off               | adds `deletable`       |
+| `mds-banner`                 | `variant="light"` | `primary`         | adds `variant="light"` |
+| `mds-label`                  | no truncation     | `truncate="word"` | adds `truncate="none"` |
+
+(`mds-emoji`'s default `name` changed `hexabot → mia`; deliberately not guarded — treat it as branding.)
+
+### Utility-class migration (J)
+
+The styles package's Tailwind token contract changed between v1 and v2; the codemod rewrites the classes whose
+**value survives under a new name** (verified value-by-value against the two token sets) and reports the rest. It
+runs on `class` attributes of **any** element (HTML, Angular templates, inline templates), `className`/`class` in
+JSX — including string literals inside `clsx()`/ternaries — `[class.x]`/`[ngClass]`/`[class]` bindings in Angular,
+and `@apply` in CSS/SCSS. Variant prefixes (`hover:`, `md:`, arbitrary variants) and important markers are
+preserved; only the utility segment is rewritten.
+
+| Family             | Renames (value-exact)                                                                                                                                                                                     | Reported (no exact v2 token)                                                                                                                                                      | Unchanged                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Shadows            | `shadow-sm → shadow-xs`, `shadow-sm-sharp → shadow-xs-sharp`, `shadow-inner → shadow-inset-sm` (near-exact, flagged)                                                                                      | —                                                                                                                                                                                 | `shadow`, `shadow-sharp`, `shadow-md/lg/xl/2xl(-sharp)`, `shadow-none` |
+| Ring family (#641) | `shadow-outline → shadow-ring`, `-outline-50 → -ring-2`, `-outline-light → -ring-weak`, `-outline-light-50 → -ring-weak-2`, `-outline-strong-50 → -ring-strong-2`, `-outline-strong-100 → -ring-strong-4` | `-outline-75/-100`, `-outline-light-75/-100`, `-outline-strong(-75)` — ⚠ v2 reuses the name `shadow-outline-strong` for a **different** shadow, so leaving it is a silent restyle | —                                                                      |
+| Radius             | `rounded → rounded-3xs`, `md → 2xs`, `lg → xs`, `xl → md`, `2xl → lg`, `3xl → 2xl` — expanded over every corner/side variant (`rounded-t-*`, `rounded-tl-*`, …)                                           | `rounded-sm` (2px; the v2 scale starts at 4px, and v2 reuses `rounded-sm` for 10px)                                                                                               | `rounded-none`, `rounded-full`                                         |
+| Border width       | `border-md → border-sm`, `border-lg → border-200`, `border-xl → border-800` (side variants included)                                                                                                      | —                                                                                                                                                                                 | bare `border`, numeric steps                                           |
+| Gap                | bare `gap`(`-x`/`-y`) `→ gap-lg` (flagged: skippable if it is a hand-written class), `gap-3xl → gap-2000`                                                                                                 | —                                                                                                                                                                                 | `gap-xs`…`gap-2xl`, numeric steps                                      |
+
+Caveats:
+
+- **Run it once.** The radius scale shift is a chain (`rounded-xl → rounded-md` while `rounded-md → rounded-2xs`):
+  a single run is single-pass and never cascades, but a second run over already-migrated code double-shifts it.
+  The `--write` dirty-git-tree guard is your friend here.
+- Numeric steps (`p-400`, `gap-200`, `border-50`, `h-*`, `w-*`, typography, screens) kept their values everywhere
+  — no rules, nothing to do.
+- The **generic Tailwind 3 → 4 migration** (config → CSS-first `@theme`, renamed core utilities like `shadow-sm`'s
+  own TW-default meaning, `outline-none`, …) is Tailwind's own upgrade guide's business, not this codemod's: only
+  the magma token contract is covered.
+
+### Mode vs theme (K)
+
+v1 had one colour-preference control, `mds-pref-theme`, and it set the **mode** (light / dark / system). v2 calls
+it `mds-pref-mode` and gives the name `mds-pref-theme` to the **named theme** chooser (`default`, `business`, ...),
+which v1 never had. The swap is silent: a v1 page upgraded without the codemod renders the theme chooser where the
+mode control was, with no error.
+
+- **Run it once.** Every rename is looked up by the name as written, so one run is safe even on code that mixes a
+  v1 `<mds-pref-theme>` with a beta `<mds-pref-theme-variant>`. A second run over migrated code turns the v2 theme
+  chooser into a mode control.
+- **The stored preference needs no codemod**: v2 moves a v1 `localStorage.mdsPrefTheme` (`light` / `dark` /
+  `system`) to `mdsPrefMode` on first load, before any control reads it.
+- **Imperative code is not rewritten** (as everywhere): `querySelector('mds-pref-theme')`,
+  `classList.contains('pref-theme-dark')`, `getPropertyValue('--magma-pref-theme')`, a `mdsPrefChange` listener
+  that compares `detail.preference` with `'theme-mode'` (v2: `'mode'`). Search your scripts for `pref-theme`.
+- **Beta only, not covered**: the events `mdsPrefThemeVariantChange` / `mdsPrefThemeVariantItemSelect` (v2:
+  `mdsPrefThemeChange` / `mdsPrefThemeItemSelect`), the `pref-theme-name-<name>` class (v2: `pref-theme-<name>`)
+  and `'theme-variant'` in `mdsPrefChange` (v2: `'theme'`).
+
+## What it cannot rewrite (reported, not changed)
+
+These are surfaced under the **dynamic / manual** category in the report:
+
+- React **spread props** (`<MdsButton {...props} />`), aliased components, computed prop names.
+- Dynamic enum values (`tone={expr}` / `[tone]="expr"`).
+- **Dynamic class lists**: a `className` template literal with `${…}` holes that mentions a migrated utility class
+  is reported (a hole can split a token), and an `[ngClass]="expr"` whose expression carries no string literals is
+  silently out of reach — only the quoted class strings inside the expression are rewritten.
+- Slot content that contains **markup** (e.g. `<mds-icon>` inside `mds-button`).
+- Inline templates / HTML in template literals that contain `${…}` interpolation.
+- Angular `@Component({ host })` bindings are intentionally left untouched (rewriting a consumer component's own
+  host with `mds-*` rules is rarely correct).
+
+Out of scope entirely (all surfaces work on markup/templates only):
+
+- **Imperative code**: `el.backdrop = false`, `setAttribute('cockade', …)`, `addEventListener('mdsX', …)`
+  in plain JS/TS is never rewritten or reported.
+- **`updateLang()` removal**: v2 removed the public `updateLang()` method from every localized component —
+  components now react automatically when `<html lang>` changes (or via `mds-pref-language`). Calls like
+  `el.updateLang()` live in imperative code, which these codemods do not scan: delete them by hand, no
+  replacement is needed. Likewise, per-element `lang` overrides on `mds-*` hosts are no longer honored
+  (the language is page-wide, driven by `<html lang>`), but flagging every `lang` attribute in templates
+  would be noise, so no rule reports it.
+- **`eventRename`** exists in the manifest schema but no surface implements it — no event was renamed
+  between v1.12 and v2.0.0-beta, so no rule exists today. Implement it before the first real event rename.
+
+## Development
+
+```bash
+npx nx run codemod:build      # tsc → dist/
+npx nx run codemod:test       # jest (ESM)
+```
+
+### Regenerating the manifest from the docs
+
+```bash
+# v2 docs come from a `dev` build; v1 docs from a one-off build of `support/v1.x` in a worktree.
+FROM_VERSION=1.12.0 TO_VERSION=2.0.0 \
+  npm run generate.candidate -- <v1 documentation.json> <v2 documentation.json> src/manifest/manifest.candidate.json
+```
+
+Review the candidate and merge confirmed rules into `src/manifest/manifest.ts`.
+
+Caveats when producing the two `documentation.json`:
+
+- A docs-only build (`stencil docs`) on `support/v1.x` does **not** extract the `styles` section (the CSS
+  `@prop` annotations), so every `cssVarRename` would silently drop from the candidate. Use a full
+  `npm run build`, or inject the `styles` arrays from the `@prop` comments before diffing.
+- Both builds need the generated fixtures first: `npm run build.icons` (v1 also needs
+  `npm run storybook.version`).
+
+## Release
+
+Two dedicated, independent GitHub Actions workflows (not part of the shared semantic-release flow):
+
+- **`codemods-ci.yml`** — build + test, on push to `dev` and on pull requests touching `projects/codemod/**`.
+- **`codemods-publish.yml`** — manual (`workflow_dispatch`): build + test → bump (`patch|minor|major|pre*`,
+  with a selectable prerelease id) → `npm publish` via OIDC trusted publishing → push the tag
+  `magma-codemods@<version>`. No commit is pushed to `main` (tag-only). Run it with `dry-run: true` first.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper around {@link runMigration}. Dry-run is the default; pass
+ * `--write` to apply changes (refused on a dirty git tree unless `--force`).
+ */
+import arg from 'arg';
+import chalk from 'chalk';
+import { exitCode, runMigration } from './index.js';
+const HELP = `magma-codemods — migrate @maggioli-design-system/magma consumer code from v1 to v2
+
+Usage:
+  npx @maggioli-design-system/magma-codemods --path ./src [options]
+
+Options:
+  --framework <react|angular|html|css|auto>   surface (default: auto, inferred by extension)
+  --path <file|dir>                            file or directory to scan (repeatable; positional args also work)
+  --dry-run                                    print a diff and report, write nothing (DEFAULT)
+  --write                                      apply changes in place
+  --force                                      allow --write on a dirty git working tree
+  --ignore <glob>                              extra ignore globs (repeatable)
+  --report <path>                              write the JSON report
+  --only <ruleId,...>                          run only these rules
+  --skip <ruleId,...>                          skip these rules
+  --manifest <path>                            override the bundled manifest (JSON)
+  -h, --help                                   show this help
+`;
+const split = (value) => value
+    ?.split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+const main = async () => {
+    const args = arg({
+        '--framework': String,
+        '--path': [String],
+        '--write': Boolean,
+        '--dry-run': Boolean,
+        '--force': Boolean,
+        '--ignore': [String],
+        '--report': String,
+        '--only': String,
+        '--skip': String,
+        '--manifest': String,
+        '--help': Boolean,
+        '-h': '--help',
+    });
+    if (args['--help']) {
+        console.log(HELP);
+        return 0;
+    }
+    const paths = [...(args['--path'] ?? []), ...args._];
+    if (paths.length === 0) {
+        console.error(chalk.red('Nothing to do: pass at least one --path (or a positional path).\n'));
+        console.log(HELP);
+        return 2;
+    }
+    const { report, reporter } = await runMigration({
+        paths,
+        framework: args['--framework'] ?? 'auto',
+        write: args['--write'] === true,
+        force: args['--force'] === true,
+        ignore: args['--ignore'],
+        only: split(args['--only']),
+        skip: split(args['--skip']),
+        manifestPath: args['--manifest'],
+        reportPath: args['--report'],
+    });
+    console.log(reporter.renderHuman(report, { showDiff: true }));
+    return exitCode(report);
+};
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exitCode = 2;
+});

package/dist/generate/diff-docs.d.ts

@@ -0,0 +1,36 @@
+import { type ComponentManifest, type Manifest } from '../manifest/schema.js';
+export interface DocsValue {
+    value?: string;
+    type: string;
+}
+export interface DocsProp {
+    name: string;
+    attr?: string;
+    type: string;
+    values?: DocsValue[];
+    default?: string;
+}
+export interface DocsComponent {
+    tag: string;
+    props?: DocsProp[];
+    styles?: {
+        name: string;
+    }[];
+    parts?: {
+        name: string;
+    }[];
+    slots?: {
+        name: string;
+    }[];
+    events?: {
+        event: string;
+    }[];
+}
+export interface JsonDocs {
+    components: DocsComponent[];
+}
+export declare const diffComponent: (v1: DocsComponent, v2: DocsComponent) => ComponentManifest;
+export declare const generateCandidateManifest: (v1: JsonDocs, v2: JsonDocs, opts?: {
+    fromVersion?: string;
+    toVersion?: string;
+}) => Manifest;

package/dist/generate/diff-docs.js

@@ -0,0 +1,180 @@
+/**
+ * Generate a **candidate** manifest by diffing two Stencil `documentation.json`
+ * payloads (v1 and v2). The deterministic outputs — attr↔prop pairs, React
+ * names, the per-component v2 enum sets — are reliable; the pairing heuristics
+ * (boolean inversion, CSS var renames, part/event renames) are best-effort
+ * candidates marked `review`/`manual` for a human to ratify. The runtime
+ * `manifest.ts` is then maintained by merging this candidate's output.
+ */
+import { propToAttr, tagToReactName } from '../manifest/registry.js';
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+// Stencil emits `boolean | undefined` for optional props, so match on the union members.
+const isBool = (p) => p.type.split('|').some((t) => t.trim() === 'boolean');
+const enumValues = (p) => {
+    const values = (p.values ?? [])
+        .filter((v) => v.type === 'string' && typeof v.value === 'string')
+        .map((v) => v.value);
+    return values.length > 1 ? values : undefined;
+};
+const propId = (p) => ({ attr: p.attr ?? propToAttr(p.name), prop: p.name });
+const byName = (items) => new Map(items.map((i) => [i.name, i]));
+const setEq = (a, b) => a.length === b.length && a.every((v) => b.includes(v));
+/** Find the v2 boolean prop that looks like the inverted form of a removed v1 prop. */
+const findInverted = (removed, addedBool) => {
+    const name = removed.name;
+    const negated = (base) => [
+        `hide${cap(base)}`,
+        `disable${cap(base)}`,
+        `no${cap(base)}`,
+    ];
+    const candidates = negated(name);
+    // v1 `showX` → v2 `hideX`: the `show` prefix drops, the negation flips.
+    const shown = name.replace(/^show([A-Z])/, (_, c) => c.toLowerCase());
+    if (shown !== name)
+        candidates.push(...negated(shown));
+    // v1 already negated (e.g. `hideArrow` → v2 `arrow`): stripping the prefix flips the polarity.
+    // (`show` is intentionally not stripped here: `showX` → `x` keeps the polarity, so it is not an inversion.)
+    const stripped = name.replace(/^(hide|disable|no)([A-Z])/, (_, __, c) => c.toLowerCase());
+    if (stripped !== name)
+        candidates.push(stripped);
+    return addedBool.find((a) => candidates.includes(a.name));
+};
+export const diffComponent = (v1, v2) => {
+    const v1Props = byName(v1.props ?? []);
+    const v2Props = byName(v2.props ?? []);
+    const removedProps = [...v1Props.values()].filter((p) => !v2Props.has(p.name));
+    const addedProps = [...v2Props.values()].filter((p) => !v1Props.has(p.name));
+    const addedBool = addedProps.filter(isBool);
+    const usedAdded = new Set();
+    const rules = [];
+    // Boolean inversion (B).
+    for (const r of removedProps.filter(isBool)) {
+        const a = findInverted(r, addedBool.filter((p) => !usedAdded.has(p.name)));
+        if (a) {
+            usedAdded.add(a.name);
+            rules.push({
+                kind: 'booleanInvert',
+                from: propId(r),
+                to: propId(a),
+                oldDefault: r.default === 'true',
+                newDefault: a.default === 'true',
+                confidence: 'review',
+            });
+        }
+    }
+    // Enum changes on props present in both (A/E).
+    const v2EnumSets = {};
+    for (const [name, v2p] of v2Props) {
+        const v2set = enumValues(v2p);
+        if (v2set)
+            v2EnumSets[name] = v2set;
+        const v1p = v1Props.get(name);
+        if (!v1p)
+            continue;
+        const v1set = enumValues(v1p);
+        if (v1set && v2set && !setEq(v1set, v2set)) {
+            const removedValues = v1set.filter((v) => !v2set.includes(v));
+            if (removedValues.length) {
+                rules.push({
+                    kind: 'enumRemap',
+                    prop: propId(v2p),
+                    map: Object.fromEntries(removedValues.map((v) => [v, null])),
+                    v2set: name,
+                    confidence: 'manual',
+                });
+            }
+        }
+    }
+    // Removed props with no inverted pair → removal (C).
+    const invertedFromNames = new Set(rules.flatMap((rule) => (rule.kind === 'booleanInvert' ? [rule.from.prop] : [])));
+    for (const r of removedProps) {
+        if (invertedFromNames.has(r.name))
+            continue;
+        rules.push({
+            kind: 'propRemove',
+            prop: propId(r),
+            strategy: 'comment',
+            message: `\`${r.name}\` was removed in v2; migrate manually.`,
+        });
+    }
+    // CSS custom properties: renames (G) and plain removals (G2).
+    const v2Styles = new Set((v2.styles ?? []).map((s) => s.name));
+    const v1Styles = (v1.styles ?? []).map((s) => s.name);
+    for (const name of v1Styles) {
+        if (v2Styles.has(name))
+            continue;
+        const base = name.slice(2); // strip leading --
+        if (v2Styles.has(`${name}-rgb`)) {
+            rules.push({ kind: 'cssVarRename', from: base, to: `${base}-rgb`, valueFormatChanged: true });
+        }
+        else if (name.includes('ghost') && v2Styles.has(name.replace('ghost', 'outline'))) {
+            rules.push({
+                kind: 'cssVarRename',
+                from: base,
+                to: name.replace('ghost', 'outline').slice(2),
+            });
+        }
+        else {
+            rules.push({
+                kind: 'cssVarRemove',
+                name: base,
+                message: `\`${name}\` was removed in v2 with no replacement; migrate manually.`,
+            });
+        }
+    }
+    // Named slots removed in v2 (F). The default slot is handled by the global rule.
+    const v2Slots = new Set((v2.slots ?? []).map((s) => s.name));
+    for (const { name } of v1.slots ?? []) {
+        if (name === '' || name === 'default' || v2Slots.has(name))
+            continue;
+        rules.push({ kind: 'slotRemove', from: name });
+    }
+    // Shadow parts (H) and events (I): pair when exactly one was removed and one added.
+    pairRename((v1.parts ?? []).map((p) => p.name), (v2.parts ?? []).map((p) => p.name), (from, to) => rules.push({ kind: 'partRename', from, to }));
+    pairRename((v1.events ?? []).map((e) => e.event), (v2.events ?? []).map((e) => e.event), (from, to) => rules.push({ kind: 'eventRename', from, to }));
+    const component = { tag: v2.tag, react: tagToReactName(v2.tag), rules };
+    if (Object.keys(v2EnumSets).length)
+        component.v2EnumSets = v2EnumSets;
+    return component;
+};
+const pairRename = (v1, v2, emit) => {
+    const removed = v1.filter((n) => !v2.includes(n));
+    const added = v2.filter((n) => !v1.includes(n));
+    if (removed.length === 1 && added.length === 1)
+        emit(removed[0], added[0]);
+};
+export const generateCandidateManifest = (v1, v2, opts = {}) => {
+    const v1ByTag = new Map(v1.components.map((c) => [c.tag, c]));
+    const components = {};
+    let hasTone = false;
+    let hasDefaultSlot = false;
+    for (const v2c of v2.components) {
+        const v1c = v1ByTag.get(v2c.tag);
+        if (!v1c)
+            continue; // new component, nothing to migrate
+        const candidate = diffComponent(v1c, v2c);
+        if (candidate.rules.length || candidate.v2EnumSets)
+            components[v2c.tag] = candidate;
+        if ((v2c.props ?? []).some((p) => p.name === 'tone'))
+            hasTone = true;
+        if ((v1c.slots ?? []).some((s) => s.name === 'default'))
+            hasDefaultSlot = true;
+    }
+    return {
+        fromVersion: opts.fromVersion ?? 'unknown',
+        toVersion: opts.toVersion ?? 'unknown',
+        global: {
+            ...(hasTone
+                ? {
+                    tone: {
+                        prop: { attr: 'tone', prop: 'tone' },
+                        map: { ghost: 'outline', quiet: 'weak' },
+                        toneSet: 'tone',
+                    },
+                }
+                : {}),
+            removeDefaultSlot: hasDefaultSlot,
+        },
+        components,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type Manifest } from './manifest/schema.js';
+import { Reporter } from './report/reporter.js';
+import { type Report, type Surface } from './report/types.js';
+import { type TransformContext, type TransformResult } from './surfaces/shared/transform.js';
+export type Framework = 'react' | 'angular' | 'html' | 'css' | 'auto';
+export interface MigrationOptions {
+    /** Files and/or directories to scan. */
+    paths: string[];
+    framework: Framework;
+    /** Apply changes in place. Default: dry-run. */
+    write?: boolean;
+    /** Allow `write` on a dirty git working tree. */
+    force?: boolean;
+    /** Extra ignore globs (added to the defaults). */
+    ignore?: string[];
+    only?: string[];
+    skip?: string[];
+    /** Override the bundled manifest with a JSON file. */
+    manifestPath?: string;
+    /** Write the JSON report to this path. */
+    reportPath?: string;
+    cwd?: string;
+}
+export interface MigrationRun {
+    report: Report;
+    reporter: Reporter;
+}
+interface Route {
+    surface: Surface;
+    run: (source: string, manifest: Manifest, ctx: TransformContext) => TransformResult;
+}
+/** Pick the transform for a file given the framework (or `auto` by extension). Returns null to skip. */
+export declare const routeFile: (file: string, framework: Framework) => Route | null;
+/** Expand the input paths into a concrete, de-duplicated file list. */
+export declare const collectFiles: (paths: string[], cwd: string, ignore: string[]) => Promise<string[]>;
+export declare const runMigration: (options: MigrationOptions) => Promise<MigrationRun>;
+export * from './report/types.js';
+export { exitCode } from './report/reporter.js';
+export type { Manifest } from './manifest/schema.js';