bestax-migrate 2.3.1 → 2.3.3

package/dist/sources/_shared/polymorphic.js

@@ -0,0 +1,703 @@
+/**
+ * bestax's DOM props follow `as`: an element's attributes are the attributes
+ * of whatever `as` renders, and a few components narrow `as` to a literal
+ * union of the elements Bulma's markup allows there. Every source library
+ * this package migrates from is looser — rbx and react-bulma-components take
+ * any tag, bloomer took any `tag` — so a faithful prop-for-prop rename emits
+ * shapes that do not compile against the library:
+ *
+ * - an `as` naming an element the bestax component does not offer;
+ * - an `href` beside an `as` that is not an `<a>`;
+ * - an `href` on a component that declares none at any `as`;
+ * - `target` and its siblings on an element, or a component, without them.
+ *
+ * All are dropped with a TODO rather than carried, because carrying them
+ * hands the user a project that does not typecheck, which is the one thing a
+ * codemod must not do.
+ *
+ * What that costs differs by case, and each TODO says so. Dropping an `href`
+ * or a `target` costs nothing the source had: they sat on a `<span>` or a
+ * `<div>`, where no browser acts on them. Dropping an `as` does change the
+ * element — every source here rendered the tag it was given, and bestax
+ * renders its own instead — so that TODO names the tag to restore rather than
+ * claiming nothing moved.
+ *
+ * Source-agnostic: what it knows is bestax's side of the rename, so all three
+ * sources run it over every element after their prop passes.
+ */
+import { addTodo, attrSource, findAttr, literalValueOf, removeAttr, } from './jsx-utils.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * The bestax components whose `as` is a closed literal union, by the name the
+ * mappings use as their `target`. Every other component either takes no `as`
+ * (`restrictAsToTargets` handles those) or is generic over `React.ElementType`
+ * and accepts any tag.
+ *
+ * `as-unions.test.ts` holds each row to the library's own type, so a union
+ * that widens or narrows in bulma-ui fails here rather than drifting into
+ * output that does not compile.
+ */
+const AS_UNION_TABLE = {
+    Control: ['div', 'p'],
+    'Dropdown.Item': ['a', 'div', 'button'],
+    Footer: ['footer', 'div'],
+    Image: ['figure', 'div', 'p'],
+    'Level.Item': ['div', 'p', 'a'],
+    Media: ['article', 'div'],
+    'Media.Left': ['figure', 'div'],
+    SubTitle: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p'],
+    Title: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p'],
+};
+export const AS_UNIONS = AS_UNION_TABLE;
+/**
+ * The targets that accept an `as` beyond a narrowed union -- generic over
+ * `React.ElementType`, so any tag is valid. Every other target either narrows
+ * `as` (the table above) or declares none at all.
+ *
+ * That last group is why this set has to exist. An earlier pass flags an `as`
+ * a component cannot take and leaves the attribute in place as the marker for
+ * its TODO, so reading the element off whatever `as` is present would believe
+ * a prop the component never had -- and `<Panel.Block as="span" href="/x">`
+ * would lose the `href` that compiles and keep the `as` that does not.
+ */
+const AS_ANY = new Set(['Button', 'Menu.Item', 'Navbar.Item', 'Navbar.Link']);
+/**
+ * Where an `href` can live, by bestax target -- the value is the element the
+ * component renders when no `as` is given. An `href` survives only where that
+ * element is the anchor, or where `as="a"` names one; a target absent from
+ * this table takes no `href` at any `as`, which is most of them.
+ *
+ * Stated this way round on purpose. The source libraries put an `href` on
+ * anything, and a table of what cannot take one is a list nobody can keep
+ * complete -- the first version of this rule named four targets and missed
+ * `Tabs.Item`, `Media.Left`, `Card.Image` and ninety more. Note the two
+ * `Pagination` controls: a source reaches them through a `special`, not a
+ * `target:` line, so a table built by reading the mappings alone misses them.
+ *
+ * The default element is here rather than a bare "takes an href" flag because
+ * typechecking cannot answer the question on its own. `Level.Item` declares
+ * `href` on its props at every `as`, so `<Level.Item href="/x">` compiles --
+ * but it renders a <div> and forwards `href` only when the tag is an `<a>`
+ * (`bulma-ui/src/layout/Level.tsx:227`), so the attribute is dropped at
+ * runtime. A table built from the types alone calls that supported; it is the
+ * same dead attribute this pass exists to remove.
+ */
+const HREF_OK = {
+    Button: 'button',
+    'Dropdown.Item': 'a',
+    'Level.Item': 'div',
+    'Menu.Item': 'a',
+    'Navbar.Item': 'a',
+    'Navbar.Link': 'a',
+    'Pagination.Link': 'a',
+    'Pagination.Next': 'a',
+    'Pagination.Previous': 'a',
+    'Panel.Block': 'a',
+};
+/**
+ * Where "put an <a> inside" is not the useful advice. bloomer's navbar handler
+ * already said this for its own source; the other two reached the same target
+ * and got the generic line, which is the sibling drift `bestax-migrate`'s
+ * CLAUDE.md warns about. Keyed by target, all three get it.
+ */
+const NO_HREF_HINT = {
+    'Navbar.Dropdown': 'bestax `Navbar.Dropdown` is the container and takes no `href`; put it on the `<Navbar.Link>` inside',
+    // `Delete` renders a self-closing <button/> with no `{children}` at all, so
+    // the generic "put an <a> inside it" is advice nobody can follow. bloomer's
+    // mapping said the right thing here before the entry moved into this table.
+    Delete: 'bestax `Delete` renders a <button> with no children and has no anchor form; wrap it in an <a>, or navigate in `onClick`',
+    'Card.Header.Icon': 'bestax `Card.Header.Icon` renders a <button>, so an <a> inside it would nest interactive elements; navigate in `onClick`, or wrap the whole icon in an <a>',
+};
+/**
+ * Where to put a link on a target, for the attributes beside `href`. The same
+ * fact as `NO_HREF_HINT` in its short form -- fixing the `Delete` advice in
+ * one branch and leaving the sibling saying "put it on an <a> inside" to a
+ * component with no children is how these two drifted apart the first time.
+ */
+const LINK_REMEDY = {
+    Delete: 'wrap it in an <a>, or navigate in `onClick`',
+    'Navbar.Dropdown': 'put it on the `<Navbar.Link>` inside',
+    // Already renders an interactive element, so "put an <a> inside" would nest
+    // one inside the other, which is invalid.
+    'Card.Header.Icon': 'navigate in `onClick`, or wrap the whole icon in an <a>',
+};
+/**
+ * Elements that may not CONTAIN an `<a>`, so "put an <a> inside" names markup
+ * the author cannot write.
+ *
+ * This is not the same question as "may an `<a>` contain it". Interactive
+ * content -- `button`, `input`, `details`, `iframe`, … -- may not be an `<a>`
+ * DESCENDANT, which rules out wrapping; only a subset also refuses an `<a>`
+ * child, which is what rules out nesting. `<details>` is the case that shows
+ * they differ: an `<a>` may not wrap one, and
+ * `<details><summary>…</summary><a href>…</a></details>` is ordinary valid
+ * markup. Conflating the two directions suppressed advice that was correct.
+ *
+ * So this set is only the second direction, read off each element's content
+ * model: `a` (transparent, but no `a` descendant), `button` (no interactive
+ * descendant), `select`/`textarea` (options and text only), `embed`/`input`
+ * (void), `iframe` (content model "nothing" — markup between the tags is not a
+ * usable child).
+ *
+ * `label` is deliberately NOT here, though it is interactive: its content model
+ * is phrasing content excluding labelable controls and nested labels, and an
+ * `<a>` is neither. It refuses to be WRAPPED, not to hold a link.
+ *
+ * `LINK_REMEDY` states the same thing per TARGET, for components that render
+ * such an element whatever `as` says; this states it per RENDERED ELEMENT, for
+ * the ones where the author's `as` chose it. `Dropdown.Item` needs both
+ * readings: it is a link by default and a `<button>` on request.
+ */
+const NO_ANCHOR_CHILD = new Set([
+    'a',
+    'button',
+    'embed',
+    'iframe',
+    'input',
+    'select',
+    'textarea',
+]);
+/**
+ * Elements an `<a>` may not WRAP, because they are interactive content and an
+ * `<a>` may have no interactive descendant. The complement of the set above
+ * rather than the same list: `details` and `label` refuse to be wrapped and
+ * accept an `<a>` child perfectly well, which is the whole reason the two
+ * questions need two sets.
+ *
+ * `audio` and `video` are deliberately absent -- interactive only with
+ * `controls`, which the tag alone does not say, so wrapping one is valid as far
+ * as this can tell.
+ */
+const NO_ANCHOR_WRAPPER = new Set([...NO_ANCHOR_CHILD, 'details', 'label']);
+/**
+ * Void elements an `<a>` may actually WRAP. `<a><img></a>` is the canonical
+ * form, and it is the advice `Delete` already gives through `LINK_REMEDY` for
+ * the same reason. The plain-markup path reaches these: bloomer's `tag` is
+ * whatever literal the source wrote, so `<Help tag="img">` is one rewrite away.
+ *
+ * Deliberately short. Void-ness is necessary and not sufficient, and the two
+ * ways of getting that wrong are both invalid trees: `input` and `embed` are
+ * interactive (above), and the set below belongs somewhere an `<a>` cannot be.
+ */
+const WRAPPABLE_VOID = new Set(['br', 'hr', 'img', 'wbr']);
+/**
+ * Void elements whose parent is fixed by the spec, so no `<a>` can sit between
+ * them and it: `base`, `link` and `meta` belong to `<head>`, `col` to
+ * `<colgroup>`, `source` and `track` to a media element, `param` to `<object>`,
+ * `area` to `<map>`.
+ *
+ * Nothing can be nested in them and nothing can wrap them, so the only honest
+ * remedy is to stop using the element for this.
+ */
+const CONTEXT_BOUND = new Set([
+    'area',
+    'base',
+    'col',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+]);
+/**
+ * What to do with a link the element refuses. `carry` is true for an attribute
+ * that has to land ON the anchor to do anything (`target`, `download`, …) and
+ * false where the anchor itself IS the remedy (a bare `href`).
+ *
+ * Four answers, because "put an <a> inside" is wrong in three different ways:
+ * an anchor inside interactive content is invalid, an anchor inside a void
+ * element is impossible, and an anchor around a context-bound element puts it
+ * somewhere its parent may not be.
+ *
+ * Exported because `specials-utils.ts` reaches the same question from the plain
+ * markup side, and `bestax-migrate/CLAUDE.md` puts a rule two transforms need in
+ * `_shared/` rather than in one of them.
+ */
+export const nestOrClick = (rendered, carry = false) => {
+    if (rendered !== undefined && NO_ANCHOR_CHILD.has(rendered)) {
+        return 'navigate in `onClick`';
+    }
+    if (rendered !== undefined && CONTEXT_BOUND.has(rendered)) {
+        return carry
+            ? 'move it to an element that can take it'
+            : 'use an element that can be a link';
+    }
+    if (rendered !== undefined &&
+        WRAPPABLE_VOID.has(rendered) &&
+        !NO_ANCHOR_WRAPPER.has(rendered)) {
+        return carry
+            ? 'put it on an <a> wrapping this element'
+            : 'wrap it in an <a>';
+    }
+    return carry ? 'put it on an <a> inside' : 'put an <a> inside';
+};
+const remedyFor = (target, rendered) => LINK_REMEDY[target] ??
+    `${nestOrClick(rendered, true)}, or change the element`;
+/** The targets whose `as` this pass may believe. */
+export function declaresAs(target) {
+    return target in AS_UNIONS || AS_ANY.has(target);
+}
+/** Whether `target` renders `value` when told `as={value}`. */
+function acceptsAs(target, value) {
+    const union = AS_UNIONS[target];
+    return union ? union.includes(value) : AS_ANY.has(target);
+}
+/** The rows the type test holds to the library. */
+export const HREF_TABLE = HREF_OK;
+export const AS_ANY_TARGETS = [...AS_ANY].sort();
+/**
+ * The `as` value that keeps an `href`. Only the anchor, and not because it is
+ * the only intrinsic React types an `href` onto -- `area`, `link` and `base`
+ * carry one too, and a target generic over `as` accepts them.
+ *
+ * They are excluded because the components disagree about what they forward,
+ * so no shared set is right. `Menu.Item` strips `href` unless the tag is an
+ * `<a>` or a custom component (`bulma-ui/src/components/Menu.tsx:212-222`),
+ * while `Button` routes everything but `'button'` through its anchor path and
+ * would forward it. Keeping `href` beside `as="area"` therefore typechecks on
+ * both and does nothing on one of them, which is the silently-dead attribute
+ * this pass exists to remove. Dropping it is announced and the TODO quotes
+ * the value; keeping it is not. No source here emits `as="area"` anyway, and
+ * an `<area href>` outside a `<map>` navigates nowhere regardless.
+ */
+const ANCHOR = 'a';
+/**
+ * The elements each link attribute is valid on. Not a blanket "anchor-only"
+ * list, because they are not: `referrerPolicy` is real on `<img>` and
+ * `<script>`, `target` on `<form>`, `rel` on `<link>`. Treating them as one
+ * set deleted working attributes from those elements.
+ *
+ * They still have to be checked. Dropping the `href` alone left
+ * `<Navbar.Link as="span" target="_blank">`, which does not compile either --
+ * and the check has to run whether or not an `href` was there to start with,
+ * since that shape is just as invalid without one.
+ */
+const LINK_ATTR_ELEMENTS = {
+    target: ['a', 'area', 'base', 'form'],
+    download: ['a', 'area'],
+    hrefLang: ['a', 'area', 'link'],
+    ping: ['a'],
+    referrerPolicy: ['a', 'area', 'iframe', 'img', 'link', 'script'],
+    media: ['a', 'area', 'link', 'meta', 'source', 'style'],
+};
+// `type` is the other member `AnchorHTMLAttributes` adds, and it is
+// deliberately absent. It is not a link attribute in any useful sense: it is
+// an ordinary prop on form controls and buttons, which bestax components
+// declare in their own right. This rule cannot tell "the anchor contributed
+// it" from "the component owns it", and treating it as a link attribute
+// stripped `type="text"` off every `<Input>` in the fixtures. So
+// `<Button as="span" type="button">` still ships a type error -- one the
+// source wrote rather than one the codemod created, which is the trade.
+// `rel` is deliberately absent: React declares it on `HTMLAttributes`, so it
+// is valid on every intrinsic and there is nothing to remove. The same point
+// `bulma-ui/src/__typetests__/polymorphic.tsx` makes about it.
+/**
+ * The link attributes a target accepts, where its props do not follow `as`.
+ *
+ * Most components here either follow `as` (the element decides, above) or
+ * extend `AnchorHTMLAttributes` outright (`Pagination.*`, `Panel.Block`, so
+ * everything is fine). `Level.Item` is the exception that enumerates: it
+ * declares `href`, `target` and `rel` and nothing else, so `download`,
+ * `hrefLang`, `ping` and `referrerPolicy` are type errors there even at
+ * `as="a"`.
+ *
+ * A target absent from `HREF_OK` needs no row: a component that takes no
+ * `href` at any `as` takes none of its siblings either -- verified for
+ * `Card.FooterItem`, `Tabs.Item` and `Delete`, which is why this is derived
+ * from that table rather than being a second list to keep.
+ */
+const TARGET_LINK_ATTRS = {
+    'Level.Item': ['target'],
+};
+/** The rows the type test holds to the library. */
+export const TARGET_LINK_ATTR_TABLE = TARGET_LINK_ATTRS;
+/**
+ * The intrinsic elements React types an `href` onto.
+ *
+ * Only relevant to plain markup. On a bestax component the anchor is the only
+ * `as` that keeps an `href`, because the components disagree about what they
+ * forward (see `ANCHOR` below) -- but a plain `<area href>` has no component
+ * in the way, and it is valid.
+ */
+export const HREF_ELEMENTS = ['a', 'area', 'base', 'link'];
+/**
+ * The HTML half of `JSX.IntrinsicElements`, as of `@types/react` 19.
+ *
+ * Regenerate by reading the keys between `interface IntrinsicElements {` and
+ * the `// SVG` comment in `@types/react/index.d.ts`. `as-unions.test.ts`
+ * holds the link tables to this set, so it is checked rather than trusted.
+ *
+ * SVG is excluded deliberately: `SVGAttributes` declares `href`, `media` and
+ * `target`, so every SVG tag would join those rows. What that means for a
+ * plain rewrite is `tagRejectsHref`'s problem, not a reason to widen this.
+ */
+export const HTML_INTRINSICS = [
+    'a',
+    'abbr',
+    'address',
+    'area',
+    'article',
+    'aside',
+    'audio',
+    'b',
+    'base',
+    'bdi',
+    'bdo',
+    'big',
+    'blockquote',
+    'body',
+    'br',
+    'button',
+    'canvas',
+    'caption',
+    'center',
+    'cite',
+    'code',
+    'col',
+    'colgroup',
+    'data',
+    'datalist',
+    'dd',
+    'del',
+    'details',
+    'dfn',
+    'dialog',
+    'div',
+    'dl',
+    'dt',
+    'em',
+    'embed',
+    'fieldset',
+    'figcaption',
+    'figure',
+    'footer',
+    'form',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'head',
+    'header',
+    'hgroup',
+    'hr',
+    'html',
+    'i',
+    'iframe',
+    'img',
+    'input',
+    'ins',
+    'kbd',
+    'keygen',
+    'label',
+    'legend',
+    'li',
+    'link',
+    'main',
+    'map',
+    'mark',
+    'menu',
+    'menuitem',
+    'meta',
+    'meter',
+    'nav',
+    'noindex',
+    'noscript',
+    'object',
+    'ol',
+    'optgroup',
+    'option',
+    'output',
+    'p',
+    'param',
+    'picture',
+    'pre',
+    'progress',
+    'q',
+    'rp',
+    'rt',
+    'ruby',
+    's',
+    'samp',
+    'script',
+    'search',
+    'section',
+    'select',
+    'slot',
+    'small',
+    'source',
+    'span',
+    'strong',
+    'style',
+    'sub',
+    'summary',
+    'sup',
+    'table',
+    'tbody',
+    'td',
+    'template',
+    'textarea',
+    'tfoot',
+    'th',
+    'thead',
+    'time',
+    'title',
+    'tr',
+    'track',
+    'u',
+    'ul',
+    'var',
+    'video',
+    'wbr',
+    'webview',
+];
+/**
+ * Whether a plain tag is known NOT to take an `href`.
+ *
+ * `HREF_ELEMENTS` is the HTML answer, and bloomer's `plainTag` can return any
+ * literal the source wrote -- including an SVG tag, where `SVGAttributes`
+ * declares `href`. Treating "not in the HTML list" as "takes no href" lost a
+ * working `href` off `<TabLink tag="use" href="#icon">`. An unrecognised tag
+ * is left alone: this pass removes attributes it can prove are dead, and it
+ * cannot prove that here.
+ */
+export function tagRejectsHref(tag) {
+    return HTML_INTRINSICS.includes(tag) && !HREF_ELEMENTS.includes(tag);
+}
+// `<style href>` is React 19 only -- it arrived with stylesheet hoisting, and
+// `StyleHTMLAttributes` has no `href` in React 18. bulma-ui's peer range is
+// `^18 || ^19` and CI builds both, so a row true of only one major would have
+// the codemod emit output that fails in a supported project. These rows are
+// the common denominator, which is not what a probe against the installed
+// types answers -- only React 19's are here, and they said to add `style`.
+/** Whether `element` renders `attr` legally -- exported for the plain-markup path. */
+export function elementTakesLinkAttr(name, element) {
+    const allowed = LINK_ATTR_ELEMENTS[name];
+    return !allowed || allowed.includes(element);
+}
+/** The link attributes, for callers that iterate them. */
+export const LINK_ATTRS = Object.keys(LINK_ATTR_ELEMENTS);
+/** The rows the type test holds to React. */
+export const LINK_ATTR_TABLE = LINK_ATTR_ELEMENTS;
+/**
+ * Drop an `as` the bestax target cannot render, naming the elements it can.
+ *
+ * A literal only. A dynamic `as` is left exactly as written, and the reason is
+ * the one `rbx/mapping.ts` gives for its `AS_OK` entries: `as={SomeComponent}`
+ * against a narrowed union should surface as a type error the author reads,
+ * not a silent rewrite. Removing it here would delete a live reference to
+ * their component and quietly render something else.
+ */
+function restrictAsValue(ctx, path, element, target, attr, literal) {
+    const allowed = AS_UNIONS[target];
+    if (!allowed || !attr || !literal)
+        return;
+    if (literal.kind !== 'string' || allowed.includes(literal.value))
+        return;
+    const offered = allowed.map(a => `\`${a}\``).join(' / ');
+    removeAttr(element, attr);
+    addTodo(ctx, path, 'prop:as', `bestax \`${target}\` renders only ${offered}, so \`as="${literal.value}"\` cannot carry across — wrap it in a <${literal.value}> or restructure`);
+    ctx.dirty = true;
+}
+/**
+ * Drop an `href` the element cannot take.
+ *
+ * The element is read from the `as` the target actually declares, never from
+ * whatever attribute happens to be spelled `as`, and from the value as it was
+ * written -- `restrictAsValue` may be about to remove it, and an element this
+ * pass has already forgotten cannot be judged.
+ */
+function dropInertHref(ctx, path, element, target, literal, elementKnown) {
+    const href = findAttr(element, 'href');
+    if (!href)
+        return;
+    const wasWritten = attrSource(ctx.j, href);
+    const drop = (why) => {
+        removeAttr(element, href);
+        const was = wasWritten ? ` -- it read \`${wasWritten}\`` : '';
+        addTodo(ctx, path, 'prop:href', `${why}${was}`);
+        ctx.dirty = true;
+    };
+    const defaultEl = HREF_OK[target];
+    if (!defaultEl) {
+        drop(NO_HREF_HINT[target] ??
+            `bestax \`${target}\` takes no \`href\` at any \`as\` -- navigate in \`onClick\`, or put an <a> inside it`);
+        return;
+    }
+    // Past here every answer depends on which element renders. A dynamic `as`
+    // may well be an anchor at runtime, and a spread may supply one; guessing
+    // either way is worse than leaving the pair for the author.
+    if (!elementKnown)
+        return;
+    if (literal && literal.kind !== 'string')
+        return;
+    // An `as` naming a tag the target does not render is dropped by
+    // `restrictAsValue`, so what renders is the component's own default -- the
+    // same element as if no `as` had been written at all.
+    const rendered = literal && literal.kind === 'string' && acceptsAs(target, literal.value)
+        ? literal.value
+        : undefined;
+    if (rendered === undefined) {
+        if (defaultEl === ANCHOR)
+            return;
+        drop(`bestax \`${target}\` renders a <${defaultEl}> unless \`as\` says otherwise, and only its <a> form carries an \`href\` -- set \`as="a"\` to make this a link, or ${nestOrClick(defaultEl)}`);
+        return;
+    }
+    if (rendered === ANCHOR)
+        return;
+    // Which remedy is right depends on what the target renders with no `as`.
+    // "drop the `as`" is only a link on the targets whose bare element is the
+    // anchor; on `Button` it gives a <button> that will not compile, and on
+    // `Level.Item` a <div> that compiles and quietly is not a link.
+    const remedy = defaultEl === ANCHOR
+        ? `drop the \`as\` to make this a link, or ${nestOrClick(rendered)}`
+        : `set \`as="a"\` to make this a link -- dropping the \`as\` gives you a <${defaultEl}> -- or ${nestOrClick(rendered)}`;
+    drop(`\`href\` on \`as="${rendered}"\`: bestax gives an element the attributes of the tag \`as\` names, and a <${rendered}> takes no \`href\` (it navigated nowhere in the source either) -- ${remedy}`);
+}
+/**
+ * Drop a link attribute the rendered element does not take.
+ *
+ * Independent of `href`: `<Navbar.Link as="span" target="_blank">` is invalid
+ * with or without one, and the sources emit both shapes. Each attribute is
+ * judged against the element rather than as a group, so a `referrerPolicy` on
+ * an `<img>` and a `target` on a `<form>` stay.
+ */
+function dropInertLinkAttrs(ctx, path, element, target, rendered) {
+    const carriesLinks = HREF_OK[target] !== undefined;
+    const declared = TARGET_LINK_ATTRS[target];
+    for (const name of LINK_ATTRS) {
+        // Both have to allow it. A target that enumerates its props can be
+        // narrower than the element, and the element can be narrower than the
+        // target: `Level.Item` declares `target` but forwards it only when the
+        // tag is an `<a>`, so `<Level.Item as="p" target="_blank">` was keeping
+        // the same inert attribute this pass removes everywhere else.
+        // Which check rejects it decides both the outcome and what the TODO says.
+        // Keying the message off "the target has a row" instead told a
+        // `<Level.Item as="p" target>` reader that `Level.Item` does not declare
+        // `target` -- it does; the <p> is what refuses it.
+        let rejectedBy = null;
+        if (!carriesLinks)
+            rejectedBy = 'component';
+        else if (declared && !declared.includes(name))
+            rejectedBy = 'component';
+        // A dynamic `as` leaves the element unknown, and guessing either way is
+        // worse than leaving it for the author.
+        else if (rendered !== undefined && !elementTakesLinkAttr(name, rendered))
+            rejectedBy = 'element';
+        if (!rejectedBy)
+            continue;
+        const attr = findAttr(element, name);
+        if (!attr)
+            continue;
+        const was = attrSource(ctx.j, attr);
+        removeAttr(element, attr);
+        const because = rejectedBy === 'element'
+            ? `\`${name}\` needs an element that takes it, and \`${target}\` renders a <${rendered}> here`
+            : !carriesLinks
+                ? `bestax \`${target}\` is not a link at any \`as\`, so it takes no \`${name}\` either`
+                : `bestax \`${target}\` declares its own props rather than taking the element's, and \`${name}\` is not among them`;
+        addTodo(ctx, path, `prop:${name}`, `${because} -- ${was ? `it read \`${was}\`; ` : ''}${remedyFor(target, rendered)}`);
+        ctx.dirty = true;
+    }
+}
+/**
+ * The `as` attribute only if no spread can overwrite it. `findAttr` reads by
+ * name and knows nothing about `{...rest}`, which JSX applies last-write-wins.
+ */
+function lastWordOnAs(element, spreadCanCarryAs) {
+    const attrs = element.openingElement?.attributes ?? [];
+    let seen;
+    let shadowed = false;
+    for (const a of attrs) {
+        if (a.type === 'JSXSpreadAttribute') {
+            if (seen && spreadCanCarryAs) {
+                seen = undefined;
+                shadowed = true;
+            }
+        }
+        else if (a.name?.name === 'as') {
+            seen = a;
+            shadowed = false;
+        }
+    }
+    return { attr: seen, shadowed };
+}
+/**
+ * The whole-element pass each source runs after its prop passes, once the
+ * bestax `target` and the final `as` are both known.
+ */
+export function enforcePolymorphicProps(ctx, path, element, target, 
+/**
+ * Whether a spread on this element could be carrying an `as`.
+ *
+ * Only where the SOURCE spells its element prop `as`, which is rbx alone.
+ * bloomer's is `tag` and react-bulma-components' is `renderAs`, and the
+ * rename only ever touches a literal attribute -- a `renderAs` key inside
+ * `{...rest}` never becomes an `as`. Guessing `true` everywhere let
+ * `<Button renderAs="span" {...rest} href="/x">` through untouched, which
+ * is the shape this pass exists to remove.
+ */
+spreadCanCarryAs = false) {
+    // Read the `as` once, before either rule can remove it, and only where the
+    // target declares one at all -- and only when JSX precedence says this
+    // attribute is the one that wins. A spread after it overwrites it, so
+    // `<Button as="span" {...p} href="/x">` with `p.as === "a"` rendered an
+    // anchor while this pass read `span` and deleted a working `href`. An `as`
+    // the spread can overwrite is treated as unknown, which is the same answer
+    // this pass already gives for a dynamic one.
+    const read = declaresAs(target)
+        ? lastWordOnAs(element, spreadCanCarryAs)
+        : { attr: undefined, shadowed: false };
+    // A spread with no `as` written beside it keeps the ordinary reading, and
+    // that is a settled decision rather than an oversight. `{...rest}` is on
+    // half the elements in a real app; treating every one as an unknown element
+    // would keep `href` on components that take none, which is the defect this
+    // pass exists to remove. It trades a silent invalid `href` for a reported
+    // dropped one, and the reported one is the better failure. Weighed against
+    // the alternative and chosen deliberately -- these are dead source
+    // libraries and the simpler rule is the right one. Do not re-open it
+    // without a real migration that it got wrong.
+    //
+    // `restrictAsValue` still runs on a shadowed `as`. An out-of-union literal
+    // is invalid exactly as written, and dead if the spread overwrites it, so
+    // removing it is right either way.
+    const attr = read.attr ?? findAttr(element, 'as');
+    const literal = attr ? literalValueOf(attr) : undefined;
+    // Shadowing makes the ELEMENT unknown, not the component. Returning here
+    // skipped the union check and the component-level `href` rule as well, so
+    // `<Image as="span" {...p} href="/x">` kept both an `as` outside `Image`'s
+    // union and an `href` it declares at no `as` -- two facts the spread cannot
+    // change.
+    dropInertHref(ctx, path, element, target, literal, !read.shadowed);
+    // The element as it will render: the `as` if the target takes it, otherwise
+    // the component's own. Unknown for a dynamic `as`, and unknown for a target
+    // outside `HREF_OK` that was given no `as` -- the default element is only
+    // recorded for the targets in that table. So this rule reaches an explicit
+    // accepted `as` on any target, plus those targets bare; elsewhere it
+    // declines rather than guesses.
+    const rendered = read.shadowed
+        ? undefined
+        : literal && literal.kind === 'string'
+            ? acceptsAs(target, literal.value)
+                ? literal.value
+                : HREF_OK[target]
+            : literal
+                ? undefined
+                : HREF_OK[target];
+    dropInertLinkAttrs(ctx, path, element, target, rendered);
+    restrictAsValue(ctx, path, element, target, attr, literal);
+    // Only now, and only if something element-dependent actually survived. The
+    // first version fired on every `as` beside a spread -- `<Title as="h2"
+    // {...rest}>` is a complete migration with nothing at stake and was getting
+    // a TODO -- and it ran before the passes, so it also claimed attributes
+    // were "left as written" that the component-level rules had just removed.
+    if (read.shadowed) {
+        const left = ['href', ...LINK_ATTRS].filter(n => findAttr(element, n));
+        if (left.length) {
+            addTodo(ctx, path, 'prop:as', `a spread after \`as\` can overwrite it, so which element \`${target}\` renders here is not knowable -- ${left
+                .map(n => `\`${n}\``)
+                .join(', ')} ${left.length > 1 ? 'were' : 'was'} left as written, and whether ${left.length > 1 ? 'they are' : 'it is'} valid depends on what the spread supplies`);
+        }
+    }
+}