bestax-migrate 2.3.8 → 2.4.0

package/README.md

@@ -11,15 +11,16 @@
 
 Codemods that migrate existing React apps to [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — the actively maintained React component library for **Bulma v1**.
 
-Currently supported source libraries:
+Currently supported sources:
 
-| 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)                |
-| [`bloomer`](https://github.com/AlgusDark/bloomer) (0.6)                          | ✅ All 108 exports mapped (Font Awesome 4 icons and Bulma 0.4's `Nav` are flagged) |
+| 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)                  |
+| [`bloomer`](https://github.com/AlgusDark/bloomer) (0.6)                          | ✅ All 108 exports mapped (Font Awesome 4 icons and Bulma 0.4's `Nav` are flagged)   |
+| `bulma-classes`: Bulma's classes on plain JSX, no library                        | ✅ Converts an element only when bestax renders the same markup; the rest is flagged |
 
-Pass the source library as the first argument: `bestax-migrate <source> <paths…>`.
+Pass the source as the first argument: `bestax-migrate <source> <paths…>`.
 
 ## Requirements
 
@@ -37,6 +38,8 @@ pnpm dlx bestax-migrate react-bulma-components src/ --dry
 # …or, for an rbx or bloomer app
 pnpm dlx bestax-migrate rbx src/ --dry
 pnpm dlx bestax-migrate bloomer src/ --dry
+# …or, for an app that writes Bulma's classes on plain JSX
+pnpm dlx bestax-migrate bulma-classes src/ --dry
 
 # Apply the migration
 pnpm dlx bestax-migrate react-bulma-components src/
@@ -50,11 +53,12 @@ The codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:
 - rename components and compound sub-components (`Form.Textarea` → `TextArea`, `Card.Footer.Item` → `Card.FooterItem`, `Hero.Footer` → `Hero.Foot`, …) — and, for bloomer, its flat names onto bestax's compounds (`CardHeaderTitle` → `Card.Header.Title`)
 - 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}`) and bloomer's `isDisplay`/`isHidden` strings, arrays and objects (`isHidden="touch"` → `visibilityTouch="hidden"`)
+- for `bulma-classes`, turn raw Bulma markup into components and props (`<a className="button is-primary">` → `<Button as="a" color="primary">`, `<p className="has-text-centered mt-4">` → `<Paragraph textAlign="centered" mt="4">`), converting an element only when bestax renders exactly the same markup
 - 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 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. A **bloomer** app declared its own Bulma 0.6, which is what gets bumped
+- 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. A **bloomer** app declared its own Bulma 0.6, which is what gets bumped. For **bulma-classes** there is no library to remove, and by default (`--css keep`) the app's Bulma version, Sass and stylesheet imports all stay: its own Bulma already styles every class a converted element renders. `--css bestax` or `--css bulma` moves it to Bulma v1 like the other sources
 
-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), [bloomer](https://bestax.io/docs/guides/getting-started/migration/bloomer)), 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), [bloomer](https://bestax.io/docs/guides/getting-started/migration/bloomer), [Bulma classes](https://bestax.io/docs/guides/getting-started/migration/bulma-classes)), 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
@@ -62,13 +66,13 @@ npx skills add https://github.com/allxsmith/bestax --skill bestax-migrate
 
 ## Options
 
-| Flag                 | Description                                                    |
-| -------------------- | -------------------------------------------------------------- |
-| `--dry`, `-d`        | Report what would change without writing files                 |
-| `--print`, `-p`      | Print transformed sources to stdout                            |
-| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`) |
-| `--css <mode>`       | Stylesheet target: `bestax` (default), `bulma`, or `keep`      |
-| `--no-deps`          | Skip updating package.json dependencies                        |
+| Flag                 | Description                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `--dry`, `-d`        | Report what would change without writing files                                                 |
+| `--print`, `-p`      | Print transformed sources to stdout                                                            |
+| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`)                                 |
+| `--css <mode>`       | Stylesheet target: `bestax`, `bulma`, or `keep` (default `bestax`; `keep` for `bulma-classes`) |
+| `--no-deps`          | Skip updating package.json dependencies                                                        |
 
 ## After the codemod
 
@@ -76,7 +80,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) · [rbx migration guide](https://bestax.io/docs/guides/getting-started/migration/rbx) · [bloomer migration guide](https://bestax.io/docs/guides/getting-started/migration/bloomer).
+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) · [bloomer migration guide](https://bestax.io/docs/guides/getting-started/migration/bloomer) · [Bulma classes migration guide](https://bestax.io/docs/guides/getting-started/migration/bulma-classes).
 
 ## Hardened by default
 

package/dist/cli.d.ts

@@ -15,6 +15,7 @@ import { createInterface } from 'node:readline/promises';
 import type { Readable, Writable } from 'node:stream';
 import { Command } from 'commander';
 import { type MigrateRunStats } from './telemetry.js';
+import type { MigrationSource } from './types.js';
 export declare function collectFiles(targets: string[], extensions: string[]): string[];
 /** Nearest package.json for each target, walking up to the filesystem root. */
 export declare function findPackageJsons(targets: string[]): string[];
@@ -75,6 +76,8 @@ export declare function blankComments(text: string): string;
  * short as `rbx`: prose and a sibling package like `rbx-utils` both counted.
  */
 export declare function makeSourceImportRe(name: string): RegExp;
+/** The package a source migrates away from, or null when it has none. */
+export declare function sourcePackage(source: MigrationSource): string | null;
 /**
  * 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;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"}
+{"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;AACxE,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,YAAY,CAAC;AAoB3D,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;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAEpE;AA4LD;;;;;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,CA0HT"}

package/dist/cli.js

@@ -201,10 +201,19 @@ export function makeSourceImportRe(name) {
         `${lead}(?:import|require(?:\\.resolve)?)\\s*\\(\\s*${spec}`,
     ].join('|'));
 }
-function migrateFiles(source, files, reporter, io, options) {
+/** The package a source migrates away from, or null when it has none. */
+export function sourcePackage(source) {
+    return source.packageName === undefined ? source.name : source.packageName;
+}
+/** Whether `text` still imports the source's package (never, without one). */
+function importsSource(importRe, text) {
+    return importRe !== null && importRe.test(blankComments(text));
+}
+function migrateFiles(source, files, reporter, io, options, project) {
     let bulmaReferenced = false;
     let sourceStillImported = false;
-    const sourceImportRe = makeSourceImportRe(source.name);
+    const pkg = sourcePackage(source);
+    const sourceImportRe = pkg === null ? null : makeSourceImportRe(pkg);
     for (const file of files) {
         const sourceText = fs.readFileSync(file, 'utf8');
         const collector = reporter.startFile();
@@ -221,6 +230,7 @@ function migrateFiles(source, files, reporter, io, options) {
             }
             else {
                 output = runTransform(source.transform, file, sourceText, collector, {
+                    ...project,
                     cssMode: options.cssMode,
                 }).output;
             }
@@ -233,7 +243,7 @@ function migrateFiles(source, files, reporter, io, options) {
             // the file still imports it, we just couldn't rewrite it.
             if (/['"](?:~?bulma\/)/.test(sourceText))
                 bulmaReferenced = true;
-            if (sourceImportRe.test(blankComments(sourceText)))
+            if (importsSource(sourceImportRe, sourceText))
                 sourceStillImported = true;
             reporter.finishFile(file, false, collector.entries);
             continue;
@@ -241,7 +251,7 @@ function migrateFiles(source, files, reporter, io, options) {
         if (/['"](?:~?bulma\/)/.test(output ?? sourceText)) {
             bulmaReferenced = true;
         }
-        if (sourceImportRe.test(blankComments(output ?? sourceText))) {
+        if (importsSource(sourceImportRe, output ?? sourceText)) {
             sourceStillImported = true;
         }
         if (output !== null) {
@@ -259,14 +269,36 @@ function migrateFiles(source, files, reporter, io, options) {
  * source library, so a migration never silently skips them.
  */
 function reportUnsupportedFiles(source, targets, reporter, extensions) {
-    const unsupported = UNSUPPORTED_EXTENSIONS.filter(ext => !extensions.includes(ext));
+    const unsupported = UNSUPPORTED_EXTENSIONS.filter(ext => !extensions.includes(ext) &&
+        (source.unsupportedExtensions?.includes(ext) ?? true));
+    const pkg = sourcePackage(source);
     if (unsupported.length === 0)
         return false;
+    if (pkg === null) {
+        // No package to look for: the source says what it would have converted.
+        const find = source.findUnsupportedReference;
+        if (!find)
+            return false;
+        for (const file of collectFiles(targets, unsupported)) {
+            const line = find(fs.readFileSync(file, 'utf8'));
+            if (line === null)
+                continue;
+            const collector = reporter.startFile();
+            collector.add({
+                file,
+                line,
+                rule: 'unsupported-file',
+                message: `has markup the ${source.name} source would convert, but ${path.extname(file)} files cannot be parsed by the codemod — migrate this file by hand`,
+            });
+            reporter.finishFile(file, false, collector.entries);
+        }
+        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);
+    const importRe = makeSourceImportRe(pkg);
     for (const file of collectFiles(targets, unsupported)) {
         const text = fs.readFileSync(file, 'utf8');
         // A substring match is not evidence of an import. `rbx` is three
@@ -283,7 +315,7 @@ function reportUnsupportedFiles(source, targets, reporter, extensions) {
             file,
             line,
             rule: 'unsupported-file',
-            message: `imports ${source.name}, but ${path.extname(file)} files cannot be parsed by the codemod — migrate this file by hand`,
+            message: `imports ${pkg}, but ${path.extname(file)} files cannot be parsed by the codemod — migrate this file by hand`,
         });
         reporter.finishFile(file, false, collector.entries);
     }
@@ -419,7 +451,7 @@ export function createCLI(io = { log: console.log, error: console.error }) {
         .option('-d, --dry', 'dry run — report what would change without writing', false)
         .option('-p, --print', 'print transformed sources to stdout', false)
         .option('-e, --extensions <list>', 'comma-separated file extensions to include', 'js,jsx,ts,tsx,scss,sass')
-        .option('--css <mode>', `stylesheet target: ${CSS_MODES.join(', ')}`, 'bestax')
+        .option('--css <mode>', `stylesheet target: ${CSS_MODES.join(', ')} (default bestax; keep for bulma-classes)`)
         .option('--no-deps', 'skip updating package.json dependencies')
         .option('--telemetry', 'enable anonymous usage telemetry (https://bestax.io/docs/guides/telemetry)')
         .option('--no-telemetry', 'disable anonymous usage telemetry')
@@ -430,7 +462,8 @@ export function createCLI(io = { log: console.log, error: console.error }) {
             program.error('', { exitCode: 1 });
             return;
         }
-        if (!CSS_MODES.includes(options.css)) {
+        const cssMode = options.css ?? source.defaultCssMode ?? 'bestax';
+        if (!CSS_MODES.includes(cssMode)) {
             io.error(`${chalk.red('Unknown --css mode')} "${options.css}". Valid modes: ${CSS_MODES.join(', ')}`);
             program.error('', { exitCode: 1 });
             return;
@@ -452,10 +485,11 @@ export function createCLI(io = { log: console.log, error: console.error }) {
             dry: Boolean(options.dry),
             print: Boolean(options.print),
             deps: options.deps !== false,
-            cssMode: options.css,
+            cssMode,
         };
         const reporter = new Reporter();
-        const depSignals = migrateFiles(source, files, reporter, io, runOptions);
+        const project = source.analyzeProject?.(targets) ?? {};
+        const depSignals = migrateFiles(source, files, reporter, io, runOptions, project);
         const unsupportedImports = reportUnsupportedFiles(source, targets, reporter, extensions);
         if (unsupportedImports)
             depSignals.sourceStillImported = true;

package/dist/sources/_shared/bestax-import.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `@allxsmith/bestax-bulma` import a migrated file ends up with.
+ *
+ * Every source does the same three things: seed the components an existing
+ * bestax import already binds (so the JSX reuses their locals), record which
+ * components the passes actually ask for, and then either merge the new ones
+ * into that existing import or write a fresh declaration. Where the fresh
+ * declaration goes is the caller's call; a library source puts it where the
+ * library's own import was.
+ */
+import type { TransformContext } from './jsx-utils.js';
+export declare const BESTAX = "@allxsmith/bestax-bulma";
+export interface BestaxImportState {
+    /** The existing declaration new specifiers merge into, if any. */
+    existing: any | undefined;
+    /** Components the existing declaration already binds as values. */
+    preExisting: Set<string>;
+    /** Components the passes asked for through `ctx.reserve`. */
+    requested: Set<string>;
+}
+/**
+ * Call once `ctx.reserve` is final and before any pass reserves a name: it
+ * wraps `reserve` to record requests and seeds `ctx.needed` from an existing
+ * bestax import.
+ */
+export declare function seedBestaxImport(ctx: TransformContext, root: any): BestaxImportState;
+/** The fresh declaration for components not already imported, or null. */
+export declare function buildBestaxImport(ctx: TransformContext, state: BestaxImportState): any | null;
+/**
+ * Locals that bind a bestax VALUE once the import is written. A type-only
+ * specifier the seeding recorded, and nothing promoted, binds no value.
+ */
+export declare function bestaxValueLocals(ctx: TransformContext, state: BestaxImportState): Set<string>;
+/**
+ * Merge `fresh` into the existing bestax import, or insert it through
+ * `anchor` when there is none. An AST path is an anchor: the fresh import
+ * goes before it.
+ */
+export declare function placeBestaxImport(state: BestaxImportState, fresh: any | null, anchor: {
+    insertBefore(node: any): unknown;
+}): void;
+/**
+ * A pruned declaration takes its comments with it — a licence header, an
+ * eslint directive. Hand them to `carrier` (the bestax import that survives),
+ * or to the next statement, or keep them where they were.
+ */
+export declare function carryPrunedComments(node: any, importPath: any, carrier: any | null): void;
+//# sourceMappingURL=bestax-import.d.ts.map

package/dist/sources/_shared/bestax-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bestax-import.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/bestax-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,eAAO,MAAM,MAAM,4BAA4B,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,EAAE,GAAG,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,6DAA6D;IAC7D,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,GAAG,GACR,iBAAiB,CA+CnB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,iBAAiB,GACvB,GAAG,GAAG,IAAI,CAgBZ;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,iBAAiB,GACvB,GAAG,CAAC,MAAM,CAAC,CASb;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,GAAG,GAAG,IAAI,EACjB,MAAM,EAAE;IAAE,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;CAAE,GAC3C,IAAI,CAyBN;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,GAAG,EACT,UAAU,EAAE,GAAG,EACf,OAAO,EAAE,GAAG,GAAG,IAAI,GAClB,IAAI,CAsBN"}

package/dist/sources/_shared/bestax-import.js

@@ -0,0 +1,142 @@
+/**
+ * The `@allxsmith/bestax-bulma` import a migrated file ends up with.
+ *
+ * Every source does the same three things: seed the components an existing
+ * bestax import already binds (so the JSX reuses their locals), record which
+ * components the passes actually ask for, and then either merge the new ones
+ * into that existing import or write a fresh declaration. Where the fresh
+ * declaration goes is the caller's call; a library source puts it where the
+ * library's own import was.
+ */
+import { nameOf } from './imports.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const BESTAX = '@allxsmith/bestax-bulma';
+/**
+ * Call once `ctx.reserve` is final and before any pass reserves a name: it
+ * wraps `reserve` to record requests and seeds `ctx.needed` from an existing
+ * bestax import.
+ */
+export function seedBestaxImport(ctx, root) {
+    const { j } = ctx;
+    // Names the passes actually asked for. `ctx.needed` is also seeded from an
+    // existing bestax import's specifiers below (so JSX reuses their locals),
+    // and that seeding alone must not turn a type-only specifier into a value
+    // import nobody needed.
+    const requested = new Set();
+    const baseReserve = ctx.reserve;
+    ctx.reserve = name => {
+        requested.add(name);
+        return baseReserve(name);
+    };
+    // Only a declaration made entirely of NAMED specifiers can be merged into.
+    // `import * as Bulma from '@allxsmith/bestax-bulma'` matches the source too,
+    // and appending named specifiers to it emitted
+    // `import * as Bulma, { Box } from …` — not valid JavaScript, so the whole
+    // file failed to parse after a migration that reported success.
+    const existing = root
+        .find(j.ImportDeclaration, { source: { value: BESTAX } })
+        .paths()
+        .find((path) => 
+    // A type-only declaration cannot take a value specifier: merging a
+    // component into `import type { … }` erases it at runtime.
+    path.node.importKind !== 'type' &&
+        (path.node.specifiers ?? []).every((spec) => spec.type === 'ImportSpecifier'));
+    const preExisting = new Set();
+    if (existing) {
+        for (const spec of existing.node.specifiers ?? []) {
+            if (spec.type === 'ImportSpecifier' && spec.local) {
+                // The local name is reused either way, so the JSX never needs an
+                // alias. But an inline `type` specifier (`import { type Box }`) is
+                // not a value binding: it is not counted as already imported, so the
+                // component is written as a value below — onto this specifier, which
+                // keeps its name, rather than as a duplicate.
+                ctx.needed.set(nameOf(spec.imported), nameOf(spec.local));
+                if (spec.importKind !== 'type') {
+                    preExisting.add(nameOf(spec.imported));
+                }
+            }
+        }
+    }
+    return { existing, preExisting, requested };
+}
+/** The fresh declaration for components not already imported, or null. */
+export function buildBestaxImport(ctx, state) {
+    const { j } = ctx;
+    const freshNames = [...ctx.needed.entries()]
+        .filter(([imported]) => state.requested.has(imported) && !state.preExisting.has(imported))
+        .sort((a, b) => a[0].localeCompare(b[0]));
+    return freshNames.length > 0
+        ? j.importDeclaration(freshNames.map(([imported, local]) => j.importSpecifier(j.identifier(imported), j.identifier(local))), j.stringLiteral(BESTAX))
+        : null;
+}
+/**
+ * Locals that bind a bestax VALUE once the import is written. A type-only
+ * specifier the seeding recorded, and nothing promoted, binds no value.
+ */
+export function bestaxValueLocals(ctx, state) {
+    return new Set([...ctx.needed.entries()]
+        .filter(([imported]) => state.requested.has(imported) || state.preExisting.has(imported))
+        .map(([, local]) => local));
+}
+/**
+ * Merge `fresh` into the existing bestax import, or insert it through
+ * `anchor` when there is none. An AST path is an anchor: the fresh import
+ * goes before it.
+ */
+export function placeBestaxImport(state, fresh, anchor) {
+    if (!fresh)
+        return;
+    if (!state.existing) {
+        anchor.insertBefore(fresh);
+        return;
+    }
+    const current = state.existing.node.specifiers ?? [];
+    const appended = [];
+    for (const spec of fresh.specifiers) {
+        // A type-only specifier for the same name becomes the value
+        // import (a value import carries the type too); appending a
+        // second `Box` beside `type Box` would be a duplicate identifier.
+        const typeOnly = current.find((existingSpec) => existingSpec.type === 'ImportSpecifier' &&
+            existingSpec.importKind === 'type' &&
+            nameOf(existingSpec.imported) === nameOf(spec.imported));
+        if (typeOnly) {
+            typeOnly.importKind = null;
+        }
+        else {
+            appended.push(spec);
+        }
+    }
+    state.existing.node.specifiers = [...current, ...appended];
+}
+/**
+ * A pruned declaration takes its comments with it — a licence header, an
+ * eslint directive. Hand them to `carrier` (the bestax import that survives),
+ * or to the next statement, or keep them where they were.
+ */
+export function carryPrunedComments(node, importPath, carrier) {
+    const comments = node.comments ?? [];
+    if (comments.length === 0)
+        return;
+    const body = importPath.parent?.node?.body ?? [];
+    const index = body.indexOf(node);
+    const target = carrier ?? (index >= 0 ? body[index + 1] : undefined);
+    if (target) {
+        target.comments = [...comments, ...(target.comments ?? [])];
+    }
+    else if (index > 0) {
+        // The import was the last statement: the comments stay where they
+        // were, after what precedes it.
+        const previous = body[index - 1];
+        previous.comments = [
+            ...(previous.comments ?? []),
+            ...comments.map((c) => ({ ...c, leading: false, trailing: true })),
+        ];
+    }
+    else {
+        // The import was the only statement: the comments become the file's.
+        const program = importPath.parent?.node;
+        if (program)
+            program.comments = [...comments, ...(program.comments ?? [])];
+    }
+    node.comments = [];
+}

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

@@ -0,0 +1,33 @@
+/**
+ * The stylesheet-import pass every source runs before its JSX work.
+ *
+ * `--css bestax` (the default) converges every Bulma stylesheet import on the
+ * combined `bestax.css` bundle, which already carries the extras; `bulma`
+ * keeps plain Bulma v1 CSS and adds the extras import beside it; `keep`
+ * leaves the app's own Bulma import alone and only retargets a source
+ * library's stylesheet, which no longer resolves once the library is gone.
+ *
+ * What differs per source is the source's own stylesheet (react-bulma-components'
+ * v3 bundle, `rbx/index.css`; bloomer ships none) and anything the source
+ * handles before the shared rules (rbx's extension stylesheets).
+ */
+import type { CssMode } from '../../types.js';
+import { type TransformContext } from './jsx-utils.js';
+export interface StylesheetImportOptions {
+    /**
+     * The source library's own stylesheet, retargeted wherever Bulma's is:
+     * which specifiers are it, and how the keep-mode TODO names it (e.g.
+     * "rbx's CSS import"). One object, so a matcher never lacks its label.
+     */
+    sourceCss?: {
+        is: (specifier: string) => boolean;
+        label: string;
+    };
+    /**
+     * Runs first for every import; returning true means the source handled it
+     * and the shared rules skip it.
+     */
+    handleOwn?: (path: any, specifier: string) => boolean;
+}
+export declare function rewriteStylesheetImports(ctx: TransformContext, root: any, cssMode: CssMode, options?: StylesheetImportOptions): void;
+//# sourceMappingURL=css-imports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"css-imports.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/css-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAuBhE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CACvD;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,uBAA4B,GACpC,IAAI,CA4EN"}

package/dist/sources/_shared/css-imports.js

@@ -0,0 +1,103 @@
+/**
+ * The stylesheet-import pass every source runs before its JSX work.
+ *
+ * `--css bestax` (the default) converges every Bulma stylesheet import on the
+ * combined `bestax.css` bundle, which already carries the extras; `bulma`
+ * keeps plain Bulma v1 CSS and adds the extras import beside it; `keep`
+ * leaves the app's own Bulma import alone and only retargets a source
+ * library's stylesheet, which no longer resolves once the library is gone.
+ *
+ * What differs per source is the source's own stylesheet (react-bulma-components'
+ * v3 bundle, `rbx/index.css`; bloomer ships none) and anything the source
+ * handles before the shared rules (rbx's extension stylesheets).
+ */
+import { addTodo } from './jsx-utils.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const BULMA_CSS = 'bulma/css/bulma.min.css';
+const BESTAX_CSS = '@allxsmith/bestax-bulma/bestax.css';
+const EXTRAS_CSS = '@allxsmith/bestax-bulma/extras.css';
+const BULMA_CSS_SPECIFIERS = new Set([
+    'bulma/css/bulma.css',
+    'bulma/css/bulma.min.css',
+]);
+const BESTAX_CSS_SPECIFIERS = new Set([
+    BESTAX_CSS,
+    '@allxsmith/bestax-bulma/bestax.min.css',
+    '@allxsmith/bestax-bulma/dist/bestax.css',
+    '@allxsmith/bestax-bulma/dist/bestax.min.css',
+]);
+const EXTRAS_CSS_SPECIFIERS = new Set([
+    EXTRAS_CSS,
+    '@allxsmith/bestax-bulma/dist/extras.css',
+]);
+export function rewriteStylesheetImports(ctx, root, cssMode, options = {}) {
+    const { j } = ctx;
+    const isSourceCss = options.sourceCss?.is ?? (() => false);
+    const specifierOf = (p) => String(p.node.source.value);
+    let sawBestaxCss = root
+        .find(j.ImportDeclaration)
+        .paths()
+        .some((p) => BESTAX_CSS_SPECIFIERS.has(specifierOf(p)));
+    // Whether some import in this file will become bestax.css, regardless of
+    // where it sits relative to an existing extras import.
+    const willAdoptBestaxCss = cssMode === 'bestax' &&
+        root
+            .find(j.ImportDeclaration)
+            .paths()
+            .some((p) => {
+            const specifier = specifierOf(p);
+            return isSourceCss(specifier) || BULMA_CSS_SPECIFIERS.has(specifier);
+        });
+    root.find(j.ImportDeclaration).forEach((path) => {
+        const source = specifierOf(path);
+        if (options.handleOwn?.(path, source))
+            return;
+        const isOwnCss = isSourceCss(source);
+        const isBulmaCss = BULMA_CSS_SPECIFIERS.has(source);
+        const isExtrasCss = EXTRAS_CSS_SPECIFIERS.has(source);
+        if (!isOwnCss && !isBulmaCss && !isExtrasCss)
+            return;
+        if (cssMode === 'bestax') {
+            if (isOwnCss || isBulmaCss) {
+                if (sawBestaxCss) {
+                    path.prune(); // bestax.css already imported elsewhere in this file
+                }
+                else {
+                    path.node.source = j.stringLiteral(BESTAX_CSS);
+                    sawBestaxCss = true;
+                }
+                ctx.dirty = true;
+            }
+            else if (isExtrasCss && (sawBestaxCss || willAdoptBestaxCss)) {
+                // bestax.css already contains the extras. `willAdoptBestaxCss` covers
+                // the case where the extras import comes FIRST in the file and the
+                // import that becomes bestax.css has not been visited yet —
+                // otherwise the extras survive alongside it and double-load.
+                path.prune();
+                ctx.dirty = true;
+            }
+        }
+        else if (cssMode === 'bulma') {
+            if (isOwnCss) {
+                path.node.source = j.stringLiteral(BULMA_CSS);
+                ctx.dirty = true;
+            }
+            if ((isOwnCss || isBulmaCss) && !sawBestaxCss) {
+                const hasExtras = root
+                    .find(j.ImportDeclaration)
+                    .paths()
+                    .some((p) => EXTRAS_CSS_SPECIFIERS.has(specifierOf(p)));
+                if (!hasExtras) {
+                    // Themed Radio/Checkbox need the bestax extras next to plain Bulma.
+                    path.insertAfter(j.importDeclaration([], j.stringLiteral(EXTRAS_CSS)));
+                    ctx.dirty = true;
+                }
+            }
+        }
+        else if (isOwnCss && options.sourceCss) {
+            // keep: minimal fix — the source's stylesheet goes with the source.
+            path.node.source = j.stringLiteral(BULMA_CSS);
+            addTodo(ctx, path, 'css', `replaced ${options.sourceCss.label} with '${BULMA_CSS}'; install bulma@^1 (see https://bestax.io/docs/guides/getting-started/installation)`);
+        }
+    });
+}

package/dist/sources/_shared/deps-common.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The package.json steps every source's manifest pass takes once the source
+ * library itself is dealt with: bring in bestax-bulma, move the app's Bulma to
+ * v1, report peer ranges bestax-bulma cannot install beside, and swap the
+ * dead node-sass for dart-sass. Pure data-in/data-out, like the passes that
+ * call it: no package manager is ever invoked.
+ */
+import type { TodoCollector } from '../../types.js';
+export declare const BULMA_RANGE = "^1.0.4";
+export declare const DEP_SECTIONS: readonly ["dependencies", "devDependencies"];
+type Section = (typeof DEP_SECTIONS)[number];
+export interface Manifest {
+    /** The manifest being edited in place. */
+    next: Record<string, Record<string, string> | unknown>;
+    section(name: Section): Record<string, string> | undefined;
+    /** Record a change: it counts as an edit and lands in the report. */
+    note(message: string): void;
+    /** Report without counting as an edit. */
+    report(rule: string, message: string): void;
+    /** The edited manifest, or null when nothing changed. */
+    result(): Record<string, unknown> | null;
+}
+export declare function openManifest(filePath: string, pkg: Record<string, unknown>, collector: TodoCollector | undefined): Manifest;
+/**
+ * @allxsmith/bestax-bulma comes in as a runtime dependency. An older major
+ * already declared is reported, not raised: the migrated code is written for
+ * the current one, and moving the app's existing bestax code across majors is
+ * the app's own step.
+ */
+export declare function addBestax(manifest: Manifest): void;
+export interface BulmaOutcome {
+    /** The declared range before any bump, or null when none was declared. */
+    declared: string | null;
+    bumped: boolean;
+    added: boolean;
+}
+/**
+ * Bump a pre-1 Bulma range; add one only when sources still reference
+ * bulma/… directly (otherwise it arrives transitively via bestax-bulma).
+ */
+export declare function moveBulmaToV1(manifest: Manifest, bulmaReferenced: boolean | undefined): BulmaOutcome;
+/**
+ * Report ranges bestax-bulma's peers cannot install beside. Report only: a
+ * React major and a Font Awesome major (whose icon names change) are the
+ * app's own migration steps.
+ */
+export declare function reportPeerRanges(manifest: Manifest): void;
+/** node-sass is dead; dart-sass replaces it in the same section. */
+export declare function replaceNodeSass(manifest: Manifest): void;
+export {};
+//# sourceMappingURL=deps-common.d.ts.map

package/dist/sources/_shared/deps-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps-common.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/deps-common.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,eAAO,MAAM,WAAW,WAAW,CAAC;AAIpC,eAAO,MAAM,YAAY,8CAA+C,CAAC;AACzE,KAAK,OAAO,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7C,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3D,qEAAqE;IACrE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0CAA0C;IAC1C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,yDAAyD;IACzD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,aAAa,GAAG,SAAS,GACnC,QAAQ,CAiBV;AAaD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAmBlD;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,eAAe,EAAE,OAAO,GAAG,SAAS,GACnC,YAAY,CA2Bd;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAqBzD;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAexD"}