@binclusive/a11y 0.1.0

package/src/suggest.ts

@@ -0,0 +1,328 @@
+/**
+ * `init --suggest`: scaffold the `binclusive.json` `components` map by GUESSING,
+ * from each unresolved wrapper's NAME, the HTML host it most likely renders.
+ *
+ * This removes the one manual step in adoption. Today a team with a custom
+ * design system hand-writes `{ "Button": "button", "TextField": "input", … }`;
+ * this pre-fills that map with best-guess hosts for the design-system's leaf
+ * primitives, for the team to REVIEW before committing.
+ *
+ * CONSERVATISM IS THE WHOLE DISCIPLINE (same as `enforce.ts`). A name guess is
+ * weaker evidence than a registry hit or a source trace — auto-applying one
+ * silently is exactly how you'd manufacture false positives. So this module:
+ *
+ *   - SUGGESTS, never decides: every guess is printed for review, and the
+ *     uncertain ones carry a ⚠ `verify` flag so the user looks twice.
+ *   - is OPT-IN behind `--suggest`: plain `init` writes no guessed map. The
+ *     suggestions only land in `binclusive.json` when the user asked for them.
+ *   - SKIPS composites: a name that names a multi-element widget (`Modal`,
+ *     `Dropdown`, `Tabs`, a `*Provider`, …) has NO single host, so it stays in
+ *     the declare bucket rather than being mis-mapped to one element.
+ *   - SKIPS toggles: `Checkbox`/`Switch`/`Radio`/`Toggle` are externally
+ *     labelled — enforce skips them, and so does the suggestion (mapping one to
+ *     `input`/`button` would invite the same false positives enforce avoids).
+ *
+ * The guess vocabulary REUSES `enforce.ts` (`NAME_HEURISTICS` / `typeFromName`)
+ * for the control types those heuristics already know (button / icon-button /
+ * link / image), and extends it with the input-family leaf names enforce
+ * deliberately omits. Enforce omits inputs because their accessible name comes
+ * from an external label it can't see at the call site — a FALSE-POSITIVE risk
+ * for an enforcing check. A SUGGESTION carries no such risk: it only proposes a
+ * host for the user to confirm, never fires a finding, so suggesting `input`
+ * for `*TextField` / `*Input` / `*Field` is safe and is the whole point.
+ */
+
+import type { ControlType } from "./enforce";
+import { leafName, TOGGLE_NAMES, typeFromName } from "./enforce";
+import { familyLabel, isFrameworkPrimitive, isOwnModule, packageNameOf } from "./module-scope";
+import type { ComponentResolution } from "./resolve-components";
+
+/**
+ * How confident the host guess is — the lever that keeps a name guess from
+ * being mistaken for a proven host:
+ *
+ *   - `confident` — the leaf name maps UNAMBIGUOUSLY to one host (`*Button` →
+ *     `button`, `*TextField` → `input`, `*Link` → `a`, `*Avatar` → `img`).
+ *     Printed with a ✓; still review-only, but a safe default.
+ *   - `verify`    — the name maps to a host that is OFTEN a custom widget rather
+ *     than the native element (`Select` → could be a combobox, not a native
+ *     `<select>`), or only loosely matches. Printed with a ⚠ and a reason, so
+ *     the user looks twice before trusting it.
+ */
+export type SuggestConfidence = "confident" | "verify";
+
+/** One suggested wrapper → host mapping, with its confidence and source. */
+export interface ComponentSuggestion {
+  /**
+   * The `components`-map KEY: the wrapper's LEAF name (`CommandPrimitive.Input`
+   * → `Input`), the same key the declared-host lookup matches on, so the
+   * scaffolded entry actually takes effect. Usually identical to the JSX name.
+   */
+  readonly name: string;
+  /** The module it is imported from, e.g. `"@acme/ui"`. */
+  readonly module: string;
+  /** The guessed HTML host primitive, e.g. `"button"` / `"input"` / `"a"`. */
+  readonly host: string;
+  readonly confidence: SuggestConfidence;
+  /** A short reason, present ONLY for a `verify` guess; `null` for `confident`. */
+  readonly reason: string | null;
+}
+
+/** The full outcome of a suggestion pass, for the CLI to print + persist. */
+export interface SuggestResult {
+  /** The suggested wrapper → host mappings, sorted for a deterministic report. */
+  readonly suggestions: readonly ComponentSuggestion[];
+  /**
+   * Declare-bucket components left UNMAPPED because they are composites (no
+   * single host) or toggles — kept so the CLI can print "left in declare".
+   * Names only, deduped, sorted.
+   */
+  readonly skipped: readonly string[];
+}
+
+/** Inputs for {@link suggestComponentMap}, parallel to `detect-stack`'s scoping. */
+export interface SuggestOptions {
+  /**
+   * Predicate identifying a module specifier that resolves to the repo's OWN
+   * code (relative imports, `@/`, `~`, `#`, and tsconfig path aliases that map
+   * into own source). Own components are one-offs, not a design system — they
+   * are never suggested. Mirror `ownAliasMatcherFor(dir).isOwnAlias`.
+   */
+  readonly isOwnAlias: (specifier: string) => boolean;
+  /**
+   * The detected design-system LABEL (e.g. `"@acme/ui"`, or a collapsed family
+   * name like `"Radix"`), or `null`/`"custom"` when none was detected.
+   * Suggestions from this design system sort FIRST so the most relevant guesses
+   * lead the printed list; it does not gate inclusion. The rank comparison
+   * collapses each suggestion's package through {@link familyLabel} so a family
+   * label still matches its per-component sub-packages.
+   */
+  readonly designSystem: string | null;
+}
+
+/**
+ * Composite leaf names — multi-element widgets with NO single host element, so
+ * they CANNOT be mapped to one primitive and stay in the declare bucket. Each is
+ * a whole-name or suffix match (so `ConfirmDialog`, `UserMenu`, `SidePanel`
+ * resolve), never a prefix (a `CardGrid` is its own thing). This is the
+ * conservative inverse of the leaf-control vocabulary: when a name is a
+ * composite, we REFUSE to guess a host rather than mis-map it.
+ *
+ * Kept SEPARATE from enforce's `dialog` heuristic on purpose: enforce treats
+ * `Dialog`/`Modal` as a recognizable control TYPE (for its dialog rule), but for
+ * HOST mapping a dialog has no single element — so here it is a composite to
+ * skip, not a host to suggest.
+ */
+const COMPOSITE_KEYWORDS: readonly string[] = [
+  "Modal",
+  "Dialog",
+  "Drawer",
+  "Sheet",
+  "Popover",
+  "Tooltip",
+  "Dropdown",
+  "Menu",
+  "Tabs",
+  "Tab",
+  "Accordion",
+  "Collapse",
+  "Carousel",
+  "Card",
+  "Panel",
+  "Layout",
+  "Grid",
+  "Stack",
+  "Box",
+  "Flex",
+  "Container",
+  "Provider",
+  "Form",
+  "Table",
+  "List",
+  "Tree",
+  "Stepper",
+  "Breadcrumb",
+  "Pagination",
+  "Slider",
+  "Calendar",
+  "DatePicker",
+  "Combobox",
+  "Autocomplete",
+  "Command",
+];
+
+/**
+ * Input-family leaf keywords enforce deliberately OMITS (its name heuristic
+ * never guesses an input host — a false-positive risk for an enforcing check).
+ * A SUGGESTION carries no such risk, so it extends the vocabulary here. Order
+ * matters: the more specific `Textarea` precedes `Field`/`Input` so a
+ * `SearchTextarea` resolves to `textarea`, not `input`.
+ *
+ * Each entry also carries whether the guess is CONFIDENT or needs ⚠ `verify`:
+ * `Select` maps to `select` but is FLAGGED — a "Select" in a design system is
+ * frequently a custom combobox (a `<div role="combobox">`), not a native
+ * `<select>` — so we suggest the host yet ask the user to confirm.
+ */
+const INPUT_KEYWORDS: ReadonlyArray<{
+  readonly keyword: string;
+  readonly host: string;
+  readonly confidence: SuggestConfidence;
+  readonly reason: string | null;
+}> = [
+  { keyword: "Textarea", host: "textarea", confidence: "confident", reason: null },
+  { keyword: "TextArea", host: "textarea", confidence: "confident", reason: null },
+  { keyword: "TextField", host: "input", confidence: "confident", reason: null },
+  { keyword: "TextInput", host: "input", confidence: "confident", reason: null },
+  { keyword: "Input", host: "input", confidence: "confident", reason: null },
+  { keyword: "Field", host: "input", confidence: "confident", reason: null },
+  {
+    keyword: "Select",
+    host: "select",
+    confidence: "verify",
+    reason: "could be a custom widget, not a native <select>",
+  },
+];
+
+/**
+ * Anchor/image leaf keywords enforce's `Link`/`Image` heuristic doesn't spell
+ * out (it matches `Link`/`Image` suffixes; these are the design-system aliases).
+ * `Anchor` → `a`; `Avatar`/`Img` → `img`.
+ */
+const EXTRA_KEYWORDS: ReadonlyArray<{ readonly keyword: string; readonly host: string }> = [
+  { keyword: "Anchor", host: "a" },
+  { keyword: "Avatar", host: "img" },
+  { keyword: "Img", host: "img" },
+];
+
+/** Map an enforce {@link ControlType} to the HTML host it denotes for suggesting. */
+const TYPE_TO_HOST: Readonly<Record<ControlType, string | null>> = {
+  button: "button",
+  "icon-button": "button",
+  link: "a",
+  image: "img",
+  input: "input",
+  // A dialog is a composite — no single host. Never suggested (caught earlier as
+  // a composite name); mapped to `null` here so the type is exhaustive.
+  dialog: null,
+};
+
+/** Whether `leaf` equals or ends with `keyword` (suffix match, never prefix). */
+function matchesKeyword(leaf: string, keyword: string): boolean {
+  return leaf === keyword || leaf.endsWith(keyword);
+}
+
+/**
+ * Guess a host for a single leaf name, or `null` when the name is a composite /
+ * toggle / unrecognized (no host to suggest). Precedence is by certainty:
+ *
+ *   1. toggle  → skip (externally labelled; enforce skips them too).
+ *   2. composite → skip (multi-element widget, no single host).
+ *   3. input family → `input` / `textarea` / `select` (with a ⚠ for `Select`).
+ *   4. anchor / image aliases → `a` / `img`.
+ *   5. enforce's control-type heuristic → button / link / image (reused).
+ */
+function guessHost(name: string): Omit<ComponentSuggestion, "name" | "module"> | null {
+  const leaf = leafName(name);
+
+  // Toggles are externally labelled — enforce skips them, so does suggestion.
+  if (TOGGLE_NAMES.has(leaf)) return null;
+
+  // Composite widget — no single host. Leave it in declare.
+  if (COMPOSITE_KEYWORDS.some((k) => matchesKeyword(leaf, k))) return null;
+
+  // Input family (enforce omits these; a suggestion can safely propose them).
+  for (const { keyword, host, confidence, reason } of INPUT_KEYWORDS) {
+    if (matchesKeyword(leaf, keyword)) return { host, confidence, reason };
+  }
+
+  // Anchor / image aliases enforce's Link/Image suffix doesn't name explicitly.
+  for (const { keyword, host } of EXTRA_KEYWORDS) {
+    if (matchesKeyword(leaf, keyword)) return { host, confidence: "confident", reason: null };
+  }
+
+  // Reuse enforce's name heuristic for button / icon-button / link / image.
+  const type = typeFromName(name);
+  if (type === null) return null;
+  const host = TYPE_TO_HOST[type];
+  if (host === null) return null; // dialog → composite, no host
+  return { host, confidence: "confident", reason: null };
+}
+
+/**
+ * Whether a declare-bucket resolution is in scope for suggesting: it must come
+ * from an EXTERNAL, non-framework module. Own code (`./`, `@/`, `~`, `#`,
+ * tsconfig-alias own source) is one-off app components, not a design system;
+ * framework primitives (`next`, `react`, …) are the platform, not a UI library.
+ * Mirrors the same two gates `detect-stack.detectDesignSystem` applies.
+ */
+function inScope(r: ComponentResolution, isOwnAlias: (s: string) => boolean): boolean {
+  if (isOwnModule(r.module, isOwnAlias)) return false;
+  return !isFrameworkPrimitive(packageNameOf(r.module));
+}
+
+/**
+ * Suggest a `components` map from the resolution set: take the DECLARE-bucket
+ * components (genuine unknowns — `provenance === "opaque"`, `opaqueKind ===
+ * "declare"`), scope them to external non-framework modules, and guess a host
+ * for each from its NAME. Composites and toggles are left in declare (no single
+ * host); everything else yields a suggestion, ⚠-flagged when uncertain.
+ *
+ * Pure — no disk, no detection. The caller supplies the own-code matcher and the
+ * detected design system; the function does the name reasoning. Each suggestion
+ * is keyed by the wrapper's LEAF name (the same key the declared-host lookup
+ * uses), deduped so a wrapper used in many files yields one suggestion, and
+ * sorted for a deterministic report: design-system suggestions first, then by
+ * name.
+ */
+export function suggestComponentMap(
+  resolutions: readonly ComponentResolution[],
+  opts: SuggestOptions,
+): SuggestResult {
+  const designSystem =
+    opts.designSystem === null || opts.designSystem === "custom" ? null : opts.designSystem;
+
+  const suggestions: ComponentSuggestion[] = [];
+  const skipped = new Set<string>();
+  const seen = new Set<string>();
+
+  for (const r of resolutions) {
+    // Only genuine unknowns are candidates — the design-system primitives the
+    // checker could not resolve. trusted / icons / structural are NOT gaps.
+    if (r.provenance !== "opaque" || r.opaqueKind !== "declare") continue;
+    if (!inScope(r, opts.isOwnAlias)) continue;
+
+    // Key the suggestion by the LEAF name — the SAME key the declared-host
+    // lookup in `resolveComponents` uses (`jsxKeyFor`). A namespace render
+    // (`CommandPrimitive.Input`) is matched on its trailing member, so the
+    // scaffolded `components` entry must be `{ "Input": "input" }` to take
+    // effect, not `{ "CommandPrimitive.Input": ... }` which would never match.
+    const key = leafName(r.name);
+
+    // Dedupe by the map key so a wrapper used widely is suggested once.
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const guess = guessHost(r.name);
+    if (guess === null) {
+      // Composite or toggle — no single host; it stays in the declare bucket.
+      skipped.add(key);
+      continue;
+    }
+    suggestions.push({ name: key, module: r.module, ...guess });
+  }
+
+  // Design-system suggestions first, then alphabetical — deterministic output.
+  // `designSystem` is the DETECTED label, which is collapsed to a family name for
+  // known multi-package families (`@radix-ui/react-checkbox` -> `Radix`), so the
+  // suggestion's package is run through the SAME collapse before comparing —
+  // otherwise a Radix app's per-component packages would never match `Radix` and
+  // the design-system-first sort would silently regress.
+  const rank = (s: ComponentSuggestion): number =>
+    designSystem !== null && familyLabel(packageNameOf(s.module)) === designSystem ? 0 : 1;
+  suggestions.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name));
+
+  return {
+    suggestions,
+    skipped: [...skipped].sort((a, b) => a.localeCompare(b)),
+  };
+}

package/src/suppression-ranges.ts

@@ -0,0 +1,354 @@
+import ts from "typescript";
+
+/**
+ * Finding-suppression line ranges: spans of a file where a static finding would
+ * be a false positive because the source doesn't reflect the runtime / a11y
+ * tree. Two sources — runtime child-injection (Trans / render-delegation,
+ * detailed below) and `aria-hidden` subtrees. Callers union the ranges and skip
+ * any finding on a covered line.
+ *
+ * ── Runtime child-injection ──
+ *
+ * Content rules (`anchor-has-content`, `heading-has-content`,
+ * `anchor-is-valid`) assume the element they fire on is empty because it has no
+ * JSX children. Two widely-used React patterns break that assumption by
+ * injecting children at RUNTIME, so the JSX looks childless but the rendered
+ * element is not. Both produce the same false positive, from the same cause:
+ *
+ * 1. react-i18next `<Trans>` interpolation. Elements passed in
+ *    `components={[...]}` / `components={{ key: <El/> }}` receive the
+ *    translated string's `<0>…</0>` placeholder text as their children:
+ *
+ *        <Trans defaults="<0>Create an account</0>"
+ *               components={[<a href="/register" />]} />
+ *
+ *    The `<a/>` is contentful at runtime.
+ *
+ * 2. Render-delegation props (`render={<El/>}` in base-ui / MUI Base, the value
+ *    of `asChild` chains in Radix). The host component renders AS the delegated
+ *    element and forwards ITS OWN children into it:
+ *
+ *        <BreadcrumbLink render={<Link href="/polls" />}>
+ *          <Icon /> <Trans defaults="Polls" />
+ *        </BreadcrumbLink>
+ *
+ *    The `<Link/>` (an anchor) renders with the breadcrumb's icon+text children.
+ *
+ * The fix is semantic, scoped, and false-negative-safe:
+ *   - We suppress ONLY content-family findings (the rules whose "no children"
+ *     premise the injection invalidates). ARIA/role/handler findings on the
+ *     same element still surface.
+ *   - For render-delegation we suppress ONLY when the host element actually
+ *     HAS children to inject — a `<Button render={<Link/>} />` with no children
+ *     is a genuinely empty anchor and must still flag.
+ *
+ * Triggers are public component/prop APIs, not per-repo conventions: the
+ * react-i18next `Trans` component, and the `render` delegation prop. Both reach
+ * us as plain JSX names regardless of which module they were imported from.
+ *
+ * A customer can name THEIR OWN `<Trans>`-like helpers via `binclusive.json`
+ * `injectsChildren`. Those names are treated exactly like the built-in `Trans`:
+ * their `components={...}` targets are runtime-contentful, AND the helper element
+ * ITSELF is treated as contentful (a custom helper typically replaces its own
+ * children with the translated string). This is the escape hatch for the same
+ * runtime-injection pattern when the helper isn't literally named `Trans`.
+ */
+
+/**
+ * jsx-a11y rules whose finding is invalidated by runtime child injection,
+ * because each one's premise is "this element has no text content." Scoped
+ * deliberately: ARIA/role/handler rules are NOT here, so an injected element
+ * with a real ARIA bug still surfaces.
+ */
+const CONTENT_RULES: ReadonlySet<string> = new Set([
+  "jsx-a11y/anchor-has-content",
+  "jsx-a11y/anchor-is-valid",
+  "jsx-a11y/heading-has-content",
+]);
+
+/** The JSX component name react-i18next exposes for interpolation. */
+const TRANS_TAG = "Trans";
+/** The prop on `<Trans>` that carries the interpolation target elements. */
+const COMPONENTS_PROP = "components";
+/** The render-delegation prop (base-ui / MUI Base): host renders AS this element. */
+const RENDER_PROP = "render";
+
+/** A 1-based source line range, inclusive, of a suppressed element. */
+interface LineRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Scan a source file for every JSX element whose children are injected at
+ * runtime — via `<Trans components={...}>` or a `render={<El/>}` delegation on
+ * a host element that supplies children. Returns the 1-based line ranges those
+ * elements occupy; a content-rule finding on a covered line is a false positive.
+ *
+ * `injectsChildren` is the customer's list of THEIR OWN `Trans`-like helper
+ * names (from `binclusive.json`). Each is treated identically to the built-in
+ * `Trans`: its `components={...}` targets are suppressed, and the helper element
+ * itself is suppressed (a custom helper replaces its own children at runtime).
+ */
+export function transInjectedLineRanges(
+  sf: ts.SourceFile,
+  injectsChildren: readonly string[] = [],
+): LineRange[] {
+  const ranges: LineRange[] = [];
+  const customTags = new Set(injectsChildren);
+
+  const lineOf = (pos: number): number => sf.getLineAndCharacterOfPosition(pos).line + 1;
+
+  const recordElement = (node: ts.Node): void => {
+    ranges.push({ start: lineOf(node.getStart(sf)), end: lineOf(node.getEnd()) });
+  };
+
+  // Every JSX element nested under a `<Trans>` `components` value receives
+  // injected text, so both `[<a/>]` and `{ a: <a/> }` are captured.
+  const collectInjected = (node: ts.Node): void => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) recordElement(node);
+    ts.forEachChild(node, collectInjected);
+  };
+
+  /** The trailing name of a JSX tag (`NS.Member` -> `Member`), else the name. */
+  const tagLeafName = (tagName: ts.JsxTagNameExpression): string | null => {
+    if (ts.isIdentifier(tagName)) return tagName.text;
+    if (ts.isPropertyAccessExpression(tagName)) return tagName.name.text;
+    return null;
+  };
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const leaf = tagLeafName(opening.tagName);
+      const isCustomInjector = leaf !== null && customTags.has(leaf);
+
+      if (isTransTag(opening.tagName) || isCustomInjector) {
+        // A customer's own helper replaces ITS OWN children at runtime, so the
+        // helper element itself is contentful — suppress it directly.
+        if (isCustomInjector) recordElement(node);
+        for (const attr of opening.attributes.properties) {
+          if (!ts.isJsxAttribute(attr)) continue;
+          if (attr.name.getText(sf) !== COMPONENTS_PROP) continue;
+          const init = attr.initializer;
+          if (init !== undefined && ts.isJsxExpression(init) && init.expression !== undefined) {
+            collectInjected(init.expression);
+          }
+        }
+      }
+
+      // Render-delegation: suppress the delegated element only when the host
+      // element supplies children for it to render. A childless host means a
+      // genuinely empty delegated element — leave that finding alone.
+      if (hasContentfulChildren(node)) {
+        const delegated = renderPropElement(opening, sf);
+        if (delegated !== null) recordElement(delegated);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  return ranges;
+}
+
+/**
+ * Line ranges of JSX elements marked `aria-hidden` (`aria-hidden={true}` or
+ * `aria-hidden="true"`). Such an element is removed from the accessibility tree
+ * — a screen reader never reaches it — so the content-family rules whose whole
+ * premise is "this element is reachable but empty" (`anchor-has-content`,
+ * `anchor-is-valid`, `heading-has-content`) simply do not apply to it.
+ *
+ * Scope is deliberately narrow: ONLY content-family findings are suppressed
+ * (via the shared {@link CONTENT_RULES} set + {@link isContentSuppressed}).
+ * Everything else on an aria-hidden element — bad ARIA props, role mismatches,
+ * interactive-without-handler — still surfaces, because hiding from the a11y
+ * tree doesn't make those correct. And only `aria-hidden` set to a literal
+ * truthy value counts: `aria-hidden={false}` / `aria-hidden={someVar}` are NOT
+ * suppressed, so a dynamically-shown element keeps flagging.
+ */
+export function ariaHiddenLineRanges(sf: ts.SourceFile): LineRange[] {
+  const ranges: LineRange[] = [];
+  const lineOf = (pos: number): number => sf.getLineAndCharacterOfPosition(pos).line + 1;
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      if (hasTruthyAriaHidden(opening, sf)) {
+        ranges.push({ start: lineOf(node.getStart(sf)), end: lineOf(node.getEnd()) });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return ranges;
+}
+
+/**
+ * Line ranges of JSX elements whose children are forwarded through a `{...props}`
+ * (or `{...rest}`) SPREAD, so the content-family rules cannot prove the element
+ * is empty. This is the design-system primitive shape jsx-a11y is structurally
+ * blind to:
+ *
+ *     const AlertTitle = forwardRef(({ className, ...props }, ref) => (
+ *       <h5 ref={ref} className={cn(...)} {...props} />   // children arrive via {...props}
+ *     ))
+ *     const TabLink = ({ ...props }) => <a className="…" {...props} />
+ *
+ * The `<h5/>` / `<a/>` look childless in the JSX, so `heading-has-content` /
+ * `anchor-has-content` fire — but the consumer passes the heading text / link
+ * label as children, which flow in through the spread. Every shadcn/Radix-style
+ * primitive that wraps a native `<h1-6>` / `<a>` and forwards props hits this,
+ * turning the checker's own "find bugs inside your design system" surface into a
+ * wall of false CRITICALs.
+ *
+ * Same scope + safety contract as the runtime-injection ranges above: ONLY
+ * content-family findings (via {@link isContentSuppressed}) are suppressed, so an
+ * ARIA/role/handler bug on the same spread element still surfaces. A spread can
+ * carry `children` (or `dangerouslySetInnerHTML`); we cannot prove it doesn't, so
+ * the "empty element" premise is unprovable here — exactly as it is for a
+ * `render={<El/>}` delegation — and the content-family finding is withheld rather
+ * than asserted as a false positive.
+ *
+ * Recorded only when the element has NO static contentful children of its own: an
+ * element that already spells out children needs no spread to be contentful and
+ * never fired a content finding anyway, so leaving it unrecorded keeps the range
+ * set tight.
+ *
+ * Scoped to CONTENT-RULE CANDIDATES so the range set stays small: the suppressed
+ * {@link CONTENT_RULES} fire only on `<a>` / `<h1-6>`, so a spread on a `<div>` /
+ * `<button>` / `<td>` can never have a content finding to suppress. We keep the
+ * intrinsic `a` / `h1-6` tags AND any capitalized component — a component may
+ * resolve to `a` / a heading via the jsx-a11y `components` map (a shadcn
+ * `<Link {...props}/>` is reported as an anchor), and this pass can't see that
+ * map, so excluding components would re-open those false positives.
+ */
+function isContentRuleCandidate(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement): boolean {
+  const name = opening.tagName;
+  const tag = ts.isIdentifier(name)
+    ? name.text
+    : ts.isPropertyAccessExpression(name)
+      ? name.name.text
+      : null;
+  if (tag === null) return false;
+  return /^[A-Z]/.test(tag) || tag === "a" || /^h[1-6]$/.test(tag);
+}
+
+export function spreadChildrenLineRanges(sf: ts.SourceFile): LineRange[] {
+  const ranges: LineRange[] = [];
+  const lineOf = (pos: number): number => sf.getLineAndCharacterOfPosition(pos).line + 1;
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const hasSpread = opening.attributes.properties.some((p) => ts.isJsxSpreadAttribute(p));
+      if (hasSpread && isContentRuleCandidate(opening) && !hasContentfulChildren(node)) {
+        ranges.push({ start: lineOf(node.getStart(sf)), end: lineOf(node.getEnd()) });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return ranges;
+}
+
+/** The `aria-hidden` attribute name. */
+const ARIA_HIDDEN_PROP = "aria-hidden";
+
+/**
+ * Whether an opening element carries `aria-hidden` set to a literal truthy
+ * value: bare (`<a aria-hidden>`), `aria-hidden={true}`, or `aria-hidden="true"`.
+ * A literal `false`, or any dynamic expression, returns false — we only suppress
+ * when the element is unconditionally hidden from the a11y tree.
+ */
+function hasTruthyAriaHidden(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): boolean {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    if (attr.name.getText(sf) !== ARIA_HIDDEN_PROP) continue;
+    const init = attr.initializer;
+    // Bare `aria-hidden` (no initializer) is `true`.
+    if (init === undefined) return true;
+    // `aria-hidden="true"`.
+    if (ts.isStringLiteral(init)) return init.text === "true";
+    // `aria-hidden={...}`.
+    if (ts.isJsxExpression(init) && init.expression !== undefined) {
+      const expr = init.expression;
+      if (expr.kind === ts.SyntaxKind.TrueKeyword) return true;
+      if (expr.kind === ts.SyntaxKind.FalseKeyword) return false;
+      // `aria-hidden={"true"}`.
+      if (ts.isStringLiteral(expr)) return expr.text === "true";
+    }
+    return false;
+  }
+  return false;
+}
+
+/** Whether a JSX tag-name node is the react-i18next `Trans` component. */
+function isTransTag(tagName: ts.JsxTagNameExpression): boolean {
+  if (ts.isIdentifier(tagName)) return tagName.text === TRANS_TAG;
+  if (ts.isPropertyAccessExpression(tagName)) return tagName.name.text === TRANS_TAG;
+  return false;
+}
+
+/**
+ * The JSX element passed as a `render={<El/>}` delegation prop on `opening`, or
+ * `null` when there is no such prop. The host will render AS this element.
+ */
+function renderPropElement(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): ts.JsxElement | ts.JsxSelfClosingElement | null {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    if (attr.name.getText(sf) !== RENDER_PROP) continue;
+    const init = attr.initializer;
+    if (init === undefined || !ts.isJsxExpression(init) || init.expression === undefined) continue;
+    const expr = init.expression;
+    if (ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr)) return expr;
+  }
+  return null;
+}
+
+/**
+ * Whether a JSX element has contentful children written directly in the JSX —
+ * non-whitespace text, a nested element/fragment, or an expression child; a
+ * self-closing element has none. Two callers, same predicate: render-delegation
+ * uses it as the false-negative guard (only a child-bearing HOST can make an
+ * otherwise-empty delegated anchor contentful), and the spread suppression uses
+ * its inverse (an element with its own children needs no spread to be contentful,
+ * so it is not a spread-injection candidate).
+ */
+function hasContentfulChildren(node: ts.JsxElement | ts.JsxSelfClosingElement): boolean {
+  if (!ts.isJsxElement(node)) return false;
+  return node.children.some((child) => {
+    if (ts.isJsxText(child)) return child.text.trim() !== "";
+    if (ts.isJsxExpression(child)) return child.expression !== undefined;
+    return ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child);
+  });
+}
+
+/**
+ * Decide whether a content-family finding at `line` is suppressed: true iff the
+ * rule is a content-family rule (its "empty element" premise) AND the line falls
+ * inside one of the supplied ranges. Both suppression sources share this gate:
+ *
+ *   - runtime child injection ({@link transInjectedLineRanges}) — the element
+ *     gets content at render time, so "empty" is wrong.
+ *   - `aria-hidden` ({@link ariaHiddenLineRanges}) — the element is out of the
+ *     a11y tree, so "empty link/heading" doesn't apply.
+ *
+ * Non-content rules are NEVER suppressed, regardless of range — only the
+ * content-family premise is invalidated by these two patterns.
+ */
+export function isContentSuppressed(
+  ruleId: string,
+  line: number,
+  ranges: readonly LineRange[],
+): boolean {
+  if (!CONTENT_RULES.has(ruleId)) return false;
+  return ranges.some((r) => line >= r.start && line <= r.end);
+}