bestax-migrate 2.1.5 → 2.2.0

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Socket Badge](https://socket.dev/api/badge/npm/package/bestax-migrate)](https://socket.dev/npm/package/bestax-migrate/overview)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance)
 [![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)
 
@@ -12,9 +13,12 @@ Codemods that migrate existing React apps to [`@allxsmith/bestax-bulma`](https:/
 
 Currently supported source libraries:
 
-| Source                                                                           | Status                                                            |
-| -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs) |
+| Source                                                                           | Status                                                              |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs)   |
+| [`rbx`](https://github.com/dfee/rbx) (v2)                                        | ✅ Full export surface mapped (a few patterns are flagged as TODOs) |
+
+Pass the source library as the first argument: `bestax-migrate <source> <paths…>`.
 
 ## Requirements
 
@@ -29,6 +33,8 @@ the app being migrated — the source is read as text and is never executed.
 ```bash
 # Preview what would change (no writes)
 pnpm dlx bestax-migrate react-bulma-components src/ --dry
+# …or, for an rbx app
+pnpm dlx bestax-migrate rbx src/ --dry
 
 # Apply the migration
 pnpm dlx bestax-migrate react-bulma-components src/
@@ -38,15 +44,15 @@ npm and yarn work too: `npx bestax-migrate …` / `yarn dlx bestax-migrate …`.
 
 The codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:
 
-- rewrite `react-bulma-components` imports to `@allxsmith/bestax-bulma` (including `const { Input } = Form` destructuring and namespace imports)
+- rewrite the source library's imports to `@allxsmith/bestax-bulma` (including destructuring and namespace imports)
 - rename components and compound sub-components (`Form.Textarea` → `TextArea`, `Card.Footer.Item` → `Card.FooterItem`, `Hero.Footer` → `Hero.Foot`, …)
 - convert props (`renderAs` → `as`, `loading` → `isLoading`, numeric spacing/text sizes → string unions, `textAlign="center"` → `textAlign="centered"`, …)
 - flatten responsive breakpoint objects (`mobile={{ size: 4 }}` → `sizeMobile={4}`)
 - restructure patterns bestax models differently (`Table.Container`, Navbar dropdowns, `Form.Help`, icon-font children → `<Icon name=…>`)
 - migrate stylesheets: CSS imports converge on `@allxsmith/bestax-bulma/bestax.css`, and SCSS files move from Bulma 0.9's `@import` + `$var !default` overrides to `@use 'bulma/sass' with (…)` plus `@use '@allxsmith/bestax-bulma/scss/extras'`
-- update `package.json`: remove `react-bulma-components`, add `@allxsmith/bestax-bulma`, bump `bulma` to `^1`, and swap the dead `node-sass` for dart `sass` (no install is ever run)
+- update `package.json`: remove the source library, add `@allxsmith/bestax-bulma`, raise a declared pre-1.0 `bulma` to `^1` (adding it only when your sources import `bulma/…` directly — otherwise it arrives transitively), and swap the dead `node-sass` for dart `sass` (no install is ever run). Migrating **rbx** is what frees an app from Bulma 0.7.5: rbx pinned it as a _direct_ dependency, so the app could not choose its own Bulma version at all. The four Bulma extensions rbx also pulled in (`bulma-badge`, `bulma-divider`, `bulma-pageloader`, `bulma-tooltip`) are **reported rather than removed** — bestax replaces all four, but a manifest entry is a deliberate declaration and your own Sass may import them
 
-Anything without a safe automatic conversion is left in place with a `// TODO(bestax-migrate): …` comment, and the run ends with a report of every TODO by file and line. TODOs are expected output, not errors — resolve them with the [migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components), or let the [`bestax-migrate` Agent Skill](https://bestax.io/docs/skills/intro) walk them for you:
+Anything without a safe automatic conversion is left in place with a `// TODO(bestax-migrate): …` comment, and the run ends with a report of every TODO by file and line. TODOs are expected output, not errors — resolve them with the migration guide ([react-bulma-components](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components), [rbx](https://bestax.io/docs/guides/getting-started/migration/rbx)), or let the [`bestax-migrate` Agent Skill](https://bestax.io/docs/skills/intro) walk them for you:
 
 ```bash
 npx skills add https://github.com/allxsmith/bestax --skill bestax-migrate
@@ -68,7 +74,7 @@ npx skills add https://github.com/allxsmith/bestax --skill bestax-migrate
 2. Search for `TODO(bestax-migrate)` and resolve each comment
 3. Typecheck/build and review the rendered app
 
-Full walkthrough: [react-bulma-components migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components).
+Full walkthrough: [react-bulma-components migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components) · [rbx migration guide](https://bestax.io/docs/guides/getting-started/migration/rbx).
 
 ## Hardened by default
 
@@ -99,4 +105,4 @@ Full disclosure of every field and control: [Telemetry guide](https://bestax.io/
 
 ## License
 
-MIT © Alex Smith
+Source code licensed MIT

package/dist/cli.d.ts

@@ -22,6 +22,59 @@ export interface CliIo {
     log: (message: string) => void;
     error: (message: string) => void;
 }
+/**
+ * Matches an import of `name` at a specifier boundary, in every form a
+ * retained reference can take: a root or DEEP JavaScript import
+ * (`from 'rbx'`, `from 'rbx/base/theme'` — deep ones are kept with a TODO), a
+ * bindingless side-effect `import 'rbx'` (which the transform leaves untouched
+ * because there is nothing to rewrite), the CommonJS / dynamic forms
+ * `require('rbx')` and `import('rbx')` — neither of which the jscodeshift
+ * transform rewrites, so both survive the run as live references — and the
+ * Sass forms the stylesheet transform preserves in indented `.sass` files
+ * (`@import '~rbx/rbx'`).
+ *
+ * Matching only `from '<pkg>'` meant a file whose ONLY remaining reference was
+ * a deep or Sass import let the manifest pass drop the package with no
+ * warning. Matching a bare substring is the opposite error, and worse for a
+ * name as short as `rbx`: prose and a sibling package like `rbx-utils` both
+ * counted as imports.
+ *
+ * Comments are allowed wherever whitespace is, because a webpack magic comment
+ * sits exactly there: `import(/* webpackChunkName: "x" *\/ 'rbx')`.
+ */
+/**
+ * Blank out comments while preserving strings, offsets, and line breaks.
+ *
+ * The import matcher needs to know whether a keyword is real code, and no
+ * lookbehind can tell it: `// import { Box } from 'rbx'` is not an import,
+ * while the `//` inside `const u = 'http://x'; require('rbx')` is not a
+ * comment. Comment bytes become spaces rather than being deleted so the
+ * caller's line lookup still lines up with the original text.
+ *
+ * Deliberately small: this is not a JavaScript lexer. It tracks quotes and the
+ * two comment forms, which is what the matcher needs, and it is applied to
+ * `.sass` and `.vue` files too, where `//` is also a comment.
+ */
+export declare function blankComments(text: string): string;
+/**
+ * Matches an import of `name` at a specifier boundary, in every form a
+ * retained reference can take: a root or DEEP JavaScript import
+ * (`from 'rbx'`, `from 'rbx/base/theme'`), a bindingless side-effect
+ * `import 'rbx'`, a re-export, the CommonJS and dynamic forms `require('rbx')`
+ * and `import('rbx')` — none of which the jscodeshift transform rewrites, so
+ * all survive the run as live references — and the Sass form the stylesheet
+ * transform preserves in indented `.sass` files (`@import '~rbx/rbx'`).
+ *
+ * Run it over `blankComments(text)`, not the raw text: the keyword alternatives
+ * carry no comment awareness of their own by design, because that job needs a
+ * scanner rather than a lookbehind.
+ *
+ * Matching only `from '<pkg>'` meant a file whose ONLY remaining reference was
+ * a deep or Sass import let the manifest pass drop the package with no warning.
+ * Matching a bare substring is the opposite error, and worse for a name as
+ * short as `rbx`: prose and a sibling package like `rbx-utils` both counted.
+ */
+export declare function makeSourceImportRe(name: string): RegExp;
 /**
  * One-question consent prompt (readline — this package carries no interactive
  * prompt dependency). Returns null when the question is cancelled (Ctrl-C /

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqBxE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CAkBV;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkB5D;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AA4ID;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,KAAK,EACT,KAAK,GAAE,QAAwB,EAC/B,MAAM,GAAE,QAAyB,EAGjC,aAAa,GAAE,OAAO,eAAiC,GACtD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAyBzB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,EAAE,EAAE,KAAK,EACT,aAAa,GAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAA0B,GAC7E,OAAO,CAAC,IAAI,CAAC,CAqBf;AAYD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAkD,GACrD,OAAO,CAkHT"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqBxE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CAkBV;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkB5D;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgDlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsBvD;AA8JD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,KAAK,EACT,KAAK,GAAE,QAAwB,EAC/B,MAAM,GAAE,QAAyB,EAGjC,aAAa,GAAE,OAAO,eAAiC,GACtD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAyBzB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,EAAE,EAAE,KAAK,EACT,aAAa,GAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAA0B,GAC7E,OAAO,CAAC,IAAI,CAAC,CAqBf;AAYD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAkD,GACrD,OAAO,CAkHT"}

package/dist/cli.js

@@ -79,8 +79,132 @@ export function findPackageJsons(targets) {
     }
     return [...found].sort();
 }
+/**
+ * Matches an import of `name` at a specifier boundary, in every form a
+ * retained reference can take: a root or DEEP JavaScript import
+ * (`from 'rbx'`, `from 'rbx/base/theme'` — deep ones are kept with a TODO), a
+ * bindingless side-effect `import 'rbx'` (which the transform leaves untouched
+ * because there is nothing to rewrite), the CommonJS / dynamic forms
+ * `require('rbx')` and `import('rbx')` — neither of which the jscodeshift
+ * transform rewrites, so both survive the run as live references — and the
+ * Sass forms the stylesheet transform preserves in indented `.sass` files
+ * (`@import '~rbx/rbx'`).
+ *
+ * Matching only `from '<pkg>'` meant a file whose ONLY remaining reference was
+ * a deep or Sass import let the manifest pass drop the package with no
+ * warning. Matching a bare substring is the opposite error, and worse for a
+ * name as short as `rbx`: prose and a sibling package like `rbx-utils` both
+ * counted as imports.
+ *
+ * Comments are allowed wherever whitespace is, because a webpack magic comment
+ * sits exactly there: `import(/* webpackChunkName: "x" *\/ 'rbx')`.
+ */
+/**
+ * Blank out comments while preserving strings, offsets, and line breaks.
+ *
+ * The import matcher needs to know whether a keyword is real code, and no
+ * lookbehind can tell it: `// import { Box } from 'rbx'` is not an import,
+ * while the `//` inside `const u = 'http://x'; require('rbx')` is not a
+ * comment. Comment bytes become spaces rather than being deleted so the
+ * caller's line lookup still lines up with the original text.
+ *
+ * Deliberately small: this is not a JavaScript lexer. It tracks quotes and the
+ * two comment forms, which is what the matcher needs, and it is applied to
+ * `.sass` and `.vue` files too, where `//` is also a comment.
+ */
+export function blankComments(text) {
+    let out = '';
+    let quote = null;
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (quote) {
+            if (c === '\\' && i + 1 < text.length) {
+                out += c + next;
+                i += 2;
+                continue;
+            }
+            if (c === quote)
+                quote = null;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            quote = c;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (c === '/' && next === '/') {
+            while (i < text.length && text[i] !== '\n') {
+                out += ' ';
+                i += 1;
+            }
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            out += '  ';
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) {
+                out += text[i] === '\n' ? '\n' : ' ';
+                i += 1;
+            }
+            if (i < text.length) {
+                out += '  ';
+                i += 2;
+            }
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+/**
+ * Matches an import of `name` at a specifier boundary, in every form a
+ * retained reference can take: a root or DEEP JavaScript import
+ * (`from 'rbx'`, `from 'rbx/base/theme'`), a bindingless side-effect
+ * `import 'rbx'`, a re-export, the CommonJS and dynamic forms `require('rbx')`
+ * and `import('rbx')` — none of which the jscodeshift transform rewrites, so
+ * all survive the run as live references — and the Sass form the stylesheet
+ * transform preserves in indented `.sass` files (`@import '~rbx/rbx'`).
+ *
+ * Run it over `blankComments(text)`, not the raw text: the keyword alternatives
+ * carry no comment awareness of their own by design, because that job needs a
+ * scanner rather than a lookbehind.
+ *
+ * Matching only `from '<pkg>'` meant a file whose ONLY remaining reference was
+ * a deep or Sass import let the manifest pass drop the package with no warning.
+ * Matching a bare substring is the opposite error, and worse for a name as
+ * short as `rbx`: prose and a sibling package like `rbx-utils` both counted.
+ */
+export function makeSourceImportRe(name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const spec = `['"](?:~|(?:\\.\\.?/)+node_modules/)?${escaped}(?:/[^'"]*)?['"]`;
+    // Not the tail of a longer identifier: `myrequire('rbx')` is not a require,
+    // and `foo.import(...)` is not an import.
+    const lead = String.raw `(?<![\w$.])`;
+    return new RegExp([
+        // A static import or re-export. The keyword is what separates a real
+        // specifier from a bare `from` in prose ("Migrated from 'rbx' in 2019").
+        // `[^;]` spans the newlines of a multi-line specifier list without
+        // running past the statement.
+        `${lead}(?:import|export)\\b[^;]*?\\bfrom\\s*${spec}`,
+        // A bindingless side-effect import, and the Sass form.
+        `${lead}import\\s*${spec}`,
+        `@import\\s*${spec}`,
+        // The dynamic and CommonJS forms, which appear mid-expression.
+        // `require.resolve('rbx')` is as live a reference as `require('rbx')`
+        // and is just as unrewritten by the transform.
+        `${lead}(?:import|require(?:\\.resolve)?)\\s*\\(\\s*${spec}`,
+    ].join('|'));
+}
 function migrateFiles(source, files, reporter, io, options) {
     let bulmaReferenced = false;
+    let sourceStillImported = false;
+    const sourceImportRe = makeSourceImportRe(source.name);
     for (const file of files) {
         const sourceText = fs.readFileSync(file, 'utf8');
         const collector = reporter.startFile();
@@ -103,12 +227,23 @@ function migrateFiles(source, files, reporter, io, options) {
         }
         catch (error) {
             io.error(chalk.red(`✖ ${file}: ${error.message}`));
+            // Read the signals off the ORIGINAL text before bailing. A parse
+            // failure in the only file importing the source library would
+            // otherwise let the manifest pass remove the package with no warning —
+            // the file still imports it, we just couldn't rewrite it.
+            if (/['"](?:~?bulma\/)/.test(sourceText))
+                bulmaReferenced = true;
+            if (sourceImportRe.test(blankComments(sourceText)))
+                sourceStillImported = true;
             reporter.finishFile(file, false, collector.entries);
             continue;
         }
         if (/['"](?:~?bulma\/)/.test(output ?? sourceText)) {
             bulmaReferenced = true;
         }
+        if (sourceImportRe.test(blankComments(output ?? sourceText))) {
+            sourceStillImported = true;
+        }
         if (output !== null) {
             if (options.print)
                 io.log(output);
@@ -117,7 +252,7 @@ function migrateFiles(source, files, reporter, io, options) {
         }
         reporter.finishFile(file, output !== null, collector.entries);
     }
-    return bulmaReferenced;
+    return { bulmaReferenced, sourceStillImported };
 }
 /**
  * Surface files in unparseable formats (.astro, .vue, …) that import the
@@ -126,13 +261,24 @@ function migrateFiles(source, files, reporter, io, options) {
 function reportUnsupportedFiles(source, targets, reporter, extensions) {
     const unsupported = UNSUPPORTED_EXTENSIONS.filter(ext => !extensions.includes(ext));
     if (unsupported.length === 0)
-        return;
+        return false;
+    // Whether any unsupported file still references the source package. These
+    // are reported but never rewritten, so the reference survives the run —
+    // and the manifest pass must not remove the package out from under it.
+    let stillImported = false;
+    const importRe = makeSourceImportRe(source.name);
     for (const file of collectFiles(targets, unsupported)) {
         const text = fs.readFileSync(file, 'utf8');
-        if (!text.includes(source.name))
+        // A substring match is not evidence of an import. `rbx` is three
+        // characters: prose in an .mdx file and a sibling package like
+        // `rbx-utils` both matched, which reported a file that imports nothing
+        // and pinned the dependency the manifest pass would otherwise remove.
+        const scanned = blankComments(text);
+        if (!importRe.test(scanned))
             continue;
+        stillImported = true;
         const collector = reporter.startFile();
-        const line = text.split('\n').findIndex(l => l.includes(source.name)) + 1 || null;
+        const line = scanned.split('\n').findIndex(l => importRe.test(l)) + 1 || null;
         collector.add({
             file,
             line,
@@ -141,8 +287,9 @@ function reportUnsupportedFiles(source, targets, reporter, extensions) {
         });
         reporter.finishFile(file, false, collector.entries);
     }
+    return stillImported;
 }
-function migrateDependencies(source, targets, reporter, io, options, bulmaReferenced) {
+function migrateDependencies(source, targets, reporter, io, options, deps) {
     if (!options.deps || !source.updateDependencies)
         return;
     for (const pkgPath of findPackageJsons(targets)) {
@@ -153,7 +300,8 @@ function migrateDependencies(source, targets, reporter, io, options, bulmaRefere
             const pkg = JSON.parse(raw);
             const next = source.updateDependencies(pkgPath, pkg, collector, {
                 cssMode: options.cssMode,
-                bulmaReferenced,
+                bulmaReferenced: deps.bulmaReferenced,
+                sourceStillImported: deps.sourceStillImported,
             });
             if (next !== null) {
                 changed = true;
@@ -307,9 +455,11 @@ export function createCLI(io = { log: console.log, error: console.error }) {
             cssMode: options.css,
         };
         const reporter = new Reporter();
-        const bulmaReferenced = migrateFiles(source, files, reporter, io, runOptions);
-        reportUnsupportedFiles(source, targets, reporter, extensions);
-        migrateDependencies(source, targets, reporter, io, runOptions, bulmaReferenced);
+        const depSignals = migrateFiles(source, files, reporter, io, runOptions);
+        const unsupportedImports = reportUnsupportedFiles(source, targets, reporter, extensions);
+        if (unsupportedImports)
+            depSignals.sourceStillImported = true;
+        migrateDependencies(source, targets, reporter, io, runOptions, depSignals);
         io.log(reporter.render(source.label + (runOptions.dry ? ' (dry run)' : '')));
         displayStarNudge(io);
         // Success path only: rule names and counts, never file/line/message.

package/dist/sources/_shared/imports.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Import-rewriting mechanics shared by every source transform: collecting the
+ * names a file already binds, and handing out non-colliding local names for
+ * the bestax imports a transform wants to add.
+ *
+ * Source-agnostic: nothing here knows which library is being migrated.
+ */
+import type { ASTPath, Collection, JSCodeshift } from 'jscodeshift';
+import type { TransformContext } from './jsx-utils.js';
+export declare const nameOf: (node: any) => string;
+/**
+ * Every identifier the file already binds — variables, function and class
+ * declarations, parameters (including destructured ones), and imports other
+ * than the source library's own (those are pruned by the caller).
+ *
+ * Importing a bestax component under a name the file already uses would
+ * redeclare it, so these names drive the aliasing in `makeReserve`.
+ */
+export declare function collectBoundNames(j: JSCodeshift, root: Collection<any>, skipImportSource: string): Set<string>;
+/**
+ * Build the `ctx.reserve` implementation: register a bestax import by its
+ * exported name and get back the local name to write in JSX — the plain name
+ * when it is free, otherwise `Bulma<Name>` (then `Bulma<Name>2`, …).
+ */
+export declare function makeReserve(ctx: TransformContext, bound: Set<string>): (importedName: string) => string;
+/**
+ * Tab-indented sources keep tabs when reprinted, so recast's output does not
+ * drift from the untouched lines around it.
+ */
+export declare function prefersTabs(source: string): boolean;
+/**
+ * True when the identifier `name` at `path` really resolves to the binding
+ * the import/alias passes recorded, rather than a local that shadows it.
+ *
+ * Both passes key on identifier TEXT, so a nested `function F({ Card })`
+ * parameter looked exactly like the source library's `Card`: its JSX was
+ * rewritten to bestax's `Card.FooterItem` and the destructured parameter was
+ * renamed alongside it, silently repointing the code at a different object.
+ *
+ * `expected` is the scope the binding was collected in — the program scope for
+ * an import (they are always top-level), or the declaring scope of a
+ * `const { Item } = Card` alias, which the alias pass records because it walks
+ * declarators at any depth.
+ */
+export declare function resolvesToBinding(path: ASTPath<any>, name: string, expected: unknown): boolean;
+//# sourceMappingURL=imports.d.ts.map

package/dist/sources/_shared/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/imports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,eAAO,MAAM,MAAM,GAAI,MAAM,GAAG,KAAG,MACyB,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,WAAW,EACd,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EACrB,gBAAgB,EAAE,MAAM,GACvB,GAAG,CAAC,MAAM,CAAC,CAmEb;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GACjB,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAiBlC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,GAChB,OAAO,CAST"}

package/dist/sources/_shared/imports.js

@@ -0,0 +1,152 @@
+/**
+ * Import-rewriting mechanics shared by every source transform: collecting the
+ * names a file already binds, and handing out non-colliding local names for
+ * the bestax imports a transform wants to add.
+ *
+ * Source-agnostic: nothing here knows which library is being migrated.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const nameOf = (node) => typeof node === 'string' ? node : String(node?.name ?? '');
+/**
+ * Every identifier the file already binds — variables, function and class
+ * declarations, parameters (including destructured ones), and imports other
+ * than the source library's own (those are pruned by the caller).
+ *
+ * Importing a bestax component under a name the file already uses would
+ * redeclare it, so these names drive the aliasing in `makeReserve`.
+ */
+export function collectBoundNames(j, root, skipImportSource) {
+    const bound = new Set();
+    const collectPattern = (node) => {
+        if (!node)
+            return;
+        switch (node.type) {
+            case 'Identifier':
+                bound.add(node.name);
+                break;
+            case 'ObjectPattern':
+                for (const prop of node.properties ?? []) {
+                    collectPattern(prop.value ?? prop.argument);
+                }
+                break;
+            case 'ArrayPattern':
+                for (const el of node.elements ?? [])
+                    collectPattern(el);
+                break;
+            case 'RestElement':
+                collectPattern(node.argument);
+                break;
+            case 'AssignmentPattern':
+                collectPattern(node.left);
+                break;
+        }
+    };
+    root.find(j.VariableDeclarator).forEach(path => collectPattern(path.node.id));
+    root.find(j.FunctionDeclaration).forEach(path => {
+        if (path.node.id)
+            bound.add(nameOf(path.node.id));
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root
+        .find(j.ClassDeclaration)
+        .forEach(path => path.node.id && bound.add(nameOf(path.node.id)));
+    // TypeScript declaration forms that occupy a name an import would collide
+    // with. An `enum Button` next to a generated `import { Button }` is a
+    // duplicate-identifier build break, and the alias pass could not see it.
+    // Interfaces and type aliases share the declaration space with an imported
+    // binding of the same name too, so they reserve as well — an unnecessary
+    // alias costs nothing, a missed one does not compile.
+    for (const kind of [
+        'TSEnumDeclaration',
+        'TSModuleDeclaration',
+        'TSInterfaceDeclaration',
+        'TSTypeAliasDeclaration',
+    ]) {
+        root.find(j[kind]).forEach((path) => {
+            const id = path.node.id;
+            if (id && (id.type === 'Identifier' || id.type === 'StringLiteral')) {
+                bound.add(nameOf(id));
+            }
+        });
+    }
+    root.find(j.FunctionExpression).forEach(path => {
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root.find(j.ArrowFunctionExpression).forEach(path => {
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root.find(j.ImportDeclaration).forEach(path => {
+        if (String(path.node.source.value) === skipImportSource)
+            return;
+        for (const spec of path.node.specifiers ?? []) {
+            if (spec.local)
+                bound.add(nameOf(spec.local));
+        }
+    });
+    return bound;
+}
+/**
+ * Build the `ctx.reserve` implementation: register a bestax import by its
+ * exported name and get back the local name to write in JSX — the plain name
+ * when it is free, otherwise `Bulma<Name>` (then `Bulma<Name>2`, …).
+ */
+export function makeReserve(ctx, bound) {
+    return (importedName) => {
+        const existing = ctx.needed.get(importedName);
+        if (existing)
+            return existing;
+        let local = importedName;
+        if (bound.has(local)) {
+            local = `Bulma${importedName}`;
+            let suffix = 2;
+            const locals = new Set(ctx.needed.values());
+            while (bound.has(local) || locals.has(local)) {
+                local = `Bulma${importedName}${suffix}`;
+                suffix += 1;
+            }
+        }
+        ctx.needed.set(importedName, local);
+        return local;
+    };
+}
+/**
+ * Tab-indented sources keep tabs when reprinted, so recast's output does not
+ * drift from the untouched lines around it.
+ */
+export function prefersTabs(source) {
+    let tabs = 0;
+    let spaces = 0;
+    for (const line of source.split('\n')) {
+        if (line.startsWith('\t'))
+            tabs += 1;
+        else if (line.startsWith(' '))
+            spaces += 1;
+    }
+    return tabs > spaces;
+}
+/**
+ * True when the identifier `name` at `path` really resolves to the binding
+ * the import/alias passes recorded, rather than a local that shadows it.
+ *
+ * Both passes key on identifier TEXT, so a nested `function F({ Card })`
+ * parameter looked exactly like the source library's `Card`: its JSX was
+ * rewritten to bestax's `Card.FooterItem` and the destructured parameter was
+ * renamed alongside it, silently repointing the code at a different object.
+ *
+ * `expected` is the scope the binding was collected in — the program scope for
+ * an import (they are always top-level), or the declaring scope of a
+ * `const { Item } = Card` alias, which the alias pass records because it walks
+ * declarators at any depth.
+ */
+export function resolvesToBinding(path, name, expected) {
+    if (!expected)
+        return true;
+    const declaring = path.scope?.lookup(name);
+    // An unresolvable name keeps the old behaviour rather than silently
+    // skipping work: a miss here means no rewrite at all, which is worse than
+    // the shadowing case it guards against.
+    return !declaring || declaring === expected;
+}

package/dist/sources/{react-bulma-components → _shared}/jsx-utils.d.ts

@@ -1,7 +1,11 @@
 /**
- * Small AST helpers shared by the react-bulma-components transform passes.
- * All functions operate on the babel/tsx AST that jscodeshift's `tsx` parser
- * produces, via the `j` builder API.
+ * Small AST helpers shared by every source's transform passes. All functions
+ * operate on the babel/tsx AST that jscodeshift's `tsx` parser produces, via
+ * the `j` builder API.
+ *
+ * Nothing here may know which source library is being migrated — this module
+ * is imported by all of them (`react-bulma-components`, `rbx`, …), so any
+ * library-specific table belongs in that source's own `mapping.ts`.
  */
 import type { JSCodeshift } from 'jscodeshift';
 import type { ASTPath } from 'jscodeshift';
@@ -10,7 +14,7 @@ export interface TransformContext {
     j: JSCodeshift;
     file: string;
     collector: TodoCollector | undefined;
-    /** RBC top-level import names that must survive the import rewrite. */
+    /** Source-library top-level import names that must survive the rewrite. */
     retained: Set<string>;
     /** bestax-bulma imports: imported name → local name (aliased on conflict). */
     needed: Map<string, string>;
@@ -26,7 +30,10 @@ export interface TransformContext {
      * Navbar.Item becomes Navbar.DropdownMenu).
      */
     overrides: WeakMap<object, string>;
-    /** Resolves a JSX name node to its canonical RBC path (set by transform). */
+    /**
+     * Resolves a JSX name node to its canonical source-library path (set by the
+     * source's transform).
+     */
     resolve?: (name: any) => string[] | null;
     dirty: boolean;
 }
@@ -57,13 +64,14 @@ export type LiteralValue = {
 export declare function literalValueOf(attr: any): LiteralValue;
 export type Booleanish = 'truthy' | 'falsy' | 'expression';
 /**
- * Classify a JSX attribute by the truthiness RBC evaluates it with at
- * runtime (`!!value`): every statically-known literal (boolean, string, or
- * number) resolves to `'truthy'`/`'falsy'`; only a genuine expression is
- * `'expression'`. This is the single place the six call sites that branch on
- * a "booleanish" prop (Button `remove`, Heading `heading`/`subtitle`,
- * `booleanToProp`, the `active` ladders, Field `multiline`) agree on what
- * counts as resolvable, so they can't drift out of sync with each other.
+ * Classify a JSX attribute by the truthiness the source library evaluates it
+ * with at runtime (`!!value`): every statically-known literal (boolean,
+ * string, or number) resolves to `'truthy'`/`'falsy'`; only a genuine
+ * expression is `'expression'`. This is the single place every call site that
+ * branches on a "booleanish" prop (RBC's Button `remove`, Heading
+ * `heading`/`subtitle`, `booleanToProp`, the `active` ladders, Field
+ * `multiline`; rbx's bare-boolean modifiers) agrees on what counts as
+ * resolvable, so they can't drift out of sync with each other.
  */
 export declare function resolveBooleanish(attr: any): Booleanish;
 /** Create `name` (bare boolean) or `name="value"` attribute. */

package/dist/sources/_shared/jsx-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-utils.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/jsx-utils.ts"],"names":[],"mappings":"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"}