bestax-migrate 2.1.6 → 2.2.0

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

@@ -13,9 +13,10 @@
  * 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 { MAPPING, UNIVERSAL_PROPS, resolveMapping } from './mapping.js';
+import { addTodo, attributesOf, jsxNameParts, renameElement, } from '../_shared/jsx-utils.js';
+import { applyPropAction, applyUniversalProps } from '../_shared/props.js';
+import { collectBoundNames, 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 */
@@ -57,7 +58,12 @@ export default function transform(fileInfo, api, options = {}) {
     /** local identifier → canonical RBC path (from destructuring). */
     const aliases = new Map();
     const rbcImportPaths = [];
-    const nameOf = (node) => typeof node === 'string' ? node : String(node?.name ?? '');
+    /**
+     * Whether a namespace binding (`import * as RBC`) is still referenced after
+     * the JSX pass — either by a retained component (`<RBC.Tile>`) or as a bare
+     * value. Pruning the import under one leaves `RBC is not defined`.
+     */
+    let namespaceStillReferenced = false;
     root.find(j.ImportDeclaration).forEach(path => {
         const source = String(path.node.source.value);
         if (source === RBC) {
@@ -141,24 +147,115 @@ export default function transform(fileInfo, api, options = {}) {
     if (imports.size === 0 && !ctx.dirty) {
         return undefined;
     }
+    // The scope each binding was collected in, so a reference can be checked
+    // against the binding it actually resolves to rather than matched by name.
+    const programScope = root.find(j.Program).paths()[0]?.scope;
+    // Aliases are keyed by the AST node that owns the declaring scope, not by
+    // bare name. Two functions can each destructure `Header` from a different
+    // component; a name-keyed map let the second overwrite the first, and both
+    // declarations were then pruned while both `<Header…>` references were left
+    // resolving to nothing.
+    //
+    // Resolution walks the reference's ANCESTORS rather than consulting
+    // `scope.lookup`, because by the time references are rewritten the alias
+    // pass has already pruned the declaration -- so the binding is gone from
+    // the scope table, and `path.scope` objects are not identity-stable across
+    // traversals either.
+    const aliasesByOwner = new Map();
+    const ownersFor = (name) => {
+        const owners = [];
+        for (const [owner, perScope] of aliasesByOwner) {
+            if (perScope.has(name))
+                owners.push(owner);
+        }
+        return owners;
+    };
+    const aliasAt = (name, at) => {
+        const owners = ownersFor(name);
+        if (owners.length === 0)
+            return undefined;
+        // Without a reference location there is nothing to walk, so the only
+        // owner is the best answer available. WITH one, always walk: an unrelated
+        // `Header` parameter in another function must not resolve to the alias
+        // merely because the alias is the only one by that name. A single-owner
+        // shortcut here rewrote such a parameter to `{ Header: Card.Header }`,
+        // which is not even valid syntax.
+        if (at === undefined) {
+            return owners.length === 1
+                ? aliasesByOwner.get(owners[0]).get(name)
+                : undefined;
+        }
+        let cursor = at;
+        while (cursor) {
+            if (cursor.node !== undefined) {
+                const hit = aliasesByOwner.get(cursor.node)?.get(name);
+                if (hit) {
+                    // The walk finds the nearest OWNER, but a binding can intervene
+                    // between the reference and that owner: `function F(Header)` under
+                    // a module-level `const { Header } = Card` shadows the alias, and
+                    // resolving through it rewrote the parameter itself to
+                    // `F(Card.Header)`. If the scope table still binds the name
+                    // somewhere other than the owner, that nearer binding wins. (After
+                    // the alias declaration is pruned the lookup returns nothing for
+                    // the alias itself, which is the case this must keep allowing.)
+                    const declaring = at.scope?.lookup(name)?.path?.node;
+                    if (declaring !== undefined &&
+                        declaring !== null &&
+                        declaring !== cursor.node) {
+                        return undefined;
+                    }
+                    return hit;
+                }
+            }
+            cursor = cursor.parent;
+        }
+        return undefined;
+    };
+    const anyAlias = (name) => ownersFor(name).length > 0;
     // ---- 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('.');
+        const baseAlias = aliasAt(base, path);
+        const imported = imports.get(base) ?? baseAlias?.join('.');
         if (!imported || imported === '*')
             return;
+        if (!imports.has(base) && !baseAlias)
+            return;
         const basePath = imports.has(base)
             ? [imports.get(base)]
-            : aliases.get(base);
+            : baseAlias;
         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]);
+                const owner = path.scope
+                    ?.path?.node;
+                let perScope = aliasesByOwner.get(owner);
+                if (!perScope) {
+                    perScope = new Map();
+                    aliasesByOwner.set(owner, perScope);
+                }
+                const target = [...basePath, prop.key.name];
+                perScope.set(prop.value.name, target);
+                aliases.set(prop.value.name, target);
+                // Pruning the declaration is only safe if every use of the alias will
+                // actually be rewritten. For a name the table cannot map, the JSX is
+                // left as written -- so dropping `const { Header } = Panel` left
+                // `<Header/>` referencing nothing at all.
+                // A `special` handler rewrites the element without naming a plain
+                // target (`Form.Label` becomes a bare <label>), so it counts as
+                // resolved just as a target does. Requiring `target` alone kept every
+                // declaration that mentioned one.
+                const targetMapping = resolveMapping(target);
+                if (!targetMapping ||
+                    targetMapping.status === 'todo' ||
+                    !(targetMapping.target || targetMapping.special)) {
+                    allResolved = false;
+                }
             }
             else {
                 allResolved = false;
@@ -180,13 +277,18 @@ export default function transform(fileInfo, api, options = {}) {
         }
     });
     /** Resolve a JSX name into a canonical RBC component path, or null. */
-    function resolveJsxPath(name) {
+    function resolveJsxPath(name, at) {
         const parts = jsxNameParts(name);
         if (!parts)
             return null;
         const [head, ...rest] = parts;
-        if (aliases.has(head))
-            return [...aliases.get(head), ...rest];
+        const alias = aliasAt(head, at);
+        if (alias)
+            return [...alias, ...rest];
+        // An alias exists under this name but not for THIS reference's binding,
+        // so the reference is not ours to rewrite.
+        if (anyAlias(head) && !imports.has(head))
+            return null;
         const imported = imports.get(head);
         if (imported === undefined)
             return null;
@@ -199,78 +301,92 @@ export default function transform(fileInfo, api, options = {}) {
     // 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;
+    const bound = collectBoundNames(j, root, RBC);
+    // Seed the reserved set with the locals of RBC imports that CANNOT be
+    // migrated, so a bestax import never claims one of them. Without this, an
+    // unmappable component aliased to a name bestax also wants
+    // (`import { Element as Button }`) had its retained specifier dropped on
+    // the collision, and its `<Button>` JSX then silently resolved to the
+    // bestax Button — one component quietly becoming another.
+    for (const [local, imported] of imports) {
+        if (imported === '*')
+            continue;
+        const entry = MAPPING[imported];
+        // Unmappable roots, plus ANY aliased import. A root can be retained by an
+        // unknown or `todo` child even when the root itself maps (`Icon` is
+        // `partial`, but `<Icon.Unknown>` retains it), and when the local name
+        // differs from the imported one that retained binding can collide with a
+        // bestax local for a completely different component. An unaliased import
+        // is safe: its name already means the same component on both sides.
+        if (!entry || entry.status === 'todo' || local !== imported) {
+            bound.add(local);
         }
-    };
-    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);
+    }
+    // A root that DOES map can still be retained by a child the table cannot
+    // (`Icon` is `partial`, but `<Icon.Unknown>` keeps the source import alive).
+    // The status check above misses that case whenever the local name equals the
+    // imported one, so the bestax import took the plain local, the retained
+    // specifier was dropped on the collision, and `<Icon.Unknown>` silently
+    // resolved to the bestax component instead.
+    //
+    // Scanned rather than reserved wholesale: adding every partial root to
+    // `bound` would alias them in every file that uses one, whether or not
+    // anything is actually retained.
+    root.find(j.JSXElement).forEach(path => {
+        const head = jsxNameParts(path.node.openingElement.name)?.[0];
+        if (!head || !imports.has(head))
+            return;
+        const parts = resolveJsxPath(path.node.openingElement.name, path);
+        const mapping = parts ? resolveMapping(parts) : undefined;
+        if (!mapping || mapping.status === 'todo')
+            bound.add(head);
     });
-    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));
+    // The same root can be retained by a VALUE chain -- `const X = Icon.Unknown`
+    // -- which only the value-reference pass discovers, after `reserve` has
+    // already handed the plain local to bestax. Scan those chains here too.
+    root.find(j.Identifier).forEach(path => {
+        if (path.node.type !== 'Identifier')
+            return;
+        const head = path.node.name;
+        const imported = imports.get(head);
+        if (imported === undefined || imported === '*')
+            return;
+        const parent = path.parent?.node;
+        if (parent?.type !== 'MemberExpression' ||
+            parent.object !== path.node ||
+            parent.computed) {
+            return;
         }
-    });
-    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;
+        const chain = [imported];
+        let outer = path.parent;
+        while (outer?.node?.type === 'MemberExpression' &&
+            !outer.node.computed &&
+            outer.node.property?.type === 'Identifier') {
+            chain.push(nameOf(outer.node.property));
+            const next = outer.parent;
+            if (next?.node?.type === 'MemberExpression' &&
+                next.node.object === outer.node) {
+                outer = next;
+            }
+            else {
+                break;
             }
         }
-        ctx.needed.set(importedName, local);
-        return local;
-    };
+        const mapping = resolveMapping(chain);
+        if (!mapping || mapping.status === 'todo')
+            bound.add(head);
+    });
+    ctx.reserve = makeReserve(ctx, bound);
     // 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()[0];
+        .paths()
+        .find(path => (path.node.specifiers ?? []).every((spec) => spec.type === 'ImportSpecifier'));
     const preExistingImports = new Set();
     if (existingBestax) {
         for (const spec of existingBestax.node.specifiers ?? []) {
@@ -283,9 +399,17 @@ export default function transform(fileInfo, api, options = {}) {
     // ---- 2. Transform JSX elements ----------------------------------------
     root.find(j.JSXElement).forEach(path => {
         const element = path.node;
-        const rbcPath = resolveJsxPath(element.openingElement.name);
+        const rbcPath = resolveJsxPath(element.openingElement.name, path);
         if (!rbcPath)
             return;
+        // Resolve by BINDING, not by name. `function F({ Card })` shadows the
+        // import with the caller's object, and rewriting its JSX to bestax's
+        // `Card.FooterItem` changed which component rendered.
+        const jsxHead = jsxNameParts(element.openingElement.name)?.[0];
+        if (jsxHead &&
+            !resolvesToBinding(path, jsxHead, anyAlias(jsxHead) ? undefined : programScope)) {
+            return;
+        }
         const mapping = resolveMapping(rbcPath);
         const dotted = rbcPath.join('.');
         if (!mapping) {
@@ -340,21 +464,40 @@ export default function transform(fileInfo, api, options = {}) {
                 applyPropAction(ctx, path, element, attr, action);
             }
         }
-        applyUniversalProps(ctx, path, element, handled);
+        applyUniversalProps(ctx, path, element, handled, UNIVERSAL_PROPS);
     });
     // ---- 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.
+    // A shorthand property's key and value are distinct nodes, so the walker
+    // reaches the property twice. The first visit rewrites it and detaches the
+    // original; the second then matched neither key nor value and fell through
+    // to the generic "referenced as a value" branch, emitting a spurious TODO
+    // and marking the root retained when it was not.
+    const handledValueRefs = new WeakSet();
     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;
+        if (handledValueRefs.has(path.node))
+            return;
         const name = path.node.name;
-        const imported = imports.get(name);
-        if (imported === undefined || imported === '*')
+        // A name bound by `const { Field } = Form` lives in `aliases`, not
+        // `imports`, and the destructuring pass has already deleted the
+        // declaration that bound it. Skipping those left `Field.Label` in the
+        // output with its `Form` import pruned: a reference to nothing.
+        const aliasPath = aliasAt(name, path);
+        const imported = aliasPath ? aliasPath[0] : imports.get(name);
+        if (imported === undefined)
             return;
+        // Resolve by BINDING, not by name: a local that shadows the import is a
+        // different object, and rewriting it repoints the code at bestax's
+        // component.
+        if (!resolvesToBinding(path, name, aliasPath ? undefined : programScope)) {
+            return;
+        }
         const parentNode = path.parent?.node;
         const parentType = parentNode?.type;
         if (parentType === 'ImportSpecifier' ||
@@ -365,6 +508,20 @@ export default function transform(fileInfo, api, options = {}) {
             parentType === 'JSXMemberExpression') {
             return;
         }
+        // A namespace binding in a real value position. `RBC.Box` is still a
+        // mappable component reference, so fall through to the member-expression
+        // branch below with an empty prefix (the namespace itself is not part of
+        // the RBC path). Anything else — a bare `RBC` — just pins the import.
+        // Treating every namespace member as opaque left `const C = RBC.Box`
+        // referencing an import that dependency migration then removed.
+        const isNamespace = imported === '*';
+        if (isNamespace &&
+            !(parentType === 'MemberExpression' &&
+                parentNode.object === path.node &&
+                !parentNode.computed)) {
+            namespaceStillReferenced = true;
+            return;
+        }
         // Non-reference positions: member property names and object keys.
         if (parentType === 'MemberExpression' &&
             parentNode.property === path.node &&
@@ -378,7 +535,25 @@ export default function transform(fileInfo, api, options = {}) {
         if (parentType === 'MemberExpression' &&
             parentNode.object === path.node &&
             !parentNode.computed) {
-            const memberPath = [imported, nameOf(parentNode.property)];
+            // Walk the full chain: `Card.Footer.Item` is one path, not
+            // `Card.Footer` with a stray `.Item`. Resolving only the first level
+            // left the tail pointing at a compound bestax does not have
+            // (bestax exposes `Card.FooterItem`).
+            const memberPath = isNamespace ? [] : [...(aliasPath ?? [imported])];
+            let outer = path.parent;
+            while (outer?.node?.type === 'MemberExpression' &&
+                !outer.node.computed &&
+                outer.node.property?.type === 'Identifier') {
+                memberPath.push(nameOf(outer.node.property));
+                const next = outer.parent;
+                if (next?.node?.type === 'MemberExpression' &&
+                    next.node.object === outer.node) {
+                    outer = next;
+                }
+                else {
+                    break;
+                }
+            }
             const memberMapping = resolveMapping(memberPath);
             const dotted = memberPath.join('.');
             if (memberMapping &&
@@ -386,7 +561,36 @@ export default function transform(fileInfo, api, options = {}) {
                 memberMapping.target &&
                 !memberMapping.special) {
                 if (memberMapping.target === dotted) {
+                    if (isNamespace) {
+                        // `RBC.Card.Header` → `Card.Header`: the namespace prefix has to
+                        // go, so rebuild the chain from the target rather than renaming
+                        // the namespace identifier in place (there is no MAPPING['*']
+                        // root to rename it to).
+                        const [root, ...rest] = memberMapping.target.split('.');
+                        let rebuilt = j.identifier(ctx.reserve(root));
+                        for (const part of rest) {
+                            rebuilt = j.memberExpression(rebuilt, j.identifier(part));
+                        }
+                        outer.replace(rebuilt);
+                        ctx.dirty = true;
+                        return;
+                    }
                     // Same compound exists on the bestax component at runtime.
+                    if (aliasPath) {
+                        // A destructured alias stands for MORE than one segment of the
+                        // chain (`const { Header } = Card` makes `Header` mean
+                        // `Card.Header`), so renaming the identifier drops every segment
+                        // but the last: `Header.Title` became `Card.Title`. Rebuild the
+                        // whole chain from the target instead.
+                        const [aliasRoot, ...aliasRest] = memberMapping.target.split('.');
+                        let rebuilt = j.identifier(ctx.reserve(aliasRoot));
+                        for (const part of aliasRest) {
+                            rebuilt = j.memberExpression(rebuilt, j.identifier(part));
+                        }
+                        outer.replace(rebuilt);
+                        ctx.dirty = true;
+                        return;
+                    }
                     const rootMapping = MAPPING[imported];
                     if (rootMapping?.target) {
                         const local = ctx.reserve(rootMapping.target);
@@ -397,15 +601,30 @@ export default function transform(fileInfo, api, options = {}) {
                     return;
                 }
                 if (!memberMapping.target.includes('.')) {
-                    // Flat target (Icon.Text → IconText): swap the member expression.
+                    // Flat target (Icon.Text → IconText): swap the whole chain.
                     const local = ctx.reserve(memberMapping.target);
-                    path.parent.replace(j.identifier(local));
+                    outer.replace(j.identifier(local));
                     ctx.dirty = true;
                     return;
                 }
+                // Dotted target that differs from the source chain
+                // (Card.Footer.Item → Card.FooterItem): rebuild the chain against the
+                // bestax path rather than flagging something the table can answer.
+                const [targetRoot, ...targetRest] = memberMapping.target.split('.');
+                const rootLocal = ctx.reserve(targetRoot);
+                let rebuilt = j.identifier(rootLocal);
+                for (const part of targetRest) {
+                    rebuilt = j.memberExpression(rebuilt, j.identifier(part));
+                }
+                outer.replace(rebuilt);
+                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);
+            addTodo(ctx, outer, 'value-reference', `\`${isNamespace ? `${name}.` : ''}${dotted}\` is referenced as a value; migrate this usage by hand`);
+            if (isNamespace)
+                namespaceStillReferenced = true;
+            else
+                ctx.retained.add(imported);
             return;
         }
         if ((parentType === 'ObjectProperty' || parentType === 'Property') &&
@@ -413,14 +632,75 @@ export default function transform(fileInfo, api, options = {}) {
             !parentNode.shorthand) {
             return;
         }
-        const mapping = MAPPING[imported];
+        // A shorthand property is both the key and the reference. Renaming the
+        // node in place rewrote the object's PUBLIC key
+        // (`{ Textarea }` → `{ TextArea }`), so expand it instead: the key keeps
+        // the name callers use, the value points at the migrated binding.
+        if ((parentType === 'ObjectProperty' || parentType === 'Property') &&
+            parentNode.shorthand) {
+            // Resolve through the alias path when there is one: `const { Footer } =
+            // Card` makes `{ Footer }` mean `Card.Footer`, not `Card`. Reading the
+            // root's mapping here emitted `{ Footer: Card }` — the wrong component
+            // under the right key.
+            const shorthandMapping = aliasPath
+                ? resolveMapping(aliasPath)
+                : MAPPING[imported];
+            if (shorthandMapping &&
+                shorthandMapping.status !== 'todo' &&
+                shorthandMapping.target &&
+                !shorthandMapping.special) {
+                const [root, ...rest] = shorthandMapping.target.split('.');
+                const local = ctx.reserve(root);
+                let value = j.identifier(local);
+                for (const part of rest) {
+                    value = j.memberExpression(value, j.identifier(part));
+                }
+                if (rest.length > 0 || local !== name) {
+                    // ast-types keeps DISTINCT key and value nodes even when
+                    // `shorthand` is true, so both positions are visited. Mark both, or
+                    // the second visit sees a node that matches neither the (new) key
+                    // nor the (new) value and falls through to the generic branch.
+                    handledValueRefs.add(parentNode.key);
+                    handledValueRefs.add(parentNode.value);
+                    parentNode.shorthand = false;
+                    parentNode.key = j.identifier(name);
+                    parentNode.value = value;
+                    ctx.dirty = true;
+                }
+            }
+            else {
+                // Mark both positions before reporting: the key and the value are
+                // distinct nodes, so an unmarked branch reports the same property
+                // twice. The AST comment dedupes, which hid this in the output while
+                // the report still double-counted it.
+                handledValueRefs.add(parentNode.key);
+                handledValueRefs.add(parentNode.value);
+                ctx.retained.add(imported);
+                addTodo(ctx, path, 'value-reference', `\`${name}\` is referenced as a value; migrate this usage by hand`);
+            }
+            return;
+        }
+        const mapping = aliasPath ? resolveMapping(aliasPath) : MAPPING[imported];
         if (mapping &&
             mapping.status !== 'todo' &&
             mapping.target &&
-            !mapping.target.includes('.')) {
-            const local = ctx.reserve(mapping.target);
-            if (local !== name)
+            !mapping.special) {
+            const [root, ...rest] = mapping.target.split('.');
+            const local = ctx.reserve(root);
+            if (rest.length > 0) {
+                // A dotted target needs a member expression, not a rename — otherwise
+                // a destructured alias used as a bare value (`const { Header } = Card;
+                // const V = Header`) fell through to the TODO branch, left referencing
+                // a binding the destructuring pass had already deleted.
+                let value = j.identifier(local);
+                for (const part of rest) {
+                    value = j.memberExpression(value, j.identifier(part));
+                }
+                path.replace(value);
+            }
+            else if (local !== name) {
                 path.node.name = local;
+            }
             ctx.dirty = true;
         }
         else {
@@ -443,9 +723,17 @@ export default function transform(fileInfo, api, options = {}) {
         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)));
+            const keepSpecifiers = (node.specifiers ?? []).filter((spec) => {
+                // `import * as RBC` reaches every export at once, so it must survive
+                // whenever a component is retained (`<RBC.Tile>` stays in the JSX) or
+                // the namespace is referenced as a value.
+                if (spec.type === 'ImportNamespaceSpecifier') {
+                    return ctx.retained.size > 0 || namespaceStillReferenced;
+                }
+                return (spec.type === 'ImportSpecifier' &&
+                    ctx.retained.has(nameOf(spec.imported)) &&
+                    !bestaxLocals.has(nameOf(spec.local)));
+            });
             if (!inserted) {
                 if (existingBestax && bestaxImport) {
                     existingBestax.node.specifiers = [
@@ -482,14 +770,3 @@ export default function transform(fileInfo, api, options = {}) {
         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.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;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"}
+{"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;AAInD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAGnD,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

@@ -3,8 +3,10 @@
  * registers here, and the CLI resolves its first argument against this map.
  */
 import { reactBulmaComponents } from './react-bulma-components/index.js';
+import { rbx } from './rbx/index.js';
 export const SOURCES = {
     [reactBulmaComponents.name]: reactBulmaComponents,
+    [rbx.name]: rbx,
 };
 export function getSource(name) {
     return SOURCES[name];

package/dist/types.d.ts

@@ -109,6 +109,14 @@ export interface DepsOptions {
     cssMode?: CssMode;
     /** True when migrated sources still reference `bulma/…` specifiers. */
     bulmaReferenced?: boolean;
+    /**
+     * True when at least one migrated file still imports the SOURCE library —
+     * the trimmed, TODO-annotated import the transform deliberately keeps for
+     * components with no bestax equivalent. Removing the package from the
+     * manifest while those remain leaves them unresolvable after the install
+     * step the report tells the user to run.
+     */
+    sourceStillImported?: boolean;
 }
 /** The standard jscodeshift transform contract. */
 export type Transform = (fileInfo: FileInfo, api: API, options: TransformOptions) => string | undefined;