bestax-migrate 2.3.7 → 2.3.9

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)
 [![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)
 [![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)
+[![Socket Badge](https://badge.socket.dev/npm/package/bestax-migrate/latest)](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)

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;AAoKD;;;;;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

@@ -201,10 +201,19 @@ export function makeSourceImportRe(name) {
         `${lead}(?:import|require(?:\\.resolve)?)\\s*\\(\\s*${spec}`,
     ].join('|'));
 }
+/** 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) {
     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();
@@ -233,7 +242,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 +250,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) {
@@ -260,13 +269,14 @@ 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)
+    const pkg = sourcePackage(source);
+    if (unsupported.length === 0 || pkg === null)
         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 +293,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);
     }

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

@@ -0,0 +1,45 @@
+/**
+ * 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 before
+ * `before` when there is none.
+ */
+export declare function placeBestaxImport(state: BestaxImportState, fresh: any | null, before: any): 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;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,GAAG,GAAG,IAAI,EACjB,MAAM,EAAE,GAAG,GACV,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,141 @@
+/**
+ * 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 before
+ * `before` when there is none.
+ */
+export function placeBestaxImport(state, fresh, before) {
+    if (!fresh)
+        return;
+    if (!state.existing) {
+        before.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,46 @@
+/**
+ * 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. */
+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;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAclD;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"}

package/dist/sources/_shared/deps-common.js

@@ -0,0 +1,98 @@
+/**
+ * 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 { isPreV1 } from './semver-range.js';
+const BESTAX_RANGE = '^5';
+export const BULMA_RANGE = '^1.0.4';
+// Bulma v1's sass tree uses `color.channel(…)` — needs dart-sass ≥ 1.79.
+const SASS_RANGE = '^1.79.0';
+export const DEP_SECTIONS = ['dependencies', 'devDependencies'];
+export function openManifest(filePath, pkg, collector) {
+    const changes = [];
+    const next = pkg;
+    const report = (rule, message) => collector?.add({ file: filePath, line: null, rule, message });
+    return {
+        next,
+        section: name => (next[name] ?? undefined),
+        note: message => {
+            changes.push(message);
+            report('deps', message);
+        },
+        report,
+        result: () => changes.length > 0 ? next : null,
+    };
+}
+/** @allxsmith/bestax-bulma comes in as a runtime dependency. */
+export function addBestax(manifest) {
+    const dependencies = (manifest.next.dependencies ??= {});
+    if (!dependencies['@allxsmith/bestax-bulma'] &&
+        !manifest.section('devDependencies')?.['@allxsmith/bestax-bulma']) {
+        dependencies['@allxsmith/bestax-bulma'] = BESTAX_RANGE;
+        manifest.note(`added @allxsmith/bestax-bulma ${BESTAX_RANGE} to dependencies`);
+    }
+}
+/**
+ * Bump a pre-1 Bulma range; add one only when sources still reference
+ * bulma/… directly (otherwise it arrives transitively via bestax-bulma).
+ */
+export function moveBulmaToV1(manifest, bulmaReferenced) {
+    const outcome = { declared: null, bumped: false, added: false };
+    for (const name of DEP_SECTIONS) {
+        const deps = manifest.section(name);
+        if (deps?.bulma) {
+            outcome.declared = deps.bulma;
+            if (isPreV1(deps.bulma)) {
+                deps.bulma = BULMA_RANGE;
+                outcome.bumped = true;
+                manifest.note(`bumped bulma to ${BULMA_RANGE} in ${name} (was pre-1.0)`);
+            }
+        }
+    }
+    if (outcome.declared === null && bulmaReferenced) {
+        const dependencies = (manifest.next.dependencies ??= {});
+        dependencies.bulma = BULMA_RANGE;
+        outcome.added = true;
+        manifest.note(`added bulma ${BULMA_RANGE} to dependencies (sources import bulma/… directly)`);
+    }
+    return outcome;
+}
+/**
+ * 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 function reportPeerRanges(manifest) {
+    for (const name of DEP_SECTIONS) {
+        const range = manifest.section(name)?.react;
+        if (range && /^[~^]?(?:[0-9]|1[0-7])(?:[.x]|$)/.test(range.trim())) {
+            manifest.report('peer-deps', `react ${range} predates bestax-bulma's peer range (^18 || ^19) — upgrade react and react-dom to 18 or 19 before installing`);
+        }
+    }
+    // Font Awesome older than 6 conflicts with bestax-bulma's optional peer
+    // range and makes `npm install` fail with ERESOLVE.
+    for (const name of DEP_SECTIONS) {
+        const range = manifest.section(name)?.['@fortawesome/fontawesome-free'];
+        if (range && /^[~^]?[0-5](?:[.x]|$)/.test(range.trim())) {
+            manifest.report('peer-deps', `@fortawesome/fontawesome-free ${range} predates bestax-bulma's optional peer range (^6.7.2 || ^7.0.0) — upgrade it, or install with \`npm install --legacy-peer-deps\``);
+        }
+    }
+}
+/** node-sass is dead; dart-sass replaces it in the same section. */
+export function replaceNodeSass(manifest) {
+    for (const name of DEP_SECTIONS) {
+        const deps = manifest.section(name);
+        if (deps && 'node-sass' in deps) {
+            delete deps['node-sass'];
+            manifest.note(`removed node-sass from ${name}`);
+            const sassDeclared = DEP_SECTIONS.some(s => manifest.section(s)?.sass);
+            if (!sassDeclared) {
+                deps.sass = SASS_RANGE;
+                manifest.note(`added sass ${SASS_RANGE} to ${name} (replaces node-sass)`);
+            }
+        }
+    }
+}

package/dist/sources/_shared/make-styles-transform.d.ts

@@ -14,8 +14,11 @@
  */
 import type { StylesTransform } from '../../types.js';
 export interface StylesConfig {
-    /** npm package name of the source library, e.g. `rbx`. */
-    packageName: string;
+    /**
+     * npm package name of the source library, e.g. `rbx`. Omitted for a source
+     * with no package, whose stylesheets only ever import Bulma itself.
+     */
+    packageName?: string;
     /** URL of that source's migration guide, linked from every TODO. */
     guideUrl: string;
     /**
@@ -32,6 +35,7 @@ export interface StylesConfig {
  * `packageName` drives two regexes — one matching any `@import` of that
  * package, one narrowing to its *root* stylesheet (which becomes a Bulma v1
  * root rather than being dropped). Everything else is Bulma-side and shared.
+ * Without a package neither can match, and only the Bulma rewriting runs.
  */
 export declare function makeStylesTransform(config: StylesConfig): StylesTransform;
 //# sourceMappingURL=make-styles-transform.d.ts.map

package/dist/sources/_shared/make-styles-transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make-styles-transform.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/make-styles-transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,gBAAgB,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AAyMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CA6UzE"}
+{"version":3,"file":"make-styles-transform.d.ts","sourceRoot":"","sources":["../../../src/sources/_shared/make-styles-transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,gBAAgB,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AAyMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAsVzE"}

package/dist/sources/_shared/make-styles-transform.js

@@ -197,10 +197,14 @@ function report(collector, file, line, rule, message) {
  * `packageName` drives two regexes — one matching any `@import` of that
  * package, one narrowing to its *root* stylesheet (which becomes a Bulma v1
  * root rather than being dropped). Everything else is Bulma-side and shared.
+ * Without a package neither can match, and only the Bulma rewriting runs.
  */
 export function makeStylesTransform(config) {
     const { packageName, guideUrl: GUIDE } = config;
-    const pkg = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // `packageName` is interpolated into messages only after one of these
+    // matched, so the no-package case never reaches them.
+    const NEVER = /(?!)/;
+    const pkg = packageName?.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     // Already regex fragments — see StylesConfig.
     const roots = config.rootStylesheetSuffixes.join('|');
     /**
@@ -210,11 +214,15 @@ export function makeStylesTransform(config) {
      * and SOURCE_ROOT_STYLESHEET below already accepts that bare form — so
      * requiring the slash here made the bare case unreachable.
      */
-    const SOURCE_STYLE_IMPORT = new RegExp(`^(\\s*)@import\\s+(['"])((?:\\.\\.?/)+node_modules/|~)?${pkg}(?:/[^'"]*)?\\2\\s*;?\\s*(?://[^\\n]*)?\\s*$`);
+    const SOURCE_STYLE_IMPORT = pkg === undefined
+        ? NEVER
+        : new RegExp(`^(\\s*)@import\\s+(['"])((?:\\.\\.?/)+node_modules/|~)?${pkg}(?:/[^'"]*)?\\2\\s*;?\\s*(?://[^\\n]*)?\\s*$`);
     /** Cheap "is this file even about us?" pre-filter (see the guard below). */
-    const SOURCE_MENTION = new RegExp(pkg);
+    const SOURCE_MENTION = pkg === undefined ? NEVER : new RegExp(pkg);
     /** …narrowed to the ones that stand in for a whole Bulma root. */
-    const SOURCE_ROOT_STYLESHEET = new RegExp(`^\\s*@import\\s+(['"])(?:(?:\\.\\.?/)+node_modules/|~)?${pkg}${roots ? `(?:${roots})?` : ''}\\1\\s*;?\\s*(?://[^\\n]*)?\\s*$`);
+    const SOURCE_ROOT_STYLESHEET = pkg === undefined
+        ? NEVER
+        : new RegExp(`^\\s*@import\\s+(['"])(?:(?:\\.\\.?/)+node_modules/|~)?${pkg}${roots ? `(?:${roots})?` : ''}\\1\\s*;?\\s*(?://[^\\n]*)?\\s*$`);
     const transformStyles = (filePath, source, collector, options) => {
         const cssMode = options.cssMode ?? 'bestax';
         // Cheap pre-filter. It must accept a file that names only the SOURCE