bestax-migrate 2.3.0 → 2.3.2

package/dist/sources/_shared/polymorphic.js

@@ -0,0 +1,593 @@
+/**
+ * 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',
+    '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>',
+    'Dropdown.Item': 'bestax `Dropdown.Item` declares no `href` and already renders an <a> by default, so an <a> inside would nest anchors; navigate in `onClick`',
+};
+/**
+ * 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',
+    // Both already render interactive elements -- a <button> and an <a> -- 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>',
+    'Dropdown.Item': 'navigate in `onClick`',
+};
+const remedyFor = (target) => LINK_REMEDY[target] ?? 'put it on an <a> inside, 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
+ * `Dropdown.Item`, `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 navigate in \`onClick\``);
+        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 put an <a> inside'
+        : `set \`as="a"\` to make this a link -- dropping the \`as\` gives you a <${defaultEl}> -- or put an <a> inside`;
+    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)}`);
+        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 nine that can carry a link. So this rule reaches an
+    // explicit accepted `as` on any target, plus those nine 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`);
+        }
+    }
+}

package/dist/sources/_shared/specials-utils.d.ts

@@ -76,6 +76,15 @@ export declare function modifierClass(ctx: TransformContext, path: ASTPath<any>,
  * it is picked.
  */
 export declare function restrictAsToTargets(ctx: TransformContext, path: ASTPath<any>, element: any, target: string | undefined, allowed: string[], prop?: string): void;
+/**
+ * Strip the link attributes a plain element cannot carry.
+ *
+ * Exported because not every source reaches plain markup through
+ * `replaceWithPlain`: react-bulma-components builds six of its replacements
+ * by hand, and they bypassed this entirely -- `<Form.Help href="/x">` became
+ * `<p className="help" href="/x">`, which does not compile.
+ */
+export declare function dropLinkAttrsForPlainTag(ctx: TransformContext, path: ASTPath<any>, element: any, tag: string, where: string): void;
 /** Attribute filter a source applies before an element becomes plain HTML. */
 export type AttrStrip = (ctx: TransformContext, path: ASTPath<any>, attrs: any[], where: string) => any[];
 /**

package/dist/sources/_shared/specials-utils.d.ts.map

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