bestax-migrate 0.0.1

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

@@ -0,0 +1,495 @@
+/**
+ * The react-bulma-components (v4) → @allxsmith/bestax-bulma transform.
+ *
+ * Passes, in order:
+ *   1. resolve imports (named/namespace) and `const { X } = Form`-style
+ *      destructuring into canonical RBC component paths
+ *   2. per-element: structural special → rename → responsive flattening →
+ *      component prop map → universal modifier props
+ *   3. rewrite imports: drop RBC, add one merged bestax-bulma import; keep a
+ *      trimmed RBC import (with a TODO) only for components that have no
+ *      bestax equivalent (Element, Tile)
+ *
+ * Anything unsafe gets a `// TODO(bestax-migrate)` comment on the enclosing
+ * statement plus an entry in the run report.
+ */
+import { MAPPING, resolveMapping } from './mapping.js';
+import { addTodo, attributesOf, jsxNameParts, renameElement, } from './jsx-utils.js';
+import { applyPropAction, applyUniversalProps } from './props.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);
+    const ctx = {
+        j,
+        file: fileInfo.path,
+        collector: options.collector,
+        retained: new Set(),
+        needed: new Map(),
+        reserve: root => root, // replaced below once local bindings are known
+        overrides: new WeakMap(),
+        dirty: false,
+    };
+    // ---- 1. Collect RBC imports -------------------------------------------
+    /** local identifier → imported RBC name ('*' for namespace imports). */
+    const imports = new Map();
+    /** local identifier → canonical RBC path (from destructuring). */
+    const aliases = new Map();
+    const rbcImportPaths = [];
+    const nameOf = (node) => typeof node === 'string' ? node : String(node?.name ?? '');
+    root.find(j.ImportDeclaration).forEach(path => {
+        const source = String(path.node.source.value);
+        if (source === RBC) {
+            rbcImportPaths.push(path);
+            for (const spec of path.node.specifiers ?? []) {
+                if (spec.type === 'ImportSpecifier' && spec.local) {
+                    imports.set(nameOf(spec.local), nameOf(spec.imported));
+                }
+                else if (spec.type === 'ImportNamespaceSpecifier' && spec.local) {
+                    imports.set(nameOf(spec.local), '*');
+                }
+                else if (spec.type === 'ImportDefaultSpecifier') {
+                    // RBC has no default export; leave it and flag it.
+                    addTodo(ctx, path, 'imports', 'react-bulma-components has no default export; convert to named imports first');
+                }
+            }
+        }
+        else if (source.startsWith(`${RBC}/`) && source.endsWith('.css')) {
+            // v3-era bundled CSS import — handled by the CSS pass below.
+        }
+        else if (source.startsWith(`${RBC}/`)) {
+            addTodo(ctx, path, 'imports', 'deep react-bulma-components import paths are a v3 pattern; move to v4 named root imports first');
+        }
+    });
+    // ---- 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)`);
+        }
+    });
+    if (imports.size === 0 && !ctx.dirty) {
+        return undefined;
+    }
+    // ---- 1b. Resolve `const { Input, Field: F } = Form` destructuring -----
+    root.find(j.VariableDeclarator).forEach(path => {
+        const node = path.node;
+        if (node.id?.type !== 'ObjectPattern' || node.init?.type !== 'Identifier')
+            return;
+        const base = node.init.name;
+        const imported = imports.get(base) ?? aliases.get(base)?.join('.');
+        if (!imported || imported === '*')
+            return;
+        const basePath = imports.has(base)
+            ? [imports.get(base)]
+            : aliases.get(base);
+        let allResolved = true;
+        for (const prop of node.id.properties) {
+            if ((prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+                prop.key?.type === 'Identifier' &&
+                prop.value?.type === 'Identifier') {
+                aliases.set(prop.value.name, [...basePath, prop.key.name]);
+            }
+            else {
+                allResolved = false;
+            }
+        }
+        if (allResolved) {
+            const declaration = path.parent;
+            if (declaration?.node?.type === 'VariableDeclaration' &&
+                declaration.node.declarations.length === 1) {
+                declaration.prune();
+            }
+            else {
+                path.prune();
+            }
+            ctx.dirty = true;
+        }
+        else {
+            addTodo(ctx, path, 'imports', `could not resolve every name destructured from \`${base}\`; migrate the leftovers by hand`);
+        }
+    });
+    /** Resolve a JSX name into a canonical RBC component path, or null. */
+    function resolveJsxPath(name) {
+        const parts = jsxNameParts(name);
+        if (!parts)
+            return null;
+        const [head, ...rest] = parts;
+        if (aliases.has(head))
+            return [...aliases.get(head), ...rest];
+        const imported = imports.get(head);
+        if (imported === undefined)
+            return null;
+        if (imported === '*')
+            return rest.length > 0 ? rest : null;
+        return [imported, ...rest];
+    }
+    ctx.resolve = resolveJsxPath;
+    // ---- 1c. Collect local bindings so new imports never collide -----------
+    // A file may already bind names like `Field` or `Control` (components,
+    // variables, function params); importing the bestax component under the
+    // same name would redeclare it, so those imports get a Bulma* alias.
+    const bound = new Set();
+    const collectPattern = (node) => {
+        if (!node)
+            return;
+        switch (node.type) {
+            case 'Identifier':
+                bound.add(node.name);
+                break;
+            case 'ObjectPattern':
+                for (const prop of node.properties ?? []) {
+                    collectPattern(prop.value ?? prop.argument);
+                }
+                break;
+            case 'ArrayPattern':
+                for (const el of node.elements ?? [])
+                    collectPattern(el);
+                break;
+            case 'RestElement':
+                collectPattern(node.argument);
+                break;
+            case 'AssignmentPattern':
+                collectPattern(node.left);
+                break;
+        }
+    };
+    root.find(j.VariableDeclarator).forEach(path => collectPattern(path.node.id));
+    root.find(j.FunctionDeclaration).forEach(path => {
+        if (path.node.id)
+            bound.add(nameOf(path.node.id));
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root
+        .find(j.ClassDeclaration)
+        .forEach(path => path.node.id && bound.add(nameOf(path.node.id)));
+    root.find(j.FunctionExpression).forEach(path => {
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root.find(j.ArrowFunctionExpression).forEach(path => {
+        for (const param of path.node.params ?? [])
+            collectPattern(param);
+    });
+    root.find(j.ImportDeclaration).forEach(path => {
+        if (String(path.node.source.value) === RBC)
+            return; // pruned later
+        for (const spec of path.node.specifiers ?? []) {
+            if (spec.local)
+                bound.add(nameOf(spec.local));
+        }
+    });
+    ctx.reserve = (importedName) => {
+        const existing = ctx.needed.get(importedName);
+        if (existing)
+            return existing;
+        let local = importedName;
+        if (bound.has(local)) {
+            local = `Bulma${importedName}`;
+            let suffix = 2;
+            const locals = new Set(ctx.needed.values());
+            while (bound.has(local) || locals.has(local)) {
+                local = `Bulma${importedName}${suffix}`;
+                suffix += 1;
+            }
+        }
+        ctx.needed.set(importedName, local);
+        return local;
+    };
+    // Merge with an existing bestax import: reuse its locals verbatim.
+    const existingBestax = root
+        .find(j.ImportDeclaration, { source: { value: BESTAX } })
+        .paths()[0];
+    const preExistingImports = new Set();
+    if (existingBestax) {
+        for (const spec of existingBestax.node.specifiers ?? []) {
+            if (spec.type === 'ImportSpecifier' && spec.local) {
+                ctx.needed.set(nameOf(spec.imported), nameOf(spec.local));
+                preExistingImports.add(nameOf(spec.imported));
+            }
+        }
+    }
+    // ---- 2. Transform JSX elements ----------------------------------------
+    root.find(j.JSXElement).forEach(path => {
+        const element = path.node;
+        const rbcPath = resolveJsxPath(element.openingElement.name);
+        if (!rbcPath)
+            return;
+        const mapping = resolveMapping(rbcPath);
+        const dotted = rbcPath.join('.');
+        if (!mapping) {
+            ctx.retained.add(rbcPath[0]);
+            addTodo(ctx, path, 'unknown-component', `\`${dotted}\` is not a known react-bulma-components v4 export; migrate it by hand`);
+            return;
+        }
+        if (mapping.status === 'todo') {
+            ctx.retained.add(rbcPath[0]);
+            addTodo(ctx, path, `component:${dotted}`, `\`${dotted}\` — ${mapping.todo ?? 'migrate by hand'}`);
+            return;
+        }
+        // Structural special first — it may pick the target or replace the node.
+        let target = mapping.target;
+        const handled = new Set();
+        if (mapping.special) {
+            const result = runSpecial(mapping.special, ctx, path, element);
+            if (result.replaced)
+                return;
+            if (result.target)
+                target = result.target;
+            for (const prop of result.handledProps ?? [])
+                handled.add(prop);
+        }
+        // A parent's structural handler may have picked this element's target.
+        const override = ctx.overrides.get(element);
+        if (override)
+            target = override;
+        if (!target)
+            return;
+        // Rename to the bestax name, aliasing the import root on collision.
+        const [targetRoot, ...targetRest] = target.split('.');
+        const localTarget = [ctx.reserve(targetRoot), ...targetRest].join('.');
+        const currentParts = jsxNameParts(element.openingElement.name);
+        if (!currentParts || currentParts.join('.') !== localTarget) {
+            renameElement(j, element, localTarget);
+            ctx.dirty = true;
+        }
+        // Responsive breakpoint objects (with Columns/Column extensions).
+        const kind = mapping.special
+            ? (RESPONSIVE_KINDS[mapping.special] ?? 'generic')
+            : 'generic';
+        flattenResponsiveProps(ctx, path, element, kind);
+        // Component-specific prop actions, then the universal modifier pass.
+        if (mapping.props) {
+            for (const attr of [...attributesOf(element)]) {
+                const name = attr.name.name;
+                const action = mapping.props[name];
+                if (!action || handled.has(name))
+                    continue;
+                handled.add(name);
+                applyPropAction(ctx, path, element, attr, action);
+            }
+        }
+        applyUniversalProps(ctx, path, element, handled);
+    });
+    // ---- 2b. Value references to RBC components ---------------------------
+    // Components can be referenced as plain values too (`renderAs={Block}`,
+    // passed to helpers, …). JSX usages were renamed above; map the leftover
+    // identifier references so the pruned RBC import doesn't strand them.
+    root.find(j.Identifier).forEach(path => {
+        // find(Identifier) also matches JSXIdentifier (a subtype) — JSX names
+        // were already handled by the element walker above.
+        if (path.node.type !== 'Identifier')
+            return;
+        const name = path.node.name;
+        const imported = imports.get(name);
+        if (imported === undefined || imported === '*')
+            return;
+        const parentNode = path.parent?.node;
+        const parentType = parentNode?.type;
+        if (parentType === 'ImportSpecifier' ||
+            parentType === 'ImportDefaultSpecifier' ||
+            parentType === 'ImportNamespaceSpecifier' ||
+            parentType === 'JSXOpeningElement' ||
+            parentType === 'JSXClosingElement' ||
+            parentType === 'JSXMemberExpression') {
+            return;
+        }
+        // Non-reference positions: member property names and object keys.
+        if (parentType === 'MemberExpression' &&
+            parentNode.property === path.node &&
+            !parentNode.computed) {
+            return;
+        }
+        // Member-expression value references (`Icon.Text`, `Columns.Column` used
+        // as expressions): resolve the full chain; when the bestax target is the
+        // same dotted chain the runtime compound still exists — only flag (or
+        // rewrite, for flat single-name targets) when it differs.
+        if (parentType === 'MemberExpression' &&
+            parentNode.object === path.node &&
+            !parentNode.computed) {
+            const memberPath = [imported, nameOf(parentNode.property)];
+            const memberMapping = resolveMapping(memberPath);
+            const dotted = memberPath.join('.');
+            if (memberMapping &&
+                memberMapping.status !== 'todo' &&
+                memberMapping.target &&
+                !memberMapping.special) {
+                if (memberMapping.target === dotted) {
+                    // Same compound exists on the bestax component at runtime.
+                    const rootMapping = MAPPING[imported];
+                    if (rootMapping?.target) {
+                        const local = ctx.reserve(rootMapping.target);
+                        if (local !== name)
+                            path.node.name = local;
+                        ctx.dirty = true;
+                    }
+                    return;
+                }
+                if (!memberMapping.target.includes('.')) {
+                    // Flat target (Icon.Text → IconText): swap the member expression.
+                    const local = ctx.reserve(memberMapping.target);
+                    path.parent.replace(j.identifier(local));
+                    ctx.dirty = true;
+                    return;
+                }
+            }
+            addTodo(ctx, path.parent, 'value-reference', `\`${dotted}\` is referenced as a value; migrate this usage by hand`);
+            ctx.retained.add(imported);
+            return;
+        }
+        if ((parentType === 'ObjectProperty' || parentType === 'Property') &&
+            parentNode.key === path.node &&
+            !parentNode.shorthand) {
+            return;
+        }
+        const mapping = MAPPING[imported];
+        if (mapping &&
+            mapping.status !== 'todo' &&
+            mapping.target &&
+            !mapping.target.includes('.')) {
+            const local = ctx.reserve(mapping.target);
+            if (local !== name)
+                path.node.name = local;
+            ctx.dirty = true;
+        }
+        else {
+            ctx.retained.add(imported);
+            addTodo(ctx, path, 'value-reference', `\`${name}\` is referenced as a value; migrate this usage by hand`);
+        }
+    });
+    // ---- 3. Rewrite imports -----------------------------------------------
+    if (imports.size > 0) {
+        const retainedNames = [...ctx.retained].sort((a, b) => a.localeCompare(b));
+        const freshNames = [...ctx.needed.entries()]
+            .filter(([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;
+        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).
+        const bestaxLocals = new Set(ctx.needed.values());
+        for (const path of rbcImportPaths) {
+            const node = path.node;
+            const keepSpecifiers = (node.specifiers ?? []).filter((spec) => spec.type === 'ImportSpecifier' &&
+                ctx.retained.has(nameOf(spec.imported)) &&
+                !bestaxLocals.has(nameOf(spec.local)));
+            if (!inserted) {
+                if (existingBestax && bestaxImport) {
+                    existingBestax.node.specifiers = [
+                        ...(existingBestax.node.specifiers ?? []),
+                        ...bestaxImport.specifiers,
+                    ];
+                }
+                else if (bestaxImport) {
+                    path.insertBefore(bestaxImport);
+                }
+                inserted = true;
+            }
+            if (keepSpecifiers.length > 0) {
+                node.specifiers = keepSpecifiers;
+                node.comments = node.comments ?? [];
+                const text = ` TODO(bestax-migrate): ${retainedNames.join(', ')} ${retainedNames.length === 1 ? 'has' : 'have'} no bestax-bulma equivalent yet — migrate and remove this import`;
+                if (!node.comments.some((c) => c.value === text)) {
+                    node.comments.push(j.commentLine(text, true, false));
+                }
+            }
+            else {
+                path.prune();
+            }
+            ctx.dirty = true;
+        }
+    }
+    if (!ctx.dirty)
+        return undefined;
+    // 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.
+    return root.toSource({
+        quote: 'double',
+        useTabs: prefersTabs(fileInfo.source),
+    });
+}
+function prefersTabs(source) {
+    let tabs = 0;
+    let spaces = 0;
+    for (const line of source.split('\n')) {
+        if (line.startsWith('\t'))
+            tabs += 1;
+        else if (line.startsWith(' '))
+            spaces += 1;
+    }
+    return tabs > spaces;
+}

package/dist/sources/registry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The multi-source seam: every library bestax-migrate can migrate from
+ * registers here, and the CLI resolves its first argument against this map.
+ */
+import type { MigrationSource } from '../types.js';
+export declare const SOURCES: Record<string, MigrationSource>;
+export declare function getSource(name: string): MigrationSource | undefined;
+export declare function sourceNames(): string[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +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;AAGnD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAEnD,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

@@ -0,0 +1,14 @@
+/**
+ * The multi-source seam: every library bestax-migrate can migrate from
+ * registers here, and the CLI resolves its first argument against this map.
+ */
+import { reactBulmaComponents } from './react-bulma-components/index.js';
+export const SOURCES = {
+    [reactBulmaComponents.name]: reactBulmaComponents,
+};
+export function getSource(name) {
+    return SOURCES[name];
+}
+export function sourceNames() {
+    return Object.keys(SOURCES);
+}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared types for the bestax-migrate codemod platform.
+ *
+ * Each source library (e.g. react-bulma-components) contributes a declarative
+ * mapping table plus a jscodeshift transform that consumes it. Everything the
+ * transform cannot convert safely is annotated with a `TODO(bestax-migrate)`
+ * comment and collected into the run report.
+ */
+import type { API, FileInfo } from 'jscodeshift';
+/**
+ * How completely a source-library component converts to bestax-bulma.
+ *
+ * - `mapped`  — converts fully; no follow-up expected.
+ * - `partial` — converts, but some props or structures are left as TODOs.
+ * - `todo`    — no bestax equivalent; usage is annotated and left in place.
+ */
+export type MappingStatus = 'mapped' | 'partial' | 'todo';
+/** A declarative action to apply to a single JSX prop. */
+export interface PropAction {
+    /** Rename the attribute, keeping its value. */
+    rename?: string;
+    /** Remap literal string values (applied after `numberToString`). */
+    valueMap?: Record<string, string>;
+    /**
+     * Changes `valueMap` semantics: matched literal values become bare boolean
+     * prop(s) named by the mapped value (space-separated for several), and the
+     * original attribute is removed. Unmatched literal values are left as-is
+     * unless listed in `valueTodo`; non-literal values get a TODO.
+     */
+    valueToProp?: boolean;
+    /** Convert a numeric literal value to its string form ({4} → "4"). */
+    numberToString?: boolean;
+    /**
+     * Replace a boolean (valueless) attribute with `name="value"`, or with a
+     * bare boolean `name` when `value` is omitted.
+     */
+    booleanToProp?: {
+        name: string;
+        value?: string;
+    };
+    /** Remove the attribute entirely. */
+    drop?: boolean;
+    /** Leave the attribute as-is and attach a TODO with this hint. */
+    todo?: string;
+    /**
+     * TODO hints keyed by specific literal values; other values convert
+     * normally. Takes precedence over `valueMap` for the listed values.
+     */
+    valueTodo?: Record<string, string>;
+}
+/** Mapping for one source-library component (or compound sub-component). */
+export interface ComponentMapping {
+    status: MappingStatus;
+    /**
+     * Target bestax-bulma JSX name, dotted for compounds (`Card.FooterItem`).
+     * The first segment is the import added to `@allxsmith/bestax-bulma`.
+     * Omitted when `status` is `todo` or a `special` handler chooses the target.
+     */
+    target?: string;
+    /** Hint attached to the TODO comment when `status` is `todo`. */
+    todo?: string;
+    /** Key of a structural handler in the transform (align-based targets etc.). */
+    special?: string;
+    /** Per-prop actions, applied before the universal modifier-prop pass. */
+    props?: Record<string, PropAction>;
+    /** Compound sub-components keyed by their source-library name. */
+    subs?: Record<string, ComponentMapping>;
+}
+/** One annotation left in the code, mirrored into the run report. */
+export interface TodoEntry {
+    file: string;
+    line: number | null;
+    rule: string;
+    message: string;
+}
+/** Per-file outcome of a transform run. */
+export interface FileResult {
+    file: string;
+    changed: boolean;
+    todos: TodoEntry[];
+}
+/** Collects TODO entries for the file currently being transformed. */
+export interface TodoCollector {
+    add(entry: TodoEntry): void;
+}
+/**
+ * Which stylesheet target CSS/SCSS rewrites aim at:
+ * - `bestax` (default): the recommended `@allxsmith/bestax-bulma/bestax.css`
+ *   combined bundle (Bulma v1 + extras; bulma comes as a transitive dep).
+ * - `bulma`: plain `bulma/css/bulma.min.css` plus a separate extras import.
+ * - `keep`: leave existing bulma stylesheet imports untouched.
+ */
+export type CssMode = 'bestax' | 'bulma' | 'keep';
+/** Options threaded through to transforms by the CLI and the tests. */
+export interface TransformOptions {
+    collector?: TodoCollector;
+    cssMode?: CssMode;
+    [key: string]: unknown;
+}
+/** Options for the package.json dependency updater. */
+export interface DepsOptions {
+    cssMode?: CssMode;
+    /** True when migrated sources still reference `bulma/…` specifiers. */
+    bulmaReferenced?: boolean;
+}
+/** The standard jscodeshift transform contract. */
+export type Transform = (fileInfo: FileInfo, api: API, options: TransformOptions) => string | undefined;
+/** Text-level transform for stylesheet files (.scss/.sass). */
+export type StylesTransform = (filePath: string, source: string, collector: TodoCollector | undefined, options: TransformOptions) => string | null;
+/** package.json updater; returns the changed manifest or null. */
+export type DependenciesUpdate = (filePath: string, pkg: Record<string, unknown>, collector: TodoCollector | undefined, options: DepsOptions) => Record<string, unknown> | null;
+/** A migration source registered with the CLI. */
+export interface MigrationSource {
+    /** CLI name, e.g. `react-bulma-components`. */
+    name: string;
+    /** Human-readable label for the report header. */
+    label: string;
+    transform: Transform;
+    transformStyles?: StylesTransform;
+    updateDependencies?: DependenciesUpdate;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the bestax-migrate codemod platform.
+ *
+ * Each source library (e.g. react-bulma-components) contributes a declarative
+ * mapping table plus a jscodeshift transform that consumes it. Everything the
+ * transform cannot convert safely is annotated with a `TODO(bestax-migrate)`
+ * comment and collected into the run report.
+ */
+export {};