bestax-migrate 2.3.8 → 2.4.0

package/dist/sources/react-bulma-components/deps.js

@@ -4,28 +4,17 @@
  * with dart-sass. Pure data-in/data-out — the CLI owns file IO, and no
  * package manager is ever invoked (the report tells the user to install).
  */
-import { isPreV1 } from '../_shared/semver-range.js';
-const BESTAX_RANGE = '^5';
-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';
-const DEP_SECTIONS = ['dependencies', 'devDependencies'];
+import { DEP_SECTIONS, addBestax, moveBulmaToV1, openManifest, replaceNodeSass, reportPeerRanges, } from '../_shared/deps-common.js';
 export const updateDependencies = (filePath, pkg, collector, options) => {
-    const changes = [];
-    const next = pkg;
-    const section = (name) => (next[name] ?? undefined);
-    const note = (message) => {
-        changes.push(message);
-        collector?.add({ file: filePath, line: null, rule: 'deps', message });
-    };
+    const manifest = openManifest(filePath, pkg, collector);
     // react-bulma-components goes away entirely.
     let removedSource = false;
     for (const name of DEP_SECTIONS) {
-        const deps = section(name);
+        const deps = manifest.section(name);
         if (deps && 'react-bulma-components' in deps) {
             delete deps['react-bulma-components'];
             removedSource = true;
-            note(`removed react-bulma-components from ${name}`);
+            manifest.note(`removed react-bulma-components from ${name}`);
         }
     }
     // The transform deliberately RETAINS imports for components with no bestax
@@ -35,76 +24,12 @@ export const updateDependencies = (filePath, pkg, collector, options) => {
     // letting them find out at build time. rbx has carried this warning since
     // it shipped; this source retains imports the same way and did not.
     if (removedSource && options.sourceStillImported) {
-        collector?.add({
-            file: filePath,
-            line: null,
-            rule: 'deps',
-            message: 'react-bulma-components was removed from package.json, but some files still import it for components with no bestax equivalent — resolve those `TODO(bestax-migrate)` imports before installing, or re-add react-bulma-components until you have',
-        });
-    }
-    // @allxsmith/bestax-bulma comes in (runtime dependency).
-    const dependencies = (next.dependencies ??= {});
-    if (!dependencies['@allxsmith/bestax-bulma'] &&
-        !section('devDependencies')?.['@allxsmith/bestax-bulma']) {
-        dependencies['@allxsmith/bestax-bulma'] = BESTAX_RANGE;
-        note(`added @allxsmith/bestax-bulma ${BESTAX_RANGE} to dependencies`);
-    }
-    // Bulma: bump a pre-1 range; add only when sources still reference bulma/…
-    // directly (otherwise it arrives transitively via bestax-bulma).
-    let bulmaDeclared = false;
-    for (const name of DEP_SECTIONS) {
-        const deps = section(name);
-        if (deps?.bulma) {
-            bulmaDeclared = true;
-            if (isPreV1(deps.bulma)) {
-                deps.bulma = BULMA_RANGE;
-                note(`bumped bulma to ${BULMA_RANGE} in ${name} (was pre-1.0)`);
-            }
-        }
-    }
-    if (!bulmaDeclared && options.bulmaReferenced) {
-        dependencies.bulma = BULMA_RANGE;
-        note(`added bulma ${BULMA_RANGE} to dependencies (sources import bulma/… directly)`);
-    }
-    // bestax-bulma requires React 18/19; RBC v4 also ran on 17. Report only —
-    // a React major upgrade is the app's own migration step.
-    for (const name of DEP_SECTIONS) {
-        const range = section(name)?.react;
-        if (range && /^[~^]?(?:[0-9]|1[0-7])(?:[.x]|$)/.test(range.trim())) {
-            collector?.add({
-                file: filePath,
-                line: null,
-                rule: 'peer-deps',
-                message: `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. Report only — icon
-    // names change across FA majors, so upgrading is the app's decision.
-    for (const name of DEP_SECTIONS) {
-        const range = section(name)?.['@fortawesome/fontawesome-free'];
-        if (range && /^[~^]?[0-5](?:[.x]|$)/.test(range.trim())) {
-            collector?.add({
-                file: filePath,
-                line: null,
-                rule: 'peer-deps',
-                message: `@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.
-    for (const name of DEP_SECTIONS) {
-        const deps = section(name);
-        if (deps && 'node-sass' in deps) {
-            delete deps['node-sass'];
-            note(`removed node-sass from ${name}`);
-            const sassDeclared = DEP_SECTIONS.some(s => section(s)?.sass);
-            if (!sassDeclared) {
-                deps.sass = SASS_RANGE;
-                note(`added sass ${SASS_RANGE} to ${name} (replaces node-sass)`);
-            }
-        }
-    }
-    return changes.length > 0 ? next : null;
+        manifest.report('deps', 'react-bulma-components was removed from package.json, but some files still import it for components with no bestax equivalent — resolve those `TODO(bestax-migrate)` imports before installing, or re-add react-bulma-components until you have');
+    }
+    addBestax(manifest);
+    moveBulmaToV1(manifest, options.bulmaReferenced);
+    // RBC v4 also ran on React 17, which bestax-bulma's peer range excludes.
+    reportPeerRanges(manifest);
+    replaceNodeSass(manifest);
+    return manifest.result();
 };

package/dist/sources/react-bulma-components/mapping.js

@@ -26,7 +26,7 @@ export const UNIVERSAL_PROPS = {
         todo: 'this bestax component has no `as` prop; restructure the element instead',
     },
     domRef: {
-        todo: 'bestax-bulma has no `domRef`. The form controls and `Button`, `LinkButton`, `Modal`, `Dropdown`, `Navbar` (plus `Navbar.Burger` and `Navbar.Link`), `Dialog`, `Sidebar`, `Toast` and `Carousel` forward a ref — on those, rename `domRef` to `ref`. Mind the `Navbar.Dropdown` collision: the `Navbar.Item` that wrapped your dropdown became bestax `Navbar.Dropdown` and forwards one, while your `Navbar.Dropdown` became `Navbar.DropdownMenu` and does not. The rest forward no ref: put the ref on a DOM child or wrap the component',
+        todo: 'bestax-bulma has no `domRef`. The form controls, plus `Avatar`, `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `Link`, `LinkButton`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`, `Navbar.Item`, `Navbar.Link`, `Sidebar` and `Toast` forward a ref — on those, rename `domRef` to `ref`, though not on the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios` wrappers, which forward none. Mind the `Navbar.Dropdown` collision: the `Navbar.Item` that wrapped your dropdown became bestax `Navbar.Dropdown` and forwards one, while your `Navbar.Dropdown` became `Navbar.DropdownMenu` and does not. The rest forward no ref: React 18 drops it with a warning, React 19 leaves it wherever the rest props go, so put the ref on a DOM child or wrap the component',
     },
     // ColorProps
     backgroundColor: { rename: 'bgColor' },

package/dist/sources/react-bulma-components/specials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specials.d.ts","sourceRoot":"","sources":["../../../src/sources/react-bulma-components/specials.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAWL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EAAE,aAAa,EAAE,CAAC;AA+yB9B,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAClB,OAAO,EAAE,GAAG,GACX,aAAa,CAIf;AAED,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAGjE,CAAC"}
+{"version":3,"file":"specials.d.ts","sourceRoot":"","sources":["../../../src/sources/react-bulma-components/specials.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAWL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EAAE,aAAa,EAAE,CAAC;AA82B9B,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAClB,OAAO,EAAE,GAAG,GACX,aAAa,CAIf;AAED,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAGjE,CAAC"}

package/dist/sources/react-bulma-components/specials.js

@@ -28,7 +28,7 @@ function keptAttrs(ctx, path, element, where, tag) {
     const kept = new Set(stripModifierProps(ctx, path, attributesOf(element), where));
     return (element.openingElement.attributes ?? []).filter((a) => a.type === 'JSXSpreadAttribute' || kept.has(a));
 }
-const stripModifierProps = makeStripModifierProps(UNIVERSAL_PROPS, RESPONSIVE_BREAKPOINTS);
+const stripModifierProps = makeStripModifierProps(UNIVERSAL_PROPS, RESPONSIVE_BREAKPOINTS, 'domRef');
 const SPECIALS = {
     /**
      * RBC defaults Columns `multiline` to TRUE (Bulma and bestax default to
@@ -490,7 +490,6 @@ const SPECIALS = {
             removeAttr(element, activeAttr);
         }
         liClass = mergeClassName(ctx, path, element, liClass, 'Breadcrumb.Item');
-        const anchorAttrs = keptAttrs(ctx, path, element, 'Breadcrumb.Item', 'a');
         const children = element.children ?? [];
         const solidChildren = children.filter((c) => !(c.type === 'JSXText' && c.value.trim() === ''));
         // `<Breadcrumb.Item><a href>…</a></Breadcrumb.Item>` already carries its
@@ -501,11 +500,37 @@ const SPECIALS = {
             solidChildren[0].openingElement.name.name === 'a'
             ? solidChildren[0]
             : null;
+        // The strip below renames `domRef` to `ref`, so a collision with a `ref`
+        // the anchor already sets is settled here, while the prop still carries
+        // the name the user wrote.
+        const domRefAttr = findAttr(element, 'domRef');
+        if (existingAnchor && domRefAttr && findAttr(existingAnchor, 'ref')) {
+            removeAttr(element, domRefAttr);
+            addTodo(ctx, path, 'prop:domRef', 'Breadcrumb.Item `domRef` was dropped: its <a> child already sets `ref` — reconcile by hand');
+        }
+        const anchorAttrs = keptAttrs(ctx, path, element, 'Breadcrumb.Item', 'a');
         if (existingAnchor && anchorAttrs.length > 0) {
-            existingAnchor.openingElement.attributes = [
+            // Merging onto an anchor the user already wrote keeps the rule
+            // `collapseOntoChild` does: the item's spreads go FIRST, as one block in
+            // source order, so the anchor's explicit props still win over them; and
+            // a named prop both set keeps the anchor's value and is flagged, since
+            // writing it twice does not compile.
+            const spreads = anchorAttrs.filter((a) => a.type === 'JSXSpreadAttribute');
+            const merged = [
+                ...spreads,
                 ...(existingAnchor.openingElement.attributes ?? []),
-                ...anchorAttrs,
             ];
+            for (const attr of anchorAttrs) {
+                if (attr.type === 'JSXSpreadAttribute')
+                    continue;
+                const name = attr.name.name;
+                if (findAttr(existingAnchor, name)) {
+                    addTodo(ctx, path, `prop:${name}`, `Breadcrumb.Item \`${name}\` was dropped: its <a> child already sets \`${name}\` — reconcile by hand`);
+                    continue;
+                }
+                merged.push(attr);
+            }
+            existingAnchor.openingElement.attributes = merged;
         }
         const anchor = existingAnchor ?? plainElement(j, 'a', undefined, anchorAttrs, children);
         path.replace(plainElement(j, 'li', liClass, [], [anchor]));
@@ -519,6 +544,19 @@ const SPECIALS = {
             if (findAttr(element, 'className')) {
                 addTodo(ctx, path, 'prop:className', 'Table.Container className; the container folded into `isResponsive` on its Table — re-apply the class by hand');
             }
+            // The container element is gone after the fold. What it carried
+            // (`domRef`, `id`, handlers) applied to the wrapping div, and moving it
+            // onto the Table would put it on the <table> instead, so it is reported
+            // rather than carried. Only `className` used to be reported.
+            for (const attr of attributesOf(element)) {
+                const name = attr?.name?.name;
+                if (!name || name === 'className')
+                    continue;
+                addTodo(ctx, path, `prop:${name}`, `Table.Container \`${name}\` was dropped: the container folded into \`isResponsive\` on its Table, so there is no element left to carry it — re-apply by hand`);
+            }
+            if ((element.openingElement.attributes ?? []).some((a) => a.type === 'JSXSpreadAttribute')) {
+                addTodo(ctx, path, 'prop:spread', 'Table.Container spread props were dropped: the container folded into `isResponsive` on its Table, so there is no element left to carry them — re-apply by hand');
+            }
             const child = children[0];
             addAttr(child, makeAttr(ctx.j, 'isResponsive'));
             path.replace(child);

package/dist/sources/react-bulma-components/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/sources/react-bulma-components/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA6CvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,gBAAqB,GAC7B,MAAM,GAAG,SAAS,CAy8BpB"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/sources/react-bulma-components/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAoCvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,gBAAqB,GAC7B,MAAM,GAAG,SAAS,CA6wBpB"}

package/dist/sources/react-bulma-components/transform.js

@@ -14,32 +14,16 @@
  * statement plus an entry in the run report.
  */
 import { MAPPING, UNIVERSAL_PROPS, resolveMapping } from './mapping.js';
-import { addTodo, attributesOf, jsxNameParts, renameElement, } from '../_shared/jsx-utils.js';
+import { addTodo, attributesOf, forgetJsxParens, jsxNameParts, renameElement, reprintDirectives, } from '../_shared/jsx-utils.js';
 import { applyPropAction, applyUniversalProps } from '../_shared/props.js';
 import { enforcePolymorphicProps } from '../_shared/polymorphic.js';
+import { bestaxValueLocals, buildBestaxImport, carryPrunedComments, placeBestaxImport, seedBestaxImport, } from '../_shared/bestax-import.js';
+import { rewriteStylesheetImports } from '../_shared/css-imports.js';
 import { collectBoundNames, makeAliasRegistry, makeReserve, nameOf, prefersTabs, resolvesToBinding, } from '../_shared/imports.js';
 import { flattenResponsiveProps } from './responsive.js';
 import { RESPONSIVE_KINDS, runSpecial } from './specials.js';
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const RBC = 'react-bulma-components';
-const BESTAX = '@allxsmith/bestax-bulma';
-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 default function transform(fileInfo, api, options = {}) {
     const j = api.jscodeshift;
     const root = j(fileInfo.source);
@@ -105,60 +89,12 @@ export default function transform(fileInfo, api, options = {}) {
         addTodo(ctx, p, 'imports', `\`export * from '${RBC}'\` was not migrated; re-export the bestax components you need by hand`);
     });
     // ---- 1a. Stylesheet imports (mode-driven) -----------------------------
-    // `bestax` (default): everything converges on the recommended combined
-    // bundle. `bulma`: plain Bulma v1 CSS plus the separate extras file.
-    // `keep`: only the dead RBC v3 CSS import is touched.
-    const cssMode = options.cssMode ?? 'bestax';
-    let sawBestaxCss = root
-        .find(j.ImportDeclaration)
-        .paths()
-        .some(p => BESTAX_CSS_SPECIFIERS.has(String(p.node.source.value)));
-    root.find(j.ImportDeclaration).forEach(path => {
-        const source = String(path.node.source.value);
-        const isRbcCss = source.startsWith(`${RBC}/`) && source.endsWith('.css');
-        const isBulmaCss = BULMA_CSS_SPECIFIERS.has(source);
-        const isExtrasCss = EXTRAS_CSS_SPECIFIERS.has(source);
-        if (!isRbcCss && !isBulmaCss && !isExtrasCss)
-            return;
-        if (cssMode === 'bestax') {
-            if (isRbcCss || 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) {
-                // bestax.css already contains the extras.
-                path.prune();
-                ctx.dirty = true;
-            }
-        }
-        else if (cssMode === 'bulma') {
-            if (isRbcCss) {
-                path.node.source = j.stringLiteral(BULMA_CSS);
-                ctx.dirty = true;
-            }
-            if ((isRbcCss || isBulmaCss) && !sawBestaxCss) {
-                const hasExtras = root
-                    .find(j.ImportDeclaration)
-                    .paths()
-                    .some(p => EXTRAS_CSS_SPECIFIERS.has(String(p.node.source.value)));
-                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 (isRbcCss) {
-            // keep: minimal fix — the v3 bundled CSS no longer exists at all.
-            path.node.source = j.stringLiteral(BULMA_CSS);
-            addTodo(ctx, path, 'css', `replaced the react-bulma-components CSS import with '${BULMA_CSS}'; install bulma@^1 (see https://bestax.io/docs/guides/getting-started/installation)`);
-        }
+    // `keep` touches only the dead RBC v3 CSS import.
+    rewriteStylesheetImports(ctx, root, options.cssMode ?? 'bestax', {
+        sourceCss: {
+            is: specifier => specifier.startsWith(`${RBC}/`) && specifier.endsWith('.css'),
+            label: 'the react-bulma-components CSS import',
+        },
     });
     if (imports.size === 0 && !ctx.dirty) {
         return undefined;
@@ -343,46 +279,7 @@ export default function transform(fileInfo, api, options = {}) {
             bound.add(head);
     });
     ctx.reserve = makeReserve(ctx, bound);
-    // 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 = root => {
-        requested.add(root);
-        return baseReserve(root);
-    };
-    // Merge with an existing bestax import: reuse its locals verbatim.
-    // 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 existingBestax = 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 preExistingImports = new Set();
-    if (existingBestax) {
-        for (const spec of existingBestax.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') {
-                    preExistingImports.add(nameOf(spec.imported));
-                }
-            }
-        }
-    }
+    const bestaxImportState = seedBestaxImport(ctx, root);
     // ---- 2. Transform JSX elements ----------------------------------------
     root.find(j.JSXElement).forEach(path => {
         const element = path.node;
@@ -745,62 +642,13 @@ export default function transform(fileInfo, api, options = {}) {
     // ---- 3. Rewrite imports -----------------------------------------------
     if (imports.size > 0) {
         const retainedNames = [...ctx.retained].sort((a, b) => a.localeCompare(b));
-        const freshNames = [...ctx.needed.entries()]
-            .filter(([imported]) => requested.has(imported) && !preExistingImports.has(imported))
-            .sort((a, b) => a[0].localeCompare(b[0]));
-        const bestaxImport = freshNames.length > 0
-            ? j.importDeclaration(freshNames.map(([imported, local]) => j.importSpecifier(j.identifier(imported), j.identifier(local))), j.stringLiteral(BESTAX))
-            : null;
-        /**
-    
-         * A pruned declaration takes its comments with it — a licence header, an
-    
-         * eslint directive. Hand them to what replaces it, or to the next statement.
-    
-         */
-        const carryComments = (node, importPath) => {
-            const comments = node.comments ?? [];
-            if (comments.length === 0)
-                return;
-            const body = importPath.parent?.node?.body ?? [];
-            const index = body.indexOf(node);
-            // The fresh specifiers are merged INTO an existing bestax import when there
-            // is one, and the `bestaxImport` node is then discarded — so the comments
-            // have to follow the declaration that survives, not the one that does not.
-            const carrier = (existingBestax ? existingBestax.node : bestaxImport) ??
-                (index >= 0 ? body[index + 1] : undefined);
-            if (carrier) {
-                carrier.comments = [...comments, ...(carrier.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 = [];
-        };
+        const bestaxImport = buildBestaxImport(ctx, bestaxImportState);
         let inserted = false;
         // A retained RBC specifier must never collide with a bestax import local
         // (possible when one component is both JSX-migrated and value-retained).
         // Only a VALUE local can collide at runtime: a type-only specifier the
         // seeding above recorded, and nothing promoted, binds no value.
-        const bestaxLocals = new Set([...ctx.needed.entries()]
-            .filter(([imported]) => requested.has(imported) || preExistingImports.has(imported))
-            .map(([, local]) => local));
+        const bestaxLocals = bestaxValueLocals(ctx, bestaxImportState);
         for (const path of rbcImportPaths) {
             const node = path.node;
             const keepSpecifiers = (node.specifiers ?? []).filter((spec) => {
@@ -815,28 +663,7 @@ export default function transform(fileInfo, api, options = {}) {
                     !bestaxLocals.has(nameOf(spec.local)));
             });
             if (!inserted) {
-                if (existingBestax && bestaxImport) {
-                    const current = existingBestax.node.specifiers ?? [];
-                    const appended = [];
-                    for (const fresh of bestaxImport.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((spec) => spec.type === 'ImportSpecifier' &&
-                            spec.importKind === 'type' &&
-                            nameOf(spec.imported) === nameOf(fresh.imported));
-                        if (typeOnly) {
-                            typeOnly.importKind = null;
-                        }
-                        else {
-                            appended.push(fresh);
-                        }
-                    }
-                    existingBestax.node.specifiers = [...current, ...appended];
-                }
-                else if (bestaxImport) {
-                    path.insertBefore(bestaxImport);
-                }
+                placeBestaxImport(bestaxImportState, bestaxImport, path);
                 inserted = true;
             }
             if (keepSpecifiers.length > 0) {
@@ -848,7 +675,7 @@ export default function transform(fileInfo, api, options = {}) {
                 }
             }
             else {
-                carryComments(node, path);
+                carryPrunedComments(node, path, bestaxImportState.existing?.node ?? bestaxImport);
                 path.prune();
             }
             ctx.dirty = true;
@@ -856,6 +683,8 @@ export default function transform(fileInfo, api, options = {}) {
     }
     if (!ctx.dirty)
         return undefined;
+    forgetJsxParens(j, root);
+    reprintDirectives(j, root);
     // Double quotes match the dominant JSX-attribute convention; users run
     // their own formatter afterwards anyway. Tab-indented sources keep tabs so
     // reprinted nodes don't drift from the untouched lines around them.

package/dist/sources/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sources/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAInD,CAAC;AAEF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEnE;AAED,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sources/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAMnD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAKnD,CAAC;AAEF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEnE;AAED,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC"}

package/dist/sources/registry.js

@@ -5,10 +5,12 @@
 import { reactBulmaComponents } from './react-bulma-components/index.js';
 import { rbx } from './rbx/index.js';
 import { bloomer } from './bloomer/index.js';
+import { bulmaClasses } from './bulma-classes/index.js';
 export const SOURCES = {
     [reactBulmaComponents.name]: reactBulmaComponents,
     [rbx.name]: rbx,
     [bloomer.name]: bloomer,
+    [bulmaClasses.name]: bulmaClasses,
 };
 export function getSource(name) {
     return SOURCES[name];

package/dist/types.d.ts

@@ -141,6 +141,31 @@ export interface MigrationSource {
     name: string;
     /** Human-readable label for the report header. */
     label: string;
+    /**
+     * The npm package this source migrates away from, when it is not `name`.
+     * `null` for a source with no package to move off: nothing is looked for
+     * in imports, and the manifest pass is never told the source is still
+     * imported.
+     */
+    packageName?: string | null;
+    /**
+     * Facts about the project, read once from the run's targets and passed to
+     * every transform call as options.
+     */
+    analyzeProject?: (targets: string[]) => object;
+    /** The `--css` mode when the run names none; `bestax` when omitted. */
+    defaultCssMode?: CssMode;
+    /**
+     * For a source with no package: the 1-based line of the first thing in an
+     * unparseable file (`.mdx`, `.vue`, …) that the source would have converted,
+     * or null. Such files are reported, never rewritten.
+     */
+    findUnsupportedReference?: (text: string) => number | null;
+    /**
+     * Which of the unparseable formats `findUnsupportedReference` scans; all
+     * of them when omitted.
+     */
+    unsupportedExtensions?: readonly string[];
     transform: Transform;
     transformStyles?: StylesTransform;
     updateDependencies?: DependenciesUpdate;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,aAAa,GAAG,SAAS,EACpC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,IAAI,CAAC;AAEnB,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,aAAa,GAAG,SAAS,EACpC,OAAO,EAAE,WAAW,KACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;AAEpC,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IAC/C,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC3D;;;OAGG;IACH,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,SAAS,EAAE,SAAS,CAAC;IACrB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bestax-migrate",
-  "version": "2.3.8",
+  "version": "2.4.0",
   "description": "Codemods for migrating existing React apps from other Bulma libraries to @allxsmith/bestax-bulma",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "jscodeshift": "^17.3.0",
-    "@allxsmith/bestax-bulma": "^5.16.7"
+    "@allxsmith/bestax-bulma": "^5.16.9"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
@@ -67,10 +67,11 @@
     "validate:corpus": "pnpm run build && node scripts/validate-corpus.mjs",
     "validate:corpus:rbx": "pnpm run build && node scripts/validate-corpus-rbx.mjs",
     "validate:corpus:bloomer": "pnpm run build && node scripts/validate-corpus-bloomer.mjs",
+    "validate:corpus:bulma-classes": "pnpm run build && node scripts/validate-corpus-bulma-classes.mjs",
     "format": "prettier --write \"src/**/*.{ts,tsx}\" \"e2e/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx}\" \"e2e/**/*.ts\"",
     "clean": "rimraf dist",
     "release": "npx semantic-release"
   },
-  "readme": "# bestax-migrate\n\n[![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/bestax-migrate/latest)](https://socket.dev/npm/package/bestax-migrate/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nCodemods 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**.\n\nCurrently supported source libraries:\n\n| Source                                                                           | Status                                                                             |\n| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs)                  |\n| [`rbx`](https://github.com/dfee/rbx) (v2)                                        | ✅ Full export surface mapped (a few patterns are flagged as TODOs)                |\n| [`bloomer`](https://github.com/AlgusDark/bloomer) (0.6)                          | ✅ All 108 exports mapped (Font Awesome 4 icons and Bulma 0.4's `Nav` are flagged) |\n\nPass the source library as the first argument: `bestax-migrate <source> <paths…>`.\n\n## Requirements\n\n**Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the CLI\nexits immediately with an explicit upgrade message.\n\nThis applies only to the Node version the codemod itself runs on. It places no requirement on\nthe app being migrated — the source is read as text and is never executed.\n\n## Usage\n\n```bash\n# Preview what would change (no writes)\npnpm dlx bestax-migrate react-bulma-components src/ --dry\n# …or, for an rbx or bloomer app\npnpm dlx bestax-migrate rbx src/ --dry\npnpm dlx bestax-migrate bloomer src/ --dry\n\n# Apply the migration\npnpm dlx bestax-migrate react-bulma-components src/\n```\n\nnpm and yarn work too: `npx bestax-migrate …` / `yarn dlx bestax-migrate …`.\n\nThe codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:\n\n- rewrite the source library's imports to `@allxsmith/bestax-bulma` (including destructuring and namespace imports)\n- 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`)\n- convert props (`renderAs` → `as`, `loading` → `isLoading`, numeric spacing/text sizes → string unions, `textAlign=\"center\"` → `textAlign=\"centered\"`, …)\n- flatten responsive breakpoint objects (`mobile={{ size: 4 }}` → `sizeMobile={4}`) and bloomer's `isDisplay`/`isHidden` strings, arrays and objects (`isHidden=\"touch\"` → `visibilityTouch=\"hidden\"`)\n- restructure patterns bestax models differently (`Table.Container`, Navbar dropdowns, `Form.Help`, icon-font children → `<Icon name=…>`)\n- 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'`\n- 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\n\nAnything 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:\n\n```bash\nnpx skills add https://github.com/allxsmith/bestax --skill bestax-migrate\n```\n\n## Options\n\n| Flag                 | Description                                                    |\n| -------------------- | -------------------------------------------------------------- |\n| `--dry`, `-d`        | Report what would change without writing files                 |\n| `--print`, `-p`      | Print transformed sources to stdout                            |\n| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`) |\n| `--css <mode>`       | Stylesheet target: `bestax` (default), `bulma`, or `keep`      |\n| `--no-deps`          | Skip updating package.json dependencies                        |\n\n## After the codemod\n\n1. Run your package manager's install (the codemod rewrote `package.json` but never installs)\n2. Search for `TODO(bestax-migrate)` and resolve each comment\n3. Typecheck/build and review the rendered app\n\nFull 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).\n\n## Hardened by default\n\nA codemod rewrites your source in place, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/bestax-migrate#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **The libraries this tool migrates away from are never installed here** — source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`bestax-migrate` can send one **anonymous** usage event after a successful\nrun — only if you opt in when asked (once, on an interactive terminal). The\nevent is just the run's shape — source library, CSS mode, the dry/deps flags, a\ncapped changed-file count, and per-rule TODO counts — plus the CLI version,\nNode major version, and OS platform name. Never file paths, file contents,\ncode, names, IPs, or machine IDs, and no identifier exists that could link two\nevents together. Opt out any time with `--no-telemetry`,\n`BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## License\n\nSource code licensed MIT\n"
+  "readme": "# bestax-migrate\n\n[![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/bestax-migrate/latest)](https://socket.dev/npm/package/bestax-migrate/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nCodemods 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**.\n\nCurrently supported sources:\n\n| Source                                                                           | Status                                                                               |\n| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs)                    |\n| [`rbx`](https://github.com/dfee/rbx) (v2)                                        | ✅ Full export surface mapped (a few patterns are flagged as TODOs)                  |\n| [`bloomer`](https://github.com/AlgusDark/bloomer) (0.6)                          | ✅ All 108 exports mapped (Font Awesome 4 icons and Bulma 0.4's `Nav` are flagged)   |\n| `bulma-classes`: Bulma's classes on plain JSX, no library                        | ✅ Converts an element only when bestax renders the same markup; the rest is flagged |\n\nPass the source as the first argument: `bestax-migrate <source> <paths…>`.\n\n## Requirements\n\n**Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the CLI\nexits immediately with an explicit upgrade message.\n\nThis applies only to the Node version the codemod itself runs on. It places no requirement on\nthe app being migrated — the source is read as text and is never executed.\n\n## Usage\n\n```bash\n# Preview what would change (no writes)\npnpm dlx bestax-migrate react-bulma-components src/ --dry\n# …or, for an rbx or bloomer app\npnpm dlx bestax-migrate rbx src/ --dry\npnpm dlx bestax-migrate bloomer src/ --dry\n# …or, for an app that writes Bulma's classes on plain JSX\npnpm dlx bestax-migrate bulma-classes src/ --dry\n\n# Apply the migration\npnpm dlx bestax-migrate react-bulma-components src/\n```\n\nnpm and yarn work too: `npx bestax-migrate …` / `yarn dlx bestax-migrate …`.\n\nThe codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:\n\n- rewrite the source library's imports to `@allxsmith/bestax-bulma` (including destructuring and namespace imports)\n- 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`)\n- convert props (`renderAs` → `as`, `loading` → `isLoading`, numeric spacing/text sizes → string unions, `textAlign=\"center\"` → `textAlign=\"centered\"`, …)\n- flatten responsive breakpoint objects (`mobile={{ size: 4 }}` → `sizeMobile={4}`) and bloomer's `isDisplay`/`isHidden` strings, arrays and objects (`isHidden=\"touch\"` → `visibilityTouch=\"hidden\"`)\n- 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\n- restructure patterns bestax models differently (`Table.Container`, Navbar dropdowns, `Form.Help`, icon-font children → `<Icon name=…>`)\n- 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'`\n- 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\n\nAnything 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:\n\n```bash\nnpx skills add https://github.com/allxsmith/bestax --skill bestax-migrate\n```\n\n## Options\n\n| Flag                 | Description                                                                                    |\n| -------------------- | ---------------------------------------------------------------------------------------------- |\n| `--dry`, `-d`        | Report what would change without writing files                                                 |\n| `--print`, `-p`      | Print transformed sources to stdout                                                            |\n| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`)                                 |\n| `--css <mode>`       | Stylesheet target: `bestax`, `bulma`, or `keep` (default `bestax`; `keep` for `bulma-classes`) |\n| `--no-deps`          | Skip updating package.json dependencies                                                        |\n\n## After the codemod\n\n1. Run your package manager's install (the codemod rewrote `package.json` but never installs)\n2. Search for `TODO(bestax-migrate)` and resolve each comment\n3. Typecheck/build and review the rendered app\n\nFull 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).\n\n## Hardened by default\n\nA codemod rewrites your source in place, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/bestax-migrate#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **The libraries this tool migrates away from are never installed here** — source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`bestax-migrate` can send one **anonymous** usage event after a successful\nrun — only if you opt in when asked (once, on an interactive terminal). The\nevent is just the run's shape — source library, CSS mode, the dry/deps flags, a\ncapped changed-file count, and per-rule TODO counts — plus the CLI version,\nNode major version, and OS platform name. Never file paths, file contents,\ncode, names, IPs, or machine IDs, and no identifier exists that could link two\nevents together. Opt out any time with `--no-telemetry`,\n`BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## License\n\nSource code licensed MIT\n"
 }