ultra11y 2.22.0

package/src/gh.ts

@@ -0,0 +1,214 @@
+// Optional GitHub issue creation for `prd --gh-issues`. Shells out to the `gh`
+// CLI (which handles its own auth) — NO npm dependency, no tokens in ultra11y.
+// Everything is best-effort: if gh is absent/unauthenticated, the caller still
+// wrote the markdown and we just report that issues were skipped. De-dupes by
+// issue title so re-running never creates duplicates.
+import { execFileSync } from "node:child_process";
+import type { Lang, Severity } from "./types.js";
+import type { PrdUnit } from "./prd.js";
+import { type StandardId, isCore, loadPack } from "./standards/index.js";
+import { renderAuditorUnit } from "./auditor.js";
+import { resolveMessage, resolveRemediation } from "./messages.js";
+
+// Issue-body shape: `audit` (DEFAULT) = the auditor conformance block; `remediation` = the
+// legacy dev body (WCAG refs / Fix / Occurrences). Mirrors `prd --format`.
+export type IssueFormat = "audit" | "remediation";
+
+const SEV_ORDER: Severity[] = ["bloquant", "majeur", "mineur"];
+const SEV_RANK: Record<Severity, number> = { bloquant: 0, majeur: 1, mineur: 2 };
+const ICON: Record<Severity, string> = { bloquant: "🔴", majeur: "🟠", mineur: "🟡" };
+const SEV_LABEL: Record<Lang, Record<Severity, string>> = {
+  fr: { bloquant: "Bloquant", majeur: "Majeur", mineur: "Mineur" },
+  en: { bloquant: "Blocking", majeur: "Major", mineur: "Minor" },
+};
+
+/** Display label + issue tag for the active standard ("WCAG"/"wcag" or a pack's). */
+function standardTag(standard: StandardId): { label: string; tag: string } {
+  return isCore(standard)
+    ? { label: "WCAG", tag: "wcag" }
+    : (() => {
+        const p = loadPack(standard);
+        return { label: p.name, tag: p.key };
+      })();
+}
+
+function gh(args: string[], input?: string): string {
+  // Capture stderr (pipe, not ignore) so a failed `gh` call carries a surfaceable reason
+  // on the thrown error instead of vanishing.
+  return execFileSync("gh", args, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], ...(input !== undefined ? { input } : {}) });
+}
+
+/** Extract a concise, single-line failure reason from a thrown `gh` error — the first
+ *  meaningful stderr line (where `gh` prints the API/auth error), else the error message. */
+function ghErrorReason(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const e = err as { stderr?: unknown; message?: unknown };
+  const stderr = typeof e.stderr === "string" ? e.stderr : Buffer.isBuffer(e.stderr) ? e.stderr.toString("utf8") : "";
+  const line = stderr
+    .split("\n")
+    .map((l) => l.trim())
+    .find(Boolean);
+  if (line) return line;
+  if (typeof e.message === "string" && e.message) return e.message.split("\n")[0]!.trim() || undefined;
+  return undefined;
+}
+
+/** Is the `gh` CLI installed AND authenticated here? */
+export function ghAvailable(): boolean {
+  try {
+    execFileSync("gh", ["auth", "status"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Stable, language-neutral suffix marking a non-normative recommendation issue apart
+// from a non-conformity one. Part of the de-dupe grain, so it must never drift.
+export const RECOMMENDATION_SUFFIX = " (recommendation)";
+
+/** One issue per criterion (stable de-dupe grain, regardless of --split). The label
+ *  is the active standard ("WCAG" for the core, else the pack name e.g. "RGAA"). An
+ *  advisory unit gets a stable suffix so its issue is never confused with an NC one. */
+export function issueTitle(unit: PrdUnit, label = "WCAG"): string {
+  return `[a11y] ${label} ${unit.criteriaId} — ${unit.title}${unit.advisory ? RECOMMENDATION_SUFFIX : ""}`;
+}
+
+/** Titles of all existing issues (open + closed), for de-duplication. Empty on any failure. */
+export function existingIssueTitles(): Set<string> {
+  try {
+    const raw = gh(["issue", "list", "--state", "all", "--limit", "1000", "--json", "title"]);
+    const arr = JSON.parse(raw) as Array<{ title?: string }>;
+    return new Set(arr.map((i) => i.title ?? "").filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+export function issueBody(unit: PrdUnit, lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): string {
+  if (format === "audit") return renderAuditorUnit(unit, standard, lang).join("\n").trimEnd();
+  const t = lang === "fr" ? { fix: "Correction", occ: "Occurrence(s)", def: "↳ définition" } : { fix: "Fix", occ: "Occurrence(s)", def: "↳ definition" };
+  const lines: string[] = [];
+  if (unit.refs.length) lines.push(`**WCAG** : ${unit.refs.join(", ")}`, "");
+  for (const fx of [...new Set(unit.findings.map((f) => resolveRemediation(f, lang)))]) lines.push(`**${t.fix}** : ${fx}`);
+  lines.push("", `**${t.occ} (${unit.findings.length})**`, "");
+  for (const f of unit.findings) {
+    lines.push(`- [ ] \`${f.file}:${f.line}\` (\`${f.selectorHint}\`) — ${resolveMessage(f, lang)}`);
+    if (f.related) lines.push(`  - ${t.def} : \`${f.related.file}:${f.related.line}\` (\`${f.related.selectorHint}\`)`);
+  }
+  return lines.join("\n");
+}
+
+export interface CreateResult {
+  ok: boolean;
+  /** Concise `gh` stderr reason when the creation failed (both attempts). */
+  reason?: string;
+}
+
+/** Create one issue. Retries without labels if the labelled call fails (labels may
+ *  not exist in the repo). On failure, carries `gh`'s stderr reason so the caller can
+ *  surface WHY it failed instead of silently swallowing it. */
+export function createIssue(title: string, body: string, labels: string[]): CreateResult {
+  const base = ["issue", "create", "--title", title, "--body-file", "-"];
+  try {
+    gh([...base, "--label", labels.join(",")], body);
+    return { ok: true };
+  } catch (labelledErr) {
+    try {
+      gh(base, body);
+      return { ok: true };
+    } catch (err) {
+      // Prefer the un-labelled attempt's reason (the real one); fall back to the labelled one.
+      return { ok: false, reason: ghErrorReason(err) ?? ghErrorReason(labelledErr) };
+    }
+  }
+}
+
+export interface PushResult {
+  created: number;
+  skipped: number; // already existed (by title)
+  failed: number;
+  createdTitles: string[];
+  /** Concise, de-duplicated `gh` failure reasons (empty when nothing failed). */
+  errors: string[];
+}
+
+/** Record a creation failure, keeping distinct `gh` reasons (deduped) for surfacing. */
+function recordFailure(result: PushResult, reason?: string): void {
+  result.failed++;
+  if (reason && !result.errors.includes(reason)) result.errors.push(reason);
+}
+
+/** Create a GitHub issue per unit, skipping titles that already exist. */
+export function pushIssues(units: PrdUnit[], lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): PushResult {
+  const { label, tag } = standardTag(standard);
+  const existing = existingIssueTitles();
+  const result: PushResult = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
+  for (const u of units) {
+    const title = issueTitle(u, label);
+    if (existing.has(title)) {
+      result.skipped++;
+      continue;
+    }
+    // Advisory units get the `recommendation` label so they can be triaged apart from
+    // real non-conformities (which they are not).
+    const labels = u.advisory ? ["accessibility", tag, "recommendation", u.severity] : ["accessibility", tag, u.severity];
+    const r = createIssue(title, issueBody(u, lang, standard, format), labels);
+    if (r.ok) {
+      result.created++;
+      result.createdTitles.push(title);
+      existing.add(title); // guard against duplicate units in one run
+    } else {
+      recordFailure(result, r.reason);
+    }
+  }
+  return result;
+}
+
+/** Stable title for the single consolidated audit issue. No counts/date so re-runs de-dupe. */
+export function singleIssueTitle(label = "WCAG"): string {
+  return `[a11y] ${label} — Accessibility audit`;
+}
+
+/** One consolidated issue body: every criterion, sectioned by severity (blocking → minor),
+ *  each criterion reusing the same fix + occurrences block as the per-criterion issues. */
+export function singleIssueBody(units: PrdUnit[], lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): string {
+  const { label } = standardTag(standard);
+  const intro =
+    lang === "fr"
+      ? `Audit d'accessibilité ${label} — ${units.length} critère(s) non conforme(s).`
+      : `${label} accessibility audit — ${units.length} non-conforming criteria.`;
+  const lines: string[] = [intro, ""];
+  for (const sev of SEV_ORDER) {
+    const group = units.filter((u) => u.severity === sev);
+    if (!group.length) continue;
+    lines.push(`## ${ICON[sev]} ${SEV_LABEL[lang][sev]} (${group.length})`, "");
+    for (const u of group) {
+      if (format === "audit") lines.push(...renderAuditorUnit(u, standard, lang, { heading: "###" }));
+      else lines.push(`### ${u.label}`, "", issueBody(u, lang, standard, format), "");
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Create ONE consolidated issue for the whole audit, de-duped by its stable title and
+ *  labelled by the most severe criterion. Mirrors pushIssues' best-effort/skip semantics. */
+export function pushSingleIssue(units: PrdUnit[], lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): PushResult {
+  const { label, tag } = standardTag(standard);
+  const result: PushResult = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
+  if (!units.length) return result;
+  const title = singleIssueTitle(label);
+  if (existingIssueTitles().has(title)) {
+    result.skipped = 1;
+    return result;
+  }
+  const severity = [...units].sort((a, b) => SEV_RANK[a.severity] - SEV_RANK[b.severity])[0]!.severity;
+  const r = createIssue(title, singleIssueBody(units, lang, standard, format), ["accessibility", tag, severity]);
+  if (r.ok) {
+    result.created = 1;
+    result.createdTitles.push(title);
+  } else {
+    recordFailure(result, r.reason);
+  }
+  return result;
+}

package/src/glob.ts

@@ -0,0 +1,206 @@
+// Zero-dependency input expansion for `audit`: turn file paths, directories and
+// globs into a concrete file list, then apply --include/--exclude predicates.
+// The generic machinery (directory walking, glob → RegExp) is the vendored
+// codeindex engine's; everything ultra11y-specific (markup extension allowlist,
+// test-artifact policy, audit-output skips, input-scope matching) stays here.
+import { existsSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+import { ext } from "./util.js";
+import { compileGlobs as engineCompileGlobs, walk as engineWalk } from "./vendor/codeindex-engine.mjs";
+
+// HTML + JSX/TSX + the HTML-shaped single-file component formats (Vue/Svelte/Astro
+// templates parse cleanly through the HTML path). Server templates (.twig/.erb/.hbs/
+// .liquid/.njk…) are opt-in via `--ext` since their extensions are ambiguous.
+const DEFAULT_EXT = new Set([".html", ".htm", ".xhtml", ".jsx", ".tsx", ".vue", ".svelte", ".astro"]);
+
+// GRAPH-ONLY extensions: plain TS/JS modules are never markup, so they never enter
+// the AUDIT allowlist above (`DEFAULT_EXT`) — but a barrel (`components/index.ts`
+// re-exporting `.tsx` components) or a plain-JS component definition is real
+// cross-file structure the dependency graph (`audit --graph`) needs to resolve
+// imports/re-exports/definitions through. Fed to `discover`'s `ext` for the graph's
+// OWN file discovery pass only (see `runAudit`'s graph branch in src/audit.ts) —
+// these files are parsed for their imports/exports and never run through the rule
+// engine themselves.
+export const GRAPH_ONLY_EXT = [".ts", ".js", ".mjs", ".cjs"];
+
+/** Normalise extensions (`twig` → `.twig`, lowercased) into a lookup set merged
+ *  with the built-in defaults. */
+function extSet(extra: string[] | undefined): Set<string> {
+  const set = new Set(DEFAULT_EXT);
+  for (const raw of extra ?? []) {
+    for (const e of raw.split(",")) {
+      const t = e.trim().toLowerCase();
+      if (t) set.add(t.startsWith(".") ? t : `.${t}`);
+    }
+  }
+  return set;
+}
+// Directories the engine's walk does not know about but ultra11y must never
+// auto-walk: `audits/` holds generated reports, and `.ultra11y/` (captures +
+// generated setup) is ingested only via the explicit `.ultra11y/captures` input
+// the CLI appends (so `--no-captures` genuinely opts out) or a direct
+// `--captures <dir>` / coverage scan of that dir. Like the old SKIP_DIR, these
+// prune DESCENDANTS of a walked root — naming such a dir directly as the walk
+// root still descends into it. The rest of the old SKIP_DIR (node_modules,
+// .git, dist, build, coverage, .next, out) is covered by the engine's own
+// ignore universe (a superset), and the engine walk additionally honours
+// .gitignore files under the walked root.
+const SKIP_DIR = new Set(["audits", ".ultra11y"]);
+
+// Test / spec / story / mock markup is bad-by-design (intentionally non-conformant
+// fixtures, never shipped UI). Excluded by default to keep the audit focused on real
+// product code; re-admit by naming the file/dir directly, with an `--include` glob, or
+// `--no-default-excludes`. NOT in SKIP_DIR (which prunes the walk unconditionally) so
+// the opt-outs can still reach these files.
+const TEST_DIR = new Set(["__tests__", "__mocks__", ".storybook"]);
+const TEST_FILE = /\.(test|spec|stories|story|cy)\.[^./]+$/i;
+export function isTestArtifact(rel: string): boolean {
+  if (TEST_FILE.test(rel)) return true;
+  return rel.split("/").some((seg) => TEST_DIR.has(seg));
+}
+
+// Glob matching is the engine's (same dialect as before: `**` crosses `/`,
+// `**/` makes the segment optional, `*` runs within a segment, `?` is one
+// non-`/` char). ultra11y's flag semantics on top: each --include/--exclude
+// value may carry a comma-separated LIST of globs, split and trimmed here.
+export function compileGlobs(globs: string[] | undefined): ((rel: string) => boolean) | null {
+  if (!globs || globs.length === 0) return null;
+  const list = globs
+    .flatMap((g) => g.split(","))
+    .map((g) => g.trim())
+    .filter(Boolean);
+  // A non-empty flag that splits to nothing (e.g. ",") historically compiled to
+  // a match-nothing predicate — keep that, never silently widen to "no filter".
+  return engineCompileGlobs(list) ?? (() => false);
+}
+
+export const toPosix = (p: string): string => p.split(sep).join("/");
+export const hasGlob = (s: string): boolean => /[*?]/.test(s);
+
+/** A reusable file predicate (extension + include/exclude) for callers that
+ *  already have a file list (e.g. git-changed discovery) and skip the walk. */
+export function makeFilter(opts: ExpandOpts = {}): (file: string) => boolean {
+  const include = compileGlobs(opts.include);
+  const exclude = compileGlobs(opts.exclude);
+  const exts = extSet(opts.ext);
+  return (file: string): boolean => {
+    if (!exts.has(ext(file))) return false;
+    const rel = toPosix(file);
+    if (include && !include(rel)) return false;
+    if (exclude?.(rel)) return false;
+    // Default test-artifact exclusion (re-admitted by an explicit --include match).
+    if (!opts.noDefaultExcludes && isTestArtifact(rel) && !(include && include(rel))) return false;
+    return true;
+  };
+}
+
+/** Match a file against explicit input scopes (globs OR directory prefixes).
+ *  Used by `--changed` to keep only git-changed files inside the audited scope.
+ *  Returns null when inputs impose no scope (only "." / "-"). */
+export function inScopeMatcher(inputs: string[]): ((file: string) => boolean) | null {
+  const scopes = inputs.filter((i) => i !== "-" && i !== ".");
+  if (!scopes.length) return null;
+  const globMatch = compileGlobs(scopes.filter(hasGlob));
+  const prefixes = scopes.filter((i) => !hasGlob(i)).map((p) => toPosix(p).replace(/\/+$/, ""));
+  return (file: string): boolean => {
+    const rel = toPosix(file);
+    if (globMatch?.(rel)) return true;
+    return prefixes.some((p) => rel === p || rel.startsWith(`${p}/`));
+  };
+}
+
+// Walk a directory with the engine (gitignore honoured, dependency/build/VCS
+// dirs, lockfiles, binaries and >1 MiB files skipped), returning full paths the
+// way the old recursive walker did (the input dir joined back onto each hit).
+// No maxFiles cap here: the audit's own --max-files budget applies downstream,
+// and a silent walk truncation must never masquerade as a clean "0 findings".
+function walk(dir: string, acc: string[]): void {
+  for (const f of engineWalk(dir, { maxFiles: Number.MAX_SAFE_INTEGER }).files) {
+    // Engine rel paths are posix; prune ultra11y's own output dirs at any depth
+    // below the walked root (the root itself may be named directly, as before).
+    if (f.rel.split("/").some((seg) => SKIP_DIR.has(seg))) continue;
+    acc.push(join(dir, f.rel));
+  }
+}
+
+function staticBase(glob: string): string {
+  const idx = glob.search(/[*?]/);
+  const head = idx === -1 ? glob : glob.slice(0, idx);
+  const slash = head.lastIndexOf("/");
+  return slash === -1 ? "." : head.slice(0, slash) || ".";
+}
+
+export interface ExpandOpts {
+  include?: string[];
+  exclude?: string[];
+  ext?: string[];
+  noDefaultExcludes?: boolean; // audit test/spec/story/__tests__ markup too
+  onWarn?: (msg: string) => void;
+  // Memo of directory walks, shared by the calls that expand the SAME inputs with a
+  // different extension allowlist — `audit --graph` discovers twice (markup, then
+  // markup + .ts/.js for the dependency graph) and the tree walk is identical both
+  // times because the extension filter is applied AFTER it. Caller-owned and
+  // per-run on purpose: a module-level cache would go stale across audits (a
+  // `fix --iterate` re-audit must always see the current tree).
+  walkCache?: Map<string, string[]>;
+}
+
+/** Walk `dir` once per ExpandOpts.walkCache. Without a cache, walks every time. */
+function walkCached(dir: string, opts: ExpandOpts): string[] {
+  const hit = opts.walkCache?.get(dir);
+  if (hit) return hit;
+  const acc: string[] = [];
+  walk(dir, acc);
+  opts.walkCache?.set(dir, acc);
+  return acc;
+}
+
+/** Expand inputs (paths/dirs/globs) into a sorted, de-duplicated file list. */
+export function expandInputs(inputs: string[], opts: ExpandOpts = {}): string[] {
+  const include = compileGlobs(opts.include);
+  const exclude = compileGlobs(opts.exclude);
+  const exts = extSet(opts.ext);
+  const files = new Set<string>();
+  const explicit = new Set<string>(); // files named directly — never auto-excluded
+
+  for (const input of inputs) {
+    if (input === "-") continue; // stdin handled by the caller
+    if (hasGlob(input)) {
+      // A positional glob input is ONE glob (no comma-splitting — that is an
+      // --include/--exclude flag affordance), compiled by the engine.
+      const match = engineCompileGlobs([input])!;
+      const acc = walkCached(staticBase(input), opts);
+      // Honour the markup allowlist for globs too — a broad `src/**` must not pull
+      // in .js/.css/.json and parse them as HTML (engine scope is markup only).
+      for (const f of acc) if (match(toPosix(f)) && exts.has(ext(f))) files.add(f);
+    } else if (existsSync(input)) {
+      if (statSync(input).isDirectory()) {
+        const acc = walkCached(input, opts);
+        for (const f of acc) if (exts.has(ext(f))) files.add(f);
+      } else if (exts.has(ext(input))) {
+        files.add(input);
+        explicit.add(input);
+      }
+    } else if (input !== ".") {
+      // A non-glob path that doesn't exist (a typo, a not-yet-built dist/…) — warn so a
+      // gate never reads "0 files · 100%" on a silent miss. A glob matching nothing is fine.
+      opts.onWarn?.(`ultra11y: input not found: ${input}`);
+    }
+  }
+
+  let list = [...files];
+  if (include) list = list.filter((f) => include(toPosix(f)));
+  if (exclude) list = list.filter((f) => !exclude(toPosix(f)));
+  // Default test-artifact exclusion — re-admitted when the file was named directly or
+  // matched by an explicit --include. Logged (never a silent drop).
+  if (!opts.noDefaultExcludes) {
+    const before = list.length;
+    list = list.filter((f) => {
+      const rel = toPosix(f);
+      return !isTestArtifact(rel) || explicit.has(f) || (include != null && include(rel));
+    });
+    const dropped = before - list.length;
+    if (dropped) opts.onWarn?.(`ultra11y: skipped ${dropped} test/spec/story file(s) — pass --no-default-excludes to audit them.`);
+  }
+  return list.sort();
+}

package/src/graph/build.ts

@@ -0,0 +1,114 @@
+// Pass 1 of `audit --graph`: stream every discovered file, parse it, extract a
+// compact FileGraphNode, and DISCARD the AST/Doc — so only O(file count) small
+// records are ever held, never whole-repo source. Then assemble the DepGraph.
+import { readText, ext } from "../util.js";
+import { GRAPH_ONLY_EXT } from "../glob.js";
+import { detectKind, splitAstroFrontmatter, parseSource, parseSourceWithAst } from "../parse/source.js";
+import { parseJsxAst } from "../parse/jsx-ast.js";
+import type { Doc } from "../parse/html.js";
+import { dirname } from "node:path";
+import { extractGraphNode, type FileGraphNode } from "./imports.js";
+import { buildGraph, type DepGraph } from "./graph.js";
+import { readTsAliases } from "./tsconfig.js";
+
+const GRAPH_ONLY = new Set(GRAPH_ONLY_EXT);
+
+// A plain TS/JS module has no markup — an empty Doc keeps extractGraphNode from
+// reading nothing but its (non-existent) elements, while still handing the real
+// source's AST to the import/export extraction below. Never fed through `parseHtml`
+// on the real TS/JS text: generics like `Array<string>` would look like tags to it.
+function emptyDoc(file: string, source: string): Doc {
+  return { file, source, lossy: false, kind: "html", roots: [], elements: [], byId: new Map(), lineStarts: [0] };
+}
+
+// .vue/.svelte's own <script>/<script setup>…</script> block — the only part of an
+// SFC that's real JS/TS. Astro's frontmatter fence is handled separately (it isn't
+// a <script> tag) via splitAstroFrontmatter.
+const SCRIPT_BLOCK_RE = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
+
+// The graph-relevant script source of an SFC: Astro's `---…---` frontmatter, or a
+// .vue/.svelte file's <script> block(s). A Vue SFC commonly has BOTH `<script>` and
+// `<script setup>` — concatenate ALL blocks so imports/exports from either are seen.
+// "" when there is none to parse (template-only SFC) — extractGraphNode still
+// synthesizes the self component def either way.
+function sfcScriptSource(content: string, file: string): string {
+  if (/\.astro$/i.test(file)) return splitAstroFrontmatter(content).frontmatter;
+  return [...content.matchAll(SCRIPT_BLOCK_RE)].map((m) => m[1] ?? "").join("\n");
+}
+
+// How much of the graph pass's parse work may be carried over to the audit loop.
+// The graph pass already reads and parses every markup file; without a hand-off the
+// audit loop reads and parses each of them a SECOND time. Handing the Docs over is a
+// pure win — they are the very same objects `parseSource` would rebuild — but holding
+// them all would break the streaming design's bounded-memory promise on a huge repo.
+// So the hand-off is budgeted: files are cached in discovery order (deterministic)
+// until either ceiling is hit, after which the audit loop simply re-parses as before.
+const CARRY_MAX_BYTES = 12 * 1024 * 1024;
+const CARRY_MAX_ELEMENTS = 300_000;
+
+export interface GraphBuild {
+  graph: DepGraph;
+  /** Markup Docs already parsed by this pass, for the audit loop to reuse. Bounded —
+   *  a miss is not an error, it just means "parse it yourself". Never holds the
+   *  synthetic empty Docs of plain .ts/.js modules (no markup to audit). */
+  docs: Map<string, Doc>;
+}
+
+/** The graph alone — the shape every caller but the audit loop wants. */
+export function buildGraphStreaming(files: string[]): DepGraph {
+  return buildGraphAndDocs(files).graph;
+}
+
+export function buildGraphAndDocs(files: string[], opts: { carryDocs?: boolean; carryBudget?: { bytes: number; elements: number } } = {}): GraphBuild {
+  const budget = opts.carryBudget ?? { bytes: CARRY_MAX_BYTES, elements: CARRY_MAX_ELEMENTS };
+  const nodes: FileGraphNode[] = [];
+  const docs = new Map<string, Doc>();
+  let carriedBytes = 0;
+  let carriedElements = 0;
+  for (const file of files) {
+    let content: string;
+    try {
+      content = readText(file);
+    } catch {
+      continue; // unreadable / vanished — skip, like the audit loop does
+    }
+    let ast = null;
+    let doc: Doc;
+    let sfc = false;
+    let auditable = false;
+    if (GRAPH_ONLY.has(ext(file))) {
+      // Plain .ts/.js/.mjs/.cjs: never an audit target (see GRAPH_ONLY_EXT), but real
+      // cross-file structure (barrel re-exports, plain-JS component definitions) the
+      // graph needs. Babel's typescript+jsx plugins parse pure TS/JS fine.
+      ast = parseJsxAst(content);
+      doc = emptyDoc(file, content);
+    } else if (detectKind(file) === "sfc") {
+      // The script/frontmatter AST is parsed SEPARATELY from the template doc (see
+      // sfcScriptSource) purely for imports/re-exports; extractGraphNode also
+      // synthesizes a self component def (opts.sfc) so cross-file resolution and
+      // capture coverage see the SFC itself.
+      sfc = true;
+      auditable = true;
+      doc = parseSource(content, file);
+      const scriptSrc = sfcScriptSource(content, file);
+      if (scriptSrc) ast = parseJsxAst(scriptSrc);
+    } else {
+      // HTML and JSX/TSX go through the audit's OWN parser, so the Doc handed to the
+      // audit loop below is byte-for-byte the one it would have built itself.
+      auditable = true;
+      ({ doc, ast } = parseSourceWithAst(content, file));
+    }
+    if (opts.carryDocs && auditable && carriedBytes + content.length <= budget.bytes && carriedElements + doc.elements.length <= budget.elements) {
+      docs.set(file, doc);
+      carriedBytes += content.length;
+      carriedElements += doc.elements.length;
+    }
+    nodes.push(extractGraphNode(ast, doc, file, { sfc }));
+  }
+  // tsconfig-paths anchoring, walking up from the first file's dir as before. The
+  // engine resolver reads the tsconfig chain itself (via `startDir`); the parsed
+  // cwd-relative alias map only feeds the fallback resolver. Empty when there is
+  // no tsconfig.
+  const startDir = files[0] ? dirname(files[0]) : process.cwd();
+  return { graph: buildGraph(nodes, readTsAliases(startDir), startDir), docs };
+}

package/src/graph/graph.ts

@@ -0,0 +1,126 @@
+// The cross-file dependency + component graph: a map of compact per-file nodes
+// plus the queries the cross-file rules need. Built once (pass 1) over the full
+// discovered scope; consumed (read-only) during the audit pass.
+import type { FileGraphNode, ComponentDef } from "./imports.js";
+import { makeSpecResolver, type SpecResolver } from "./engine-resolve.js";
+import type { AliasMap } from "./tsconfig.js";
+import { toPosix } from "../glob.js";
+
+export interface DepGraph {
+  nodes: Map<string, FileGraphNode>; // posix file -> node
+  known: ReadonlySet<string>; // all discovered files (posix), for specifier resolution
+  allIds: ReadonlySet<string>; // every literal id defined anywhere (global skip-link lookup)
+  // Engine-backed specifier resolution (relative / ESM ".js" / tsconfig-alias
+  // imports) bounded to `known`, with the original resolver as fallback.
+  resolveSpec: SpecResolver;
+  // Memo for `resolveUsage` top-level lookups (`file#name` -> def, null = "no such
+  // component"). Read-only graph, so a hit is always correct; see resolveUsage.
+  usageCache: Map<string, ComponentDef | null>;
+}
+
+export function buildGraph(nodes: FileGraphNode[], aliases: AliasMap = [], tsconfigStartDir?: string): DepGraph {
+  const map = new Map<string, FileGraphNode>();
+  const known = new Set<string>();
+  const allIds = new Set<string>();
+  // Deterministic: index in sorted-path order so re-runs are byte-identical.
+  for (const n of [...nodes].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))) {
+    map.set(n.file, n);
+    known.add(n.file);
+    for (const id of n.definesIds) allIds.add(id);
+  }
+  return { nodes: map, known, allIds, resolveSpec: makeSpecResolver(known, aliases, tsconfigStartDir), usageCache: new Map() };
+}
+
+/** Resolve a component used as `<localName/>` in `file` to its definition, following the
+ *  import binding across files (relative or aliased), a namespace member (`<UI.Button/>`),
+ *  a local definition, or a chain of barrel re-exports (`export { X } from "./x"`, modeled
+ *  as an import-like binding by extractGraphNode) — however many barrels deep. `seen`
+ *  guards against a re-export cycle (each file+name hop visited at most once). */
+export function resolveUsage(graph: DepGraph, file: string, localName: string, seen: Set<string> = new Set()): ComponentDef | undefined {
+  const posix = toPosix(file);
+  const visitKey = `${posix}#${localName}`;
+  // Top-level lookups are memoised: the graph is read-only for the whole audit, so
+  // `(file, name)` always resolves the same way, and several cross rules walk the very
+  // same component usages independently. Recursive hops keep their `seen` set and are
+  // NOT cached — their result is relative to the path already taken.
+  const memoized = seen.size === 0;
+  if (memoized) {
+    const hit = graph.usageCache.get(visitKey);
+    if (hit !== undefined) return hit ?? undefined;
+  }
+  if (seen.has(visitKey)) return undefined;
+  seen.add(visitKey);
+  if (memoized) {
+    const out = resolveUsageUncached(graph, posix, localName, seen);
+    graph.usageCache.set(visitKey, out ?? null);
+    return out;
+  }
+  return resolveUsageUncached(graph, posix, localName, seen);
+}
+
+function resolveUsageUncached(graph: DepGraph, posix: string, localName: string, seen: Set<string>): ComponentDef | undefined {
+  const node = graph.nodes.get(posix);
+  if (!node) return undefined;
+  // Namespaced usage `<UI.Button/>` → namespace import `import * as UI` + member Button.
+  if (localName.includes(".")) {
+    const dot = localName.indexOf(".");
+    const ns = localName.slice(0, dot);
+    const member = localName.slice(dot + 1);
+    const nsImp = node.imports.find((i) => i.imported === "*" && i.local === ns);
+    if (!nsImp) return undefined;
+    const target = graph.resolveSpec(posix, nsImp.source);
+    if (!target) return undefined;
+    // The namespace target may be a BARREL: `<UI.Button/>` where UI is `import * as UI from
+    // "./components"` and components re-exports Button. If it isn't a direct component there,
+    // follow the barrel's re-export bindings one more hop.
+    return graph.nodes.get(target)?.components.get(member) ?? resolveUsage(graph, target, member, seen);
+  }
+  const imp = node.imports.find((i) => i.local === localName);
+  if (imp) {
+    if (imp.imported === "*") return undefined; // bare namespace binding used without a member
+    const target = graph.resolveSpec(posix, imp.source);
+    if (!target) return undefined;
+    const direct = graph.nodes.get(target)?.components.get(imp.imported);
+    if (direct) return direct;
+    // The target doesn't define it directly — it may itself re-export it from
+    // elsewhere (a barrel of barrels). Follow one more hop.
+    return resolveUsage(graph, target, imp.imported, seen);
+  }
+  const local = node.components.get(localName);
+  if (local) return local; // locally-defined component
+  // `export * from "./x"` wildcard barrel: the name may be defined in any starred source.
+  for (const src of node.starReexports) {
+    const target = graph.resolveSpec(posix, src);
+    if (!target) continue;
+    const hit = resolveUsage(graph, target, localName, seen);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/** Is `id` defined as a literal id by any file in the graph? */
+export function idDefinedAnywhere(graph: DepGraph, id: string): boolean {
+  return graph.allIds.has(id);
+}
+
+/** Does any file `file` transitively imports declare an <html lang> (wrapper/layout
+ *  pattern)? Used to suppress a missing-lang false positive on a wrapped document. */
+export function htmlLangProvidedFor(graph: DepGraph, file: string): boolean {
+  const start = toPosix(file);
+  const seen = new Set<string>([start]);
+  const queue: string[] = [start];
+  while (queue.length) {
+    const cur = queue.shift() as string;
+    const node = graph.nodes.get(cur);
+    if (!node) continue;
+    if (cur !== start && node.providesHtmlLang) return true;
+    for (const imp of node.imports) {
+      const target = graph.resolveSpec(cur, imp.source);
+      if (target && !seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return false;
+}