@binclusive/a11y 0.1.0

package/src/suppressor-map.ts

@@ -0,0 +1,189 @@
+import ts from "typescript";
+import type { ResolvedHost } from "./enforce";
+import { isToggleRole } from "./registry";
+import { collectLocalImports, type ImportBinding } from "./source-trace";
+import {
+  isHiddenOrUntabbable,
+  isNameExemptInputType,
+  walkAncestorSuppressors,
+} from "./suppressors";
+
+/**
+ * The deterministic G3 input (RFC Phase 1, §"The FP discipline").
+ *
+ * `buildSuppressorMap` runs the SAME ancestor walk `enforceContent` runs — the
+ * shared {@link walkAncestorSuppressors} descent that decides `hasLabelAncestor`
+ * / `hasNameAncestor` — and records, per JSX line, WHICH of the static floor's
+ * suppressor predicates ({@link src/suppressors}) apply there. The map is the
+ * floor's hard-won precision, re-expressed as data the corpus-recall layer can
+ * (a) feed the model so it self-suppresses and (b) enforce server-side so a
+ * grounded-but-misclassified finding on a suppressed line is vetoed.
+ *
+ * It REUSES the suppressor predicates verbatim — it never re-implements them —
+ * so any drift in the floor's suppression logic ripples here automatically. The
+ * RESOLVED-HOST skips enforce performs (a traced/registry toggle role, a wrapper
+ * that renders its own name, a `type`-exempt INPUT host) need the resolved-host
+ * map enforce uses, so it is threaded in: the same `${name}@${module}` lookup
+ * {@link buildResolvedHosts} builds. It emits no findings and has no side
+ * effects: a pure `(source, resolved hosts) → line → names` read.
+ */
+
+/** The suppressor predicates, named. The string IS the wire name fed to G3. */
+export type SuppressorName =
+  | "label-ancestor"
+  | "name-injecting-wrapper"
+  | "hidden-untabbable"
+  | "name-exempt-input-type"
+  | "toggle-role"
+  | "renders-own-name";
+
+/**
+ * A per-line view of which suppressors apply. Keyed by 1-based line number (the
+ * same line a finding anchors to — an element's opening-tag line). The value is
+ * the set of suppressor names live AT that line:
+ *
+ *   - `label-ancestor` / `name-injecting-wrapper` are ANCESTOR suppressors — a
+ *     line carries them when an enclosing `<label>` / form-field grouping
+ *     (`isLabelContainer`) or a titled `<Tooltip>` (`isNameInjectingWrapper`) is
+ *     an ancestor of the element on that line. They mirror the `labelDepth` /
+ *     `nameAncestorDepth` the shared {@link walkAncestorSuppressors} threads down.
+ *   - `hidden-untabbable` / `name-exempt-input-type` / `toggle-role` /
+ *     `renders-own-name` are ELEMENT-LOCAL — the predicate (or the element's
+ *     resolved host) holds for the element opening ON that line.
+ *
+ * One line can carry several (an exempt input under a label). Lines with no live
+ * suppressor are absent, so `map.get(line) ?? EMPTY` is the safe read.
+ */
+export type SuppressorMap = ReadonlyMap<number, ReadonlySet<SuppressorName>>;
+
+/** A toggle role on the element, mirroring `enforce`'s `isToggleRole` skip. */
+const TOGGLE_ROLES: ReadonlySet<string> = new Set(["checkbox", "switch", "radio"]);
+
+/**
+ * Whether the element opening carries a STATIC toggle `role` (`checkbox` /
+ * `switch` / `radio`). The enforce pass skips toggles reached via a traced/
+ * registry host whose `role` is a toggle (captured by the resolved-host lookup
+ * below); here we ALSO read the role straight off the call-site JSX so the map
+ * captures the call-site-visible toggle case. A dynamic `role={x}` is not
+ * asserted (uncertain → not a suppressor we can name).
+ */
+function hasToggleRole(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement, sf: ts.SourceFile): boolean {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr) || attr.name.getText(sf) !== "role") continue;
+    const init = attr.initializer;
+    let value: string | null = null;
+    if (init !== undefined && ts.isStringLiteral(init)) value = init.text.trim().toLowerCase();
+    else if (
+      init !== undefined &&
+      ts.isJsxExpression(init) &&
+      init.expression !== undefined &&
+      ts.isStringLiteral(init.expression)
+    ) {
+      value = init.expression.text.trim().toLowerCase();
+    }
+    if (value !== null && TOGGLE_ROLES.has(value)) return true;
+  }
+  return false;
+}
+
+/** The bare lowercase intrinsic tag of an opening element, or null (a component). */
+function intrinsicTag(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement): string | null {
+  const tag = opening.tagName;
+  return ts.isIdentifier(tag) && /^[a-z]/.test(tag.text) ? tag.text : null;
+}
+
+/** The flattened JSX tag (`Button`, `NS.Member`), or null if not a name we key on. */
+function tagNameOf(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement): string | null {
+  const tag = opening.tagName;
+  if (ts.isIdentifier(tag)) return tag.text;
+  if (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression)) {
+    return `${tag.expression.text}.${tag.name.text}`;
+  }
+  return null;
+}
+
+/**
+ * The resolved host enforce would see for this call site, or null. Mirrors
+ * `enforce.classify`'s step 1: key the resolved-host map by `(jsx tag, import
+ * module)` so a same-named export from another module can never lend its host.
+ */
+function resolvedHostOf(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  imports: ReadonlyMap<string, ImportBinding>,
+  resolvedHosts: ReadonlyMap<string, ResolvedHost>,
+): ResolvedHost | null {
+  const tag = tagNameOf(opening);
+  if (tag === null) return null;
+  const local = tag.includes(".") ? tag.slice(0, tag.indexOf(".")) : tag;
+  const binding = imports.get(local);
+  if (binding === undefined) return null;
+  return resolvedHosts.get(`${tag}@${binding.module}`) ?? null;
+}
+
+/**
+ * Build the per-line suppressor map for one source file. Mirrors the
+ * `enforceContent` ancestor walk via the shared {@link walkAncestorSuppressors}
+ * (label / name-injecting depth), and reads the element-local predicates — plus
+ * the RESOLVED-HOST skips enforce performs — off each opening:
+ *
+ *   - `name-exempt-input-type` is emitted ONLY for a form intrinsic
+ *     (`input`/`select`/`textarea`) OR a component that RESOLVES to an `input`
+ *     host — the exact gate enforce applies (`isNameExemptInputType` runs only on
+ *     an input host). A capitalized non-input component is never marked.
+ *   - `toggle-role` / `renders-own-name` cover the resolved-host toggle and
+ *     own-name skips (a Radix Checkbox traced to `button[role=checkbox]`, a
+ *     shadcn wrapper that renders its own `sr-only` name) that call-site syntax
+ *     alone cannot see.
+ */
+export function buildSuppressorMap(
+  sf: ts.SourceFile,
+  resolvedHosts: ReadonlyMap<string, ResolvedHost> = new Map(),
+): SuppressorMap {
+  const out = new Map<number, Set<SuppressorName>>();
+  const imports = collectLocalImports(sf);
+
+  const add = (line: number, name: SuppressorName): void => {
+    let set = out.get(line);
+    if (set === undefined) {
+      set = new Set<SuppressorName>();
+      out.set(line, set);
+    }
+    set.add(name);
+  };
+
+  walkAncestorSuppressors(sf, ({ opening, line, flags }) => {
+    // Ancestor suppressors: live if an ENCLOSING container set the depth.
+    if (flags.hasLabelAncestor) add(line, "label-ancestor");
+    if (flags.hasNameAncestor) add(line, "name-injecting-wrapper");
+    // Element-local suppressors read straight off the opening.
+    if (isHiddenOrUntabbable(opening, sf)) add(line, "hidden-untabbable");
+
+    const resolved = resolvedHostOf(opening, imports, resolvedHosts);
+    // `type`-exemption is only meaningful for a real form control — a form
+    // intrinsic, OR a component enforce RESOLVES to an `input` host. Enforce runs
+    // `isNameExemptInputType` only there; a capitalized non-input component is
+    // NEVER marked (the prior over-broad `tag === null` gate was finding #3).
+    const tag = intrinsicTag(opening);
+    const isFormIntrinsic = tag === "input" || tag === "select" || tag === "textarea";
+    // enforce treats input/select/textarea hosts all as ControlType "input" (its
+    // HOST_TO_TYPE), so mirror the full set, not just "input", to provably match.
+    const isInputHost =
+      resolved !== null &&
+      (resolved.host === "input" || resolved.host === "select" || resolved.host === "textarea");
+    if ((isFormIntrinsic || isInputHost) && isNameExemptInputType(opening, sf)) {
+      add(line, "name-exempt-input-type");
+    }
+
+    // Toggle: a call-site `role="checkbox|switch|radio"`, OR a resolved host
+    // whose role is a toggle (Radix Checkbox → button[role=checkbox]) — the same
+    // skip enforce performs via `isToggleRole(resolved.role)`.
+    if (hasToggleRole(opening, sf) || (resolved !== null && isToggleRole(resolved.role))) {
+      add(line, "toggle-role");
+    }
+    // A wrapper that renders its host an internal STATIC name is named even when
+    // the call site looks empty — enforce skips it (`resolved.rendersOwnName`).
+    if (resolved !== null && resolved.rendersOwnName) add(line, "renders-own-name");
+  });
+
+  return out;
+}

package/src/suppressors.ts

@@ -0,0 +1,284 @@
+import ts from "typescript";
+
+/**
+ * The static floor's shared SUPPRESSOR predicates.
+ *
+ * Per ADR 0003 ("A Deterministic Shell Around Every Stochastic Capability"),
+ * the static floor's suppressors live in their own module so a later phase can
+ * reuse them, unchanged, as a precision PRE-FILTER on a corpus-grounded recall
+ * layer. Each predicate answers a single "uncertain → skip" question about one
+ * JSX element (is its `type` exempt? is it hidden? is it a label/name-injecting
+ * container?), built on the small name-reading primitives below
+ * ({@link attrState}, {@link anyNameAttr}). Keep these FN-safe and side-effect
+ * free: a recall layer composes them, so any behavior drift here ripples.
+ */
+
+/** Native `<input>` `type` values that exempt it from the name check. submit /
+ * button / reset are named by their `value`; hidden / image are not text-name-
+ * bearing (an image input's name is alt's job); checkbox / radio are externally
+ * labelled toggles, skipped exactly as {@link TOGGLE_NAMES} are. A DYNAMIC
+ * `type={x}` is unknowable, so — uncertain → skip — it is exempt too. A MISSING
+ * `type` defaults to `"text"` and is NOT exempt: a bare text input must be named.
+ */
+const NAME_EXEMPT_INPUT_TYPES: ReadonlySet<string> = new Set([
+  "hidden",
+  "submit",
+  "button",
+  "reset",
+  "image",
+  "checkbox",
+  "radio",
+]);
+
+/** The accessible-name attributes that, if present/dynamic, satisfy a control. */
+export const LABEL_ATTRS = ["aria-label", "aria-labelledby"] as const;
+
+/**
+ * Whether `attr` is present AND carries a NON-EMPTY value we can read statically.
+ * A dynamic expression (`aria-label={x}`) counts as present-and-unknowable, so
+ * we treat it as "could be a name" — conservatism: never flag when uncertain.
+ * Returns `"missing" | "present" | "dynamic"`.
+ */
+export type AttrState = "missing" | "present" | "dynamic";
+
+export function attrState(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+  attrName: string,
+): AttrState {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    if (attr.name.getText(sf) !== attrName) continue;
+    const init = attr.initializer;
+    // Bare attribute (`hidden`) — present, treated as a (truthy) value.
+    if (init === undefined) return "present";
+    if (ts.isStringLiteral(init)) return init.text.trim() === "" ? "missing" : "present";
+    if (ts.isJsxExpression(init)) {
+      const expr = init.expression;
+      if (expr === undefined) return "missing"; // `aria-label={}`
+      if (ts.isStringLiteral(expr)) return expr.text.trim() === "" ? "missing" : "present";
+      // Any other expression is dynamic/computed — unknowable, so "could name it".
+      return "dynamic";
+    }
+    return "dynamic";
+  }
+  return "missing";
+}
+
+/** Whether ANY of the named attributes resolves a name (present or dynamic). */
+export function anyNameAttr(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+  names: readonly string[],
+): boolean {
+  return names.some((n) => attrState(opening, sf, n) !== "missing");
+}
+
+/**
+ * Whether an input's `type` exempts it from the name check (see
+ * {@link NAME_EXEMPT_INPUT_TYPES}). A static exempt value or a dynamic
+ * `type={x}` (unknowable → skip) exempts; a missing or non-exempt static `type`
+ * does not. Only meaningful for inputs — `<select>`/`<textarea>` carry no `type`,
+ * so this is always `false` for them (they are always checked).
+ */
+export function isNameExemptInputType(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): boolean {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr) || attr.name.getText(sf) !== "type") continue;
+    const init = attr.initializer;
+    if (init === undefined) return false; // bare `type` — degenerate, treat as text
+    if (ts.isStringLiteral(init)) return NAME_EXEMPT_INPUT_TYPES.has(init.text.trim().toLowerCase());
+    if (ts.isJsxExpression(init)) {
+      const expr = init.expression;
+      if (expr !== undefined && ts.isStringLiteral(expr)) {
+        return NAME_EXEMPT_INPUT_TYPES.has(expr.text.trim().toLowerCase());
+      }
+      return true; // `type={x}` — unknowable, exempt (uncertain → skip)
+    }
+    return true;
+  }
+  return false; // no `type` → defaults to "text" → checked
+}
+
+/**
+ * Whether a control is statically HIDDEN or removed from the tab order, so an
+ * absent label is not a real finding (uncertain → skip, FN-safe):
+ *   - `tabIndex={-1}` / `tabIndex="-1"` — not keyboard-reachable in normal flow;
+ *     in practice a hidden sentinel (react-select's required-field `<input>`) or
+ *     a programmatically-focused target, externally driven, not a typed control;
+ *   - the HTML `hidden` attribute (bare or `={true}`) — not rendered;
+ *   - a `display:none` utility class (the standalone `hidden` token, Tailwind &
+ *     co.) — removed from the accessibility tree, so it is never announced.
+ * This mirrors the wide-sample false positives the native-control path would
+ * otherwise produce (~7%): all six were one of these three shapes.
+ */
+export function isHiddenOrUntabbable(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): boolean {
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    const name = attr.name.getText(sf);
+    const init = attr.initializer;
+    if (name === "hidden") {
+      if (init === undefined) return true; // bare `hidden`
+      if (ts.isJsxExpression(init) && init.expression?.kind === ts.SyntaxKind.TrueKeyword) return true;
+      continue;
+    }
+    if (name === "tabIndex" && init !== undefined) {
+      if (init.getText(sf).replace(/[{}"'\s]/g, "") === "-1") return true;
+      continue;
+    }
+    if (name === "className" || name === "class") {
+      let str: string | null = null;
+      if (init !== undefined && ts.isStringLiteral(init)) str = init.text;
+      else if (init !== undefined && ts.isJsxExpression(init) && init.expression !== undefined && ts.isStringLiteral(init.expression)) {
+        str = init.expression.text;
+      }
+      if (str !== null && /(^|\s)hidden(\s|$)/.test(str)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a JSX element is (or renders) a LABEL container — so an input nested
+ * under it likely gets its name from that label and must NOT be flagged:
+ *
+ *   - intrinsic `<label>`;
+ *   - `<X as="label">` / `<X component="label">` (Saleor `Box as="label"`, MUI);
+ *   - a component whose leaf name ends with `Label` (`FormLabel`, `InputLabel`);
+ *   - a form-field grouping (`FormItem`/`FormControl`/`FormField`/`FormGroup`)
+ *     — the react-hook-form / shadcn / MUI convention that pairs a label with
+ *     the control it wraps. Recognizing the GROUP is conservative: it suppresses
+ *     even when the label sibling is rendered conditionally or further out.
+ */
+export function isLabelContainer(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): boolean {
+  const tag = opening.tagName;
+  if (ts.isIdentifier(tag) && tag.text === "label") return true;
+  // `as`/`component` polymorphic prop set to the string "label".
+  for (const attr of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    const n = attr.name.getText(sf);
+    if (n !== "as" && n !== "component") continue;
+    const init = attr.initializer;
+    if (init !== undefined && ts.isStringLiteral(init) && init.text === "label") return true;
+    if (
+      init !== undefined &&
+      ts.isJsxExpression(init) &&
+      init.expression !== undefined &&
+      ts.isStringLiteral(init.expression) &&
+      init.expression.text === "label"
+    ) {
+      return true;
+    }
+  }
+  const leaf = ts.isPropertyAccessExpression(tag)
+    ? tag.name.text
+    : ts.isIdentifier(tag)
+      ? tag.text
+      : "";
+  if (leaf.endsWith("Label")) return true;
+  return /^(Form(Item|Control|Field|Group)|Field)$/.test(leaf);
+}
+
+/**
+ * Whether an element is a NAME-INJECTING wrapper for its single child control: a
+ * design-system `<Tooltip>` carrying a `title` (or `aria-label`). MUI / antd /
+ * Mantine Tooltips clone their child and set the `title` as the child's
+ * `aria-label` by default (MUI: `describeChild=false` ⇒ "the title acts as an
+ * accessible label for the child"). So a nested icon-only `<IconButton>` /
+ * `<Button>` / `<Link>` is NAMED at runtime even though the call site shows no
+ * `aria-label` — the actionable-control analogue of an input under a `<label>`.
+ *
+ * Matched on the LEAF name `Tooltip` (so `Tooltip`, `MyTooltip`, `Tooltip.Root`
+ * all qualify) AND only when a `title`/`aria-label` is actually present — a
+ * Tooltip with no title injects no name, so it must not suppress. A bare
+ * `describeChild` Tooltip (title → description, not name) is the rare opposite;
+ * we accept the small false-negative risk there in exchange for killing the
+ * dominant, idiomatic titled-Tooltip false positive.
+ */
+export function isNameInjectingWrapper(
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement,
+  sf: ts.SourceFile,
+): boolean {
+  const tag = opening.tagName;
+  const leaf = ts.isPropertyAccessExpression(tag)
+    ? tag.name.text
+    : ts.isIdentifier(tag)
+      ? tag.text
+      : "";
+  if (!leaf.endsWith("Tooltip")) return false;
+  // The title must actually be there to inject a name (present or dynamic).
+  return attrState(opening, sf, "title") !== "missing" || anyNameAttr(opening, sf, LABEL_ATTRS);
+}
+
+/** The enclosing-ancestor suppressor state at one JSX element (see {@link walkAncestorSuppressors}). */
+export interface AncestorFlags {
+  /** An enclosing `<label>` / form-field grouping (`isLabelContainer`) is an ancestor. */
+  readonly hasLabelAncestor: boolean;
+  /** An enclosing titled `<Tooltip>` (`isNameInjectingWrapper`) is an ancestor. */
+  readonly hasNameAncestor: boolean;
+}
+
+/** The per-element callback driven by {@link walkAncestorSuppressors}. */
+export type AncestorVisitor = (args: {
+  readonly node: ts.JsxElement | ts.JsxSelfClosingElement;
+  readonly opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement;
+  /** 1-based opening-tag line — the same line a finding/abstention anchors to. */
+  readonly line: number;
+  /** Whether a label / name-injecting CONTAINER ENCLOSES this element (not itself). */
+  readonly flags: AncestorFlags;
+}) => void;
+
+/**
+ * The ONE ancestor-suppressor tree walk, shared by `enforceContent` and
+ * `buildSuppressorMap` so they cannot drift (the two used to keep divergent
+ * copies of this `labelDepth` / `nameAncestorDepth` descent). It pushes a depth
+ * counter as a label container (`isLabelContainer`) or a name-injecting wrapper
+ * (`isNameInjectingWrapper`) is entered and pops it on exit, so every descendant
+ * element learns it is UNDER one — the container element itself does NOT count as
+ * its own ancestor. For each JSX element it invokes `visitor` with the element,
+ * its opening, its 1-based line, and the enclosing-ancestor {@link AncestorFlags}.
+ */
+export function walkAncestorSuppressors(sf: ts.SourceFile, visitor: AncestorVisitor): void {
+  let labelDepth = 0;
+  let nameAncestorDepth = 0;
+
+  const visit = (node: ts.Node): void => {
+    let enteredLabel = false;
+    let enteredNameAncestor = false;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      if (isLabelContainer(opening, sf)) {
+        labelDepth++;
+        enteredLabel = true;
+      }
+      if (isNameInjectingWrapper(opening, sf)) {
+        nameAncestorDepth++;
+        enteredNameAncestor = true;
+      }
+      const line = sf.getLineAndCharacterOfPosition(opening.getStart(sf)).line + 1;
+      // The element opening a container is not its OWN ancestor — only its
+      // descendants are — so subtract the entry just made for this element.
+      visitor({
+        node,
+        opening,
+        line,
+        flags: {
+          hasLabelAncestor: labelDepth - (enteredLabel ? 1 : 0) > 0,
+          hasNameAncestor: nameAncestorDepth - (enteredNameAncestor ? 1 : 0) > 0,
+        },
+      });
+    }
+    ts.forEachChild(node, visit);
+    if (enteredLabel) labelDepth--;
+    if (enteredNameAncestor) nameAncestorDepth--;
+  };
+  visit(sf);
+}

package/src/tsconfig-aliases.ts

@@ -0,0 +1,155 @@
+/**
+ * tsconfig path-alias reader: tell whether an import specifier is the repo's
+ * OWN code reached through a `compilerOptions.paths` alias, rather than a
+ * third-party design system.
+ *
+ * Why this exists. Design-system detection ranks the package that contributes
+ * the most host-resolving wrappers. A repo that imports its OWN UI through a
+ * project alias — Saleor `@dashboard/* -> src/*`, Cal.com `@coss/ui/* ->
+ * ../../packages/coss-ui/src/*` — looks like a published `@scope/pkg` to the
+ * naive `isOwnModule` check, so the alias wins the ranking over the real
+ * third-party library. Semantically an alias that maps INTO the repo's own
+ * source is not a design system; it is the team's own components.
+ *
+ * The signal is the alias TARGET: a target that is a relative path (`src/*`,
+ * `../../packages/.../src/*`) points at source the team controls. A target that
+ * is itself a bare package name (`@scope/pkg/*`, `node_modules/...`) is a
+ * re-pointer to an external dependency and is left alone. We resolve `extends`
+ * chains (bounded) and honor `baseUrl`, exactly as the customer's own build
+ * does — never a hardcoded per-repo list.
+ *
+ * Everything is best-effort + boundary-parsed: a missing/malformed tsconfig, an
+ * unresolvable `extends`, or a target we can't classify all degrade to "not an
+ * own-alias" — the caller then treats the import as a candidate design system,
+ * the pre-existing behavior.
+ */
+
+import { dirname, resolve, sep } from "node:path";
+import ts from "typescript";
+
+/** A compiled alias: the literal prefix of a `paths` key (before any `*`). */
+interface AliasPrefix {
+  /** The key text up to the `*` (e.g. `@dashboard/`, `@coss/ui/`), or the whole key when no `*`. */
+  readonly prefix: string;
+  /** Whether the key had a trailing `*` (so it matches by prefix, not exactly). */
+  readonly wildcard: boolean;
+}
+
+/** A repo's own-alias matcher, derived once per tsconfig directory. */
+export interface OwnAliasMatcher {
+  /** True iff `specifier` is reached through an alias that maps into own source. */
+  readonly isOwnAlias: (specifier: string) => boolean;
+}
+
+const NEVER: OwnAliasMatcher = { isOwnAlias: () => false };
+
+const matcherCache = new Map<string, OwnAliasMatcher>();
+
+/** Find the nearest `tsconfig.json` at or above `dir`, or `null`. */
+function findTsconfig(dir: string): string | null {
+  return ts.findConfigFile(dir, ts.sys.fileExists, "tsconfig.json") ?? null;
+}
+
+/**
+ * The effective `{ baseUrl, paths }` for a tsconfig, with its `extends` chain
+ * already merged. We let TypeScript itself parse the file — it handles JSONC
+ * (comments, trailing commas), resolves `extends` (including shared-config
+ * packages under `node_modules`), and merges `paths`/`baseUrl` exactly as the
+ * customer's build does. A hand-rolled JSON stripper would diverge from real TS
+ * resolution; reusing the compiler API is the in-stack primitive. Returns
+ * `null` when the file can't be read/parsed at all.
+ */
+interface EffectivePaths {
+  /** Absolute dir the `paths` targets resolve against (baseUrl, else config dir). */
+  readonly baseDir: string;
+  /** The merged `paths` map (alias key -> target strings). */
+  readonly paths: Readonly<Record<string, readonly string[]>>;
+}
+
+function readEffectivePaths(configPath: string): EffectivePaths | null {
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.config === undefined || read.config === null) return null;
+  const configDir = dirname(configPath);
+  // parseJsonConfigFileContent follows `extends` and merges compilerOptions.
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, configDir);
+  const opts = parsed.options;
+  // baseUrl is resolved to an absolute path by the parser; `paths` keys/targets
+  // are relative to it (TS semantics). When no baseUrl is set TS still resolves
+  // `paths` against the config dir, so fall back to that.
+  const baseDir = typeof opts.baseUrl === "string" ? opts.baseUrl : configDir;
+  const paths: Record<string, readonly string[]> = {};
+  if (opts.paths !== undefined) {
+    for (const [key, targets] of Object.entries(opts.paths)) {
+      if (Array.isArray(targets)) {
+        paths[key] = targets.filter((t): t is string => typeof t === "string");
+      }
+    }
+  }
+  return { baseDir, paths };
+}
+
+/**
+ * Whether an alias TARGET points into the repo's own source. A relative path
+ * (`src/*`, `../../packages/x/src/*`) is own source; a target that itself
+ * begins with a bare package name or a `node_modules/` segment is a re-pointer
+ * to an external dependency, not own code. The target is resolved against
+ * `baseDir` and rejected if it climbs into a `node_modules` directory.
+ */
+function targetIsOwnSource(target: string, baseDir: string): boolean {
+  // Strip the trailing `/*` (or `*`) wildcard for classification.
+  const cleaned = target.replace(/\*+$/, "").replace(/\/$/, "");
+  // A target that routes through node_modules is an external re-point.
+  if (cleaned.includes("node_modules")) return false;
+  const abs = resolve(baseDir, cleaned);
+  return !`${abs}${sep}`.includes(`${sep}node_modules${sep}`);
+}
+
+/** Compile a `paths` key into its literal prefix + wildcard flag. */
+function compileAliasKey(key: string): AliasPrefix {
+  const star = key.indexOf("*");
+  if (star === -1) return { prefix: key, wildcard: false };
+  return { prefix: key.slice(0, star), wildcard: true };
+}
+
+/**
+ * Build the own-alias matcher for the tsconfig governing `fromDir`. Cached per
+ * directory so each repo's config is parsed once. Returns a matcher that always
+ * answers `false` when there is no usable tsconfig — the caller then keeps its
+ * pre-existing own-code heuristics.
+ */
+export function ownAliasMatcherFor(fromDir: string): OwnAliasMatcher {
+  const cached = matcherCache.get(fromDir);
+  if (cached !== undefined) return cached;
+
+  const configPath = findTsconfig(fromDir);
+  if (configPath === null) {
+    matcherCache.set(fromDir, NEVER);
+    return NEVER;
+  }
+  const effective = readEffectivePaths(configPath);
+  if (effective === null) {
+    matcherCache.set(fromDir, NEVER);
+    return NEVER;
+  }
+
+  // Keep only the aliases whose target maps into own source — those are the
+  // ones that must be excluded from design-system ranking.
+  const ownPrefixes: AliasPrefix[] = [];
+  for (const [key, targets] of Object.entries(effective.paths)) {
+    if (targets.some((t) => targetIsOwnSource(t, effective.baseDir))) {
+      ownPrefixes.push(compileAliasKey(key));
+    }
+  }
+
+  const isOwnAlias = (specifier: string): boolean =>
+    ownPrefixes.some((p) => (p.wildcard ? specifier.startsWith(p.prefix) : specifier === p.prefix));
+
+  const matcher: OwnAliasMatcher = { isOwnAlias };
+  matcherCache.set(fromDir, matcher);
+  return matcher;
+}
+
+/** Reset the matcher cache — test-only, so fixtures don't bleed across cases. */
+export function __resetAliasCacheForTest(): void {
+  matcherCache.clear();
+}