git:20261018.fe05614 to git:20261018.c2e22b4

# bestax-migrate — codemods onto bestax-bulma

jscodeshift-based CLI (`pnpm dlx bestax-migrate <source> <paths…>`) that migrates existing

apps from other React Bulma libraries to `@allxsmith/bestax-bulma`. Multi-source by design:

each source registers in `src/sources/registry.ts`. The library sources are

`react-bulma-components` (v4 only), `rbx` (v2 only) and `bloomer` (0.6 only); `bulma-classes`

is the one with no library behind it, converting raw Bulma classes on plain JSX.

## Hard rules

- **No source library is EVER installed anywhere in this repo** (supply-chain policy) —

not react-bulma-components, not rbx, not bloomer. Fixtures are read as _text_ (`__testfixtures__`,

`fixtures/kitchen-sink`, `fixtures/rbx-kitchen-sink`, `fixtures/bloomer-kitchen-sink`); the migration _input_ is never

typechecked or executed. Validation typechecks the migrated _output_ against the

workspace `@allxsmith/bestax-bulma`. The kitchen-sink manifests are named

`package.input.json`, not `package.json`: Dependabot's alert graph treats any file with

that name as a real manifest whatever the lockfile says, and opened a security-update PR

against the rbx fixture's deliberately-old `node-sass` (#615). The e2e renames its copy

back inside `.e2e-tmp`, so the pass under test still sees a genuine `package.json`.

`bulma-classes` has no library, so its input is plain JSX, and its tests DO run and

typecheck the input: rendering input and output side by side is how it proves a conversion

changed nothing. That is the one exception, and it installs nothing.

- Mapping-table first: each source's `mapping.ts` is its single source of truth. Every

export of that library must have an entry (`mapped`/`partial`/`todo`) — the

`mapping-coverage` test walks the vendored `RBC_EXPORTS` / `RBX_EXPORTS` / `BLOOMER_EXPORTS` list against it,

in both directions, so the table cannot grow an entry for something the library never

exported either. New coverage is a table edit (plus a `special` handler in `specials.ts`

when structure changes). `bulma-classes`' table is `class-map.ts`, and its export list is

Bulma's own stylesheet: `e2e/bulma-classes-vocabulary.test.ts` classifies every class in it.

- **A new source is a directory plus one registry line.** `src/sources/_shared/` holds

everything library-agnostic: `jsx-utils.ts` (AST helpers + `TransformContext`),

`props.ts` (the `PropAction` interpreter — its universal table is a parameter, not an

import), `imports.ts` (binding collection and import aliasing), `specials-utils.ts`

(`alignTarget`, `mergeClassName`, `parseIconClasses`, `modifierClass`, `restrictAsToTargets`,

the `stripModifierProps` factory and the `makeStructuralHelpers` factory behind

`replaceWithPlain`/`collapseOntoChild`), `viewports.ts` (Bulma's viewports → bestax's

prop suffixes), `css-imports.ts` (the stylesheet-import pass), `bestax-import.ts` (seeding,

building and merging the bestax-bulma import), `deps-common.ts` (the manifest steps after

the source package is handled), and `make-styles-transform.ts` (the whole Bulma 0.9→v1

stylesheet transform, parameterised by the source package's own specifiers). What stays

per-source is the data — `mapping.ts`, `specials.ts`, `responsive.ts`, `deps.ts` — plus a

`transform.ts` that orchestrates them. bloomer's is the plain one: its exports are flat, so it has no

destructuring pass, no alias registry and no wrapping pass; the rbx and RBC copies still

carry all of them.

- `'<source>'` must be added to `MIGRATE_SOURCE_VALUES` in `telemetry-worker/src/schema.ts`

or its events are dropped at ingest; `check:conformance --only=telemetry-allowlists`

fails until it is. That worker deploys to production on merge, so the two land together.

The same check regex-scrapes each source's `index.ts` for

`: MigrationSource = { … name: '…' }` — a declaration that doesn't match that shape is a

hard violation, not a skip.

- Anything unsafe gets a `// TODO(bestax-migrate): <hint>` comment on the enclosing

statement + a report entry — never a silent skip, never a best-guess rewrite of dynamic

values.

- **A TODO message is a claim about bestax; read the component before writing it.** Four

shipped on #613 were false (Modal "always closes on Escape"; a Field TODO naming `isGrouped`).

The rbx e2e fails on an undocumented rule (RBC's does not); nothing checks the guidance is true.

- **A defect in one source's `transform.ts` is almost certainly in the others.** The fixes were

ported RBC↔rbx on #613 and review kept finding the unported half. Fix the siblings in the same

commit, or move the logic into `_shared/` (the alias registry, the literal/object helpers

and the structural-handler helpers went there on #410 for exactly this reason).

- **Resolve references by binding, not by identifier text.** Every serious bug on #613 came

from a name-keyed map (`function F(Header)` became `F(Card.Header)`). Use

`makeAliasRegistry` from `_shared/imports.ts`: ancestors decide ownership, `scope.lookup`

vetoes a nearer binding.

- **The report may only describe what actually happened.** The manifest headline said "bumped

bulma" in most manifest shapes where nothing was bumped. Track each mutation; phrase from it.

- **The stylesheet and manifest passes must agree on what is removable.** Both report rather

than remove `bulma-*` extensions, since markup outside the source may still use their classes.

rbx enumerates them in `deps.ts` and `transform.ts`; the shared Sass pass flags any `bulma-*`.

- **Never change `bulma-ui` to make a migration cleaner.** Map onto the library as it is and

emit a TODO otherwise. A gap earns a `bulma-ui` issue only if it is a bestax defect or the

source is genuinely better, not merely different (#616 to #622 are the worked example).

## Architecture

- `src/cli.ts` — file walk + per-type routing (js-ish → jscodeshift transform,

.scss/.sass → `transformStyles`, nearest package.json → `updateDependencies`) with an

in-process runner (NOT jscodeshift's worker Runner: fragile from ESM, hides per-file

stats). `src/runner.ts` is shared by CLI and tests. `--css bestax|bulma|keep` picks the

stylesheet target, `bestax` unless the source sets its own `defaultCssMode` (bulma-classes

keeps the app's stylesheet, which already styles every class it converts); `--no-deps`

skips the manifest step. The CLI reads a source's

`packageName` (defaulting to its `name`) as the import to look for; `null` means the source

has no package, so no file is ever "still importing" it.

A source with `htmlExtensions` (bulma-classes) also reads HTML pages: a page named on the

command line always, a folder walk's only when `-e` lists its extension, exactly as for every

other file (`html`, `htm`; React repos are full of `.html`

nobody wants converted), and a walk without it hands each page it skipped to the source's

`excludedHtml`, which reports the Bulma ones. `transformHtml` returns the module and where

it goes; the CLI writes it there and never touches the page. A source without HTML support

refuses a named page or an `-e` that lists `html` or `htm` rather than parsing HTML as

JavaScript.

- `src/sources/react-bulma-components/` (and `rbx/`, same shape): `transform.ts`

(orchestration: imports + css → per-element special/rename/responsive/props → import

rewrite), `mapping.ts` (data), `specials.ts` (structural handlers), `responsive.ts`

(breakpoint-object flattening), `styles.ts` (a thin call into `_shared/make-styles-transform.ts`,

line-based because Sass has no jscodeshift parser), `deps.ts` (package.json updater; never

runs an install). The PropAction interpreter and AST helpers live in `_shared/`.

- Components with no bestax equivalent (Element, Tile) keep a trimmed, TODO-annotated RBC

import so the code still runs during gradual migration.

- `src/sources/bulma-classes/` is shaped differently, because it reads markup rather than a

library's API: `class-map.ts` (data only, and imported directly by

`scripts/gen-mcp-index.mjs` for the MCP server's `lookup_bulma_classes`, so no enums or

runtime imports; a change to it wants `pnpm gen:mcp` in the same PR, and bestax-mcp's

tests run this planner beside that tool), `plan.ts` (pure: one element's tag,

classes, attributes, what its children became and the bestax components already around and

inside it in, a conversion, a fold into its only child (a `fold` wrapper such as

`.table-container`) or a TODO out; an entry that `absorbs` its only child (`.select`'s

`<select>`) converts together with it, written in the child's place, and one that

`countsChildren` (`.skeleton-lines`) writes their count and drops them, one that `readsGlyph`

(`.icon`) takes the bare glyph `<i>` it holds as props (`glyph.ts`) and drops it, one that

`buildsIcons` (`.icon-text`) takes its `.icon`s and the texts beside them as props, one that

`buildsFile` (`.file`) takes its whole tree as props, inside a `Field` only, and one with a

`parent` (`.pagination-link`) takes the place of the bare `<li>` its target renders too; an entry

with `wrapsChildren` converts only beside one of its parts, so `transform.ts` plans children

before their parents; and an element with no class to go by, a menu list's `<li>`, is found

by the list around it and planned as the `PLACED` entry for that list), `rules.ts` (rule ids from a closed

vocabulary, since the input is the app's own class strings and telemetry must never carry

them), `project.ts` (what one file cannot show: which packages are Next.js App Router

projects, which render JSX through a runtime other than React, and which are TypeScript, for

the extension of the module an HTML page becomes, and which depend on Next.js, where that

module imports no stylesheet, read once per run from every package.json the run touches) and `transform.ts` (finds the elements, reads a

`className` a `clsx` or `classnames` call builds when it can read every argument, applies the

plans, writes the import after the file's last one). The fixture render test runs the real

`clsx` and `classnames`, which is why they are dev dependencies. An element converts only when the component renders the same markup; the render

tests in `e2e/bulma-classes-*.test.ts` hold every entry to that, and

`e2e/bulma-classes-props.test.ts` to the component's props type, which can be narrower than

what it renders. One exception is deliberate (#1148): Font Awesome's own

`<i aria-hidden="true">`, alone in a `.icon` that carries nothing assistive tech reads,

converts to `Icon`, which writes that attribute on the `.icon` instead, because the glyph is

it, and beside a `role` or `tabIndex` `Icon` writes no `aria-hidden` at all, so an expression

there must refuse too. The planner marks it `movesHidden`, and the render tests compare it

through `e2e/support/hidden-glyph.ts`, which moves the attribute up in that one shape, behind

the same whitelist, and leaves every other difference to fail.

Widen it only with the same care: a new exception is a claim that the page is unchanged for

everyone who reads it, which identical markup proves and a normalization only asserts.

- The bulma-classes HTML input is `bulma-classes/html.ts`: parse the page, drop its scripts

(each a report), emit its body as JSX with `pageDisplayOf` (an element's inline display, else

the displays `display.ts` says Bulma's classes give it across viewports, else its tag's; a

box `display.ts`'s `OUT_OF_FLOW` lists counts as no box, and where the cases differ the one

kept is the one that keeps every run any of them would), wrap it in a module, run

`transform.ts` on that module **unchanged**, at the path the module goes to so the rsc and

jsx-runtime gates apply, then `finishModule` (numbers on plain elements, the import's blank

line). What a component can't carry becomes a TODO line plus a report entry under the

`html-*` rules in `html-rules.ts`, kept apart from `rules.ts` because none of it is about a

Bulma class; an id carries only a fixed name, never the page's text, and falls back to the

bare kind. Report entries name the page and its line, the planner's mapped back through the

emitter's line map. `html-assets.ts` says what each stylesheet and script the page loads is,

from its URL, and each extension's message names the bestax component only where reading it

showed one does the extension's job. Under `--css bestax` or `--css bulma` the page's Bulma

`<link>` becomes `import 'bulma/css/bulma.min.css'` in the module before the transform runs,

so the shared stylesheet pass retargets it exactly as in a JSX file, and the CLI reads the

module for `bulmaReferenced` as it reads a JSX file's output, so the manifest step agrees.

Not in a Next.js app (its Pages Router takes a global stylesheet only in `pages/_app`), and

not for a `<link media>`, which an import can't stand for. A local file is read only inside

the page's folder, and a `<script src>` only when its type is JavaScript.

`display.ts` is held to `bulma.css` by `e2e/bulma-classes-display.test.ts`, both tables and

the out-of-flow list.

- `src/sources/_shared/html/` turns HTML into JSX source, library-agnostic: `parse.ts` (parse5,

as a document or a fragment), `attributes.ts` (attribute to prop by `property-information`,

plus what React needs written by hand; numbers stay strings for the planner, and

`numberLiteral` writes them as numbers afterwards), `style.ts`, `text.ts` (escaping and

comments), `whitespace.ts` (which whitespace renders, laid out the CSS way, each element's

display coming from a `displayOf` hook that defaults to the HTML UA stylesheet) and `emit.ts`

(the JSX on the source's own lines, a map from its lines back to the HTML's, and a report of

what it could not write as it was). It never decides what a report becomes: the caller turns

each into a TODO or a rule id. `e2e/html-converter-round-trip.test.ts` renders what it writes

and compares the DOM with the page's, and `e2e/html-attributes-react.test.ts` holds

`REACT_UNKNOWN` to React.

- `src/telemetry-core.ts` is a byte-for-byte copy of

`create-bestax/src/telemetry-core.ts` — never edit it here; edit the

create-bestax original and copy it over (`check:conformance

--only=telemetry-core` enforces identity). This package's payload builder and

caps live in `src/telemetry.ts`; the caps are pinned to the ingest worker's

bounds by `scripts/telemetry-contract.test.mjs`.

## Testing

- Fixture pairs: `__testfixtures__/<case>.input.tsx` → `.output.tsx`, exact-match. To

update outputs after changing the transform, regenerate them by running the built

transform over the inputs and reviewing the diff — do not hand-edit drift in.

The HTML input's pairs are `bulma-classes/__testfixtures__/html/<case>.input.html` →

`<case>.output.tsx`, regenerated the same way from the built `convertPage`

(`dist/sources/bulma-classes/html.js`), each converted as `<case>.html` so its component is

named from the case.

- The HTML input has e2es of its own. `e2e/bulma-classes-html-render.test.ts` wants one DOM

from the page's body as parse5 builds it, the module before the planner rendered, and the

module after it rendered, so the page matching the first module proves the converter and the

modules matching each other prove the planner. It normalizes with `e2e/support/dom-canonical.ts`, the round-trip test's normalizer,

given the converter's own display hook. `e2e/bulma-classes-html-kitchen-sink.test.ts` converts

`fixtures/bulma-classes-html/` under `--css keep` and `--css bestax`, asserts each page's rules

exactly, typechecks the output (`pages/leftovers.html` holds every pattern a component can't

carry, its own script beside it in `pages/js/`, and its module stays out of the typecheck),

and wants `html-file:exists` alone on a second run. Both kitchen sinks hold every rule they

emit to the skill's references through `e2e/support/skill-rules.ts`.

- Kitchen sink e2e (`e2e/kitchen-sink.test.ts`): copies `fixtures/kitchen-sink` to a

`mkdtemp`'d dir under `.e2e-tmp/`, migrates it, and runs `tsc --noEmit` on the output

against the built bulma-ui (`turbo` orders the build; see `bestax-migrate#test` in root

turbo.json). The scratch dir is **per process, never a fixed path**: `pnpm all` runs

`test` and `test:coverage` in one turbo invocation, so two jest processes run this file

concurrently and a shared path lets them clobber each other's rmSync/cpSync — the suite

then fails as though the codemod had not run. `BESTAX_E2E_KEEP=1` leaves the dir behind.

`src/leftovers.tsx` holds every intentionally-unsupported pattern — excluded from the

typecheck, asserted via TODO rules instead. New unsupported patterns go there; new

supported ones go in the other fixture files, which must stay TODO-free.

- `e2e/rendered-output.test.ts` renders the migrated kitchen sinks to HTML, and

`e2e/support/render-module.ts` is the harness for any test that does. It loads React,

`react-dom/server` and bestax-bulma from **bulma-ui's** directory, never this package's: the

workspace can hold two React copies, and a component rendered by the other one fails on its

first hook.

- Fixtures and `.e2e-tmp` are excluded from tsc/eslint/prettier at both root and package

level (root `eslint.config.js` + both `.prettierignore`s) — keep them that way.

- Real-world corpus scripts. The ones that fetch read a pinned SHA as text only into

`.e2e-tmp/`; all of them fail on any crash, and the library sources' on an

unknown-component TODO too. Deliberately NOT in CI (no third-party fetches in the

pipeline); run them before releases and after mapping changes, and eyeball the

before/after diffs they write:

- `validate:corpus` — react-bulma-components' own MIT Storybook stories →

`.e2e-tmp/corpus-out/`.

- `validate:corpus:rbx` — rbx's own MIT docs. rbx used **docz**, not Storybook, so the

script extracts the `<Playground>` blocks out of its `*.docs.mdx` pages

and rebuilds each page as one synthetic module written the way a consumer writes rbx.

Output lands in `.e2e-tmp/corpus-out-rbx/`.

- `validate:corpus:bloomer` — bloomer's own MIT docs: 39 React "Scene" `.tsx` files that

render the library through a relative `src` import, migrated as written after that

specifier becomes `'bloomer'`. Output lands in `.e2e-tmp/corpus-out-bloomer/`.

- `validate:corpus:bulma-classes` — this repo's own stories, which mix components with raw

Bulma markup; `--dir <path>` points it at any app's source instead. Nothing is fetched.

Output lands in `.e2e-tmp/corpus-out-bulma-classes/`.

- `validate:corpus:templates` — the HTML input over the awesome-bulma-templates repos, each

fetched at the commit pinned in `scripts/lib/corpus-templates.mjs` (the one home of those

pins, checked for shape only, so a moved pin is compared with its port issue by hand) and

converted by the CLI with `--css bestax` in a scratch package where every page becomes

`.tsx`. It needs the network, which is why it stays out of CI with the others, and it

refuses to start until bestax-bulma is built, since tsc reads it for every module. It

also fails on a module that no longer parses, on one tsc could not read, and on a rule the

skill's references don't document (the kitchen sinks' check), and it lists the modules'

`tsc` diagnostics without failing on them. `report.md` and `report.json` in

`.e2e-tmp/corpus-templates/` are deterministic, so the reports from before and after a

change to the HTML input or the class table diff line by line: that diff is how such a

change is measured. A page's classes are counted from its DOM, so a refused page keeps

its count. `e2e/corpus-templates.test.ts` tests the script's offline half.

The corpus is the only check that sees breadth; the kitchen-sink e2e is the only one that

sees bestax's _real_ prop names. Both are needed — the rbx e2e's typecheck caught

mapping errors that 254 clean Playgrounds had not.

- After editing a test file, check the total test count did not drop: a range replacement

between two non-adjacent `describe` blocks deleted 868 lines on #613 and the suite stayed green

at 699 instead of 781. Compare the `Tests:` line from `pnpm test` (bare `jest` miscounts on ESM).

## Releases

Independent semantic-release, keyed off the `bestax-migrate` commit scope

(`release.config.js`, tag `bestax-migrate@x.y.z`).

**Publishing is shared, and this package is why it looks the way it does.**

Every package here publishes with `pnpm publish` rather than `npm publish`

(#436, then #532), through the plugin pair in `scripts/lib/pnpm-publish.mjs`.

The mechanism and the ways it fails quietly are documented once in

`VERSIONING.md` and in that helper. The `prepack` / `prepublishOnly` guard is

documented in `scripts/require-pnpm-publish.mjs`, and that header is worth

reading before touching it: why it keys on `npm_execpath` rather than the

inherited `npm_config_user_agent`, and why it refuses only packers it can

name instead of allow-listing pnpm. `pnpm check:conformance` reports a

violation if either hook is missing, so the exemption and the guard that

compensates for it cannot drift apart.

What is specific to bestax-migrate is the specifier that forced it.

`npm publish` does not resolve pnpm's `workspace:` protocol, so the

`workspace:^` below shipped verbatim in 1.0.0 and made the package

uninstallable (#412). That was first patched by a `prepack` hook

reimplementing pnpm's rewrite, and the reimplementation was wrong twice in one

review — which is the whole argument for handing the job to pnpm instead of

owning a subset of its logic. It was the only package carrying such a

specifier until #644 put one in every CLI, so all three tarballs are worth

inspecting after any change to how packing works: `pnpm -C bestax-migrate pack`,

and the same for `create-bestax` and `bestax-mcp`.

`@allxsmith/bestax-bulma` is a declared **dependency** (#644): the codemod is

built for the library and its manifest says so, the way bulma-ui declares

`bulma`. Nothing in `src/` imports it at runtime — it is the typecheck target

for the e2e and the source of the `valid*` constants the value-union tests diff

against — and consumers of the CLI now install it along with `bulma` and, under

npm's automatic peer install, `react`/`react-dom`. `publishable-manifests`

(#537) still forbids a workspace sibling in `dependencies`/`optionalDependencies`

**whatever the specifier says**; this one passes only because

`SIBLING_RUNTIME_DEPS` in `scripts/check-conformance.mjs` declares the exact

pair, and a test holds that declaration to the real manifest. One appearance

that is NOT this dependency: the e2e asserts the **migrated app's** manifest

depends on the library (`e2e/kitchen-sink.test.ts`) — that is the codemod's

output, which should depend on it, and no check reads it.

The skill lives at repo-root

`skills/bestax-migrate/`. It **is** bundled into create-bestax (settled in #385): the

original existing-sites-only policy lost to one uniform bundle, and the skill sits idle

in a fresh scaffold until legacy imports show up. The canonical roster of surfaces that

must agree on bundling lives in `create-bestax/CLAUDE.md`'s sync rules — don't restate

it here. When the mapping gains or loses coverage, update

`skills/bestax-migrate/references/` and the docs migration guide in the same PR.

### Codemod Registry

`codemod/` is this CLI's package in the Codemod Registry (`npx codemod bestax-migrate`).

The registry has no jscodeshift engine, so it is a wrapper: its workflows run

`npx --yes bestax-migrate@<version>` as a Codemod shell step. `.github/workflows/codemod-registry.yml`

publishes it by manual dispatch, and `scripts/codemod-registry.mjs` holds the checks.

- **The pins name one exact release and trail `package.json` between bumps.**

codemod.yaml's `version`, each `bestax-migrate@` in `codemod/`, and `package.json` must

agree when the workflow publishes, and the registry refuses a version it already has.

semantic-release moves only `package.json`, so the pins stay put until

`node scripts/codemod-registry.mjs bump` moves them in a `build(bestax-migrate)` change.

The test sibling holds the committed pins to agreeing with each other and to not leading

`package.json`. It never requires equality, because that would fail every open PR after

each release.

- **`preview` exists because Codemod's `--dry-run` skips shell steps.** It is the same

command with `--dry`. Keep the two workflows' params in step.

- **The `codemod/` workflows read params from `PARAM_*` environment variables**, which Codemod

sets for shell steps. Never put `${{ params.* }}` in a `run:` line: Codemod substitutes it

into the command before the shell parses it, so a value could run as code.

- **`codemod/` does not ship on npm.** `files` names only `dist`, and a test fails on an

entry that could cover `codemod/`. Re-check with `pnpm -C bestax-migrate pack` after any

change to `files`.

- **Nothing but the registry package goes in `codemod/`.** `codemod publish` uploads every

file in it. That is why the `codemod` CLI's own package.json and lockfile live in

`.github/codemod-cli/`, outside this package.