@binclusive/a11y 0.1.0

package/src/hook.ts

@@ -0,0 +1,242 @@
+/**
+ * The Claude Code "auto-whisper" hook: a `PostToolUse` handler that runs the
+ * a11y-checker on JUST the file the AI just edited and feeds any findings back
+ * as `additionalContext` so the model fixes them in the SAME turn.
+ *
+ * It is the loop-closer for slice 2. Slice 1 (`mcp.ts`) lets an agent ASK the
+ * checker; this hook makes the checker speak up UNASKED the instant a `.tsx`
+ * edit lands. Same wrapping discipline as `mcp.ts`: every handler is a THIN
+ * wrapper over `scan` + `enrichAll` — no new a11y logic lives here.
+ *
+ * It handles two ecosystems by file extension: a `.tsx` edit runs the React scan
+ * (floor only), and a `.prefab`/`.unity` edit runs the Unity finding-emission
+ * aggregator (`collectUnityFindings`) over the enclosing project, scoped to the
+ * edited asset — Unity reaches the editor surface at parity with React (#92).
+ *
+ * Contract (verified against https://docs.claude.com/en/docs/claude-code/hooks):
+ *   stdin  — the PostToolUse event JSON. Relevant fields:
+ *              { tool_name, tool_input: { file_path, ... }, cwd, ... }
+ *            Edit / Write / MultiEdit all carry the edited path at
+ *            `tool_input.file_path`.
+ *   stdout — to inject context the model reads alongside the tool result:
+ *              { "hookSpecificOutput":
+ *                  { "hookEventName": "PostToolUse", "additionalContext": "…" } }
+ *
+ * Two hard rules, both because this runs in the developer's edit path:
+ *   - FAST: scan ONE file, never a directory walk.
+ *   - FAIL-SAFE: never throw, never block. PostToolUse cannot block the edit
+ *     (it already ran), and a crash here would spam stderr to the model every
+ *     edit. Any problem → emit nothing, exit 0. The edit is advisory-only.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { z } from "zod";
+import { scan, type ScanResult } from "./core";
+import { evidenceFix, type EnrichedFinding, enrichAll } from "./evidence";
+import { collectUnityFindings } from "./unity-findings";
+
+/**
+ * The slice of the PostToolUse payload we use. The full event carries more
+ * (session_id, transcript_path, permission_mode, tool_response, …) but we only
+ * need the edited path and the cwd to resolve it. `tool_input.file_path` is
+ * how Edit / Write / MultiEdit each name the file they touched; `.passthrough()`
+ * keeps the parse from rejecting the fields we don't model.
+ *
+ * `cwd` is optional: a relative `file_path` is resolved against it, but an
+ * absolute path (the common case) needs neither, so a payload without `cwd`
+ * still works rather than failing the parse.
+ */
+const PostToolUseInput = z
+  .object({
+    tool_name: z.string().optional(),
+    cwd: z.string().optional(),
+    tool_input: z.object({ file_path: z.string() }).passthrough().optional(),
+  })
+  .passthrough();
+
+/** The stdout envelope that injects context back into the model. */
+export interface HookOutput {
+  readonly hookSpecificOutput: {
+    readonly hookEventName: "PostToolUse";
+    readonly additionalContext: string;
+  };
+}
+
+/** Cap the whisper: a few lines max, top findings only. It runs every edit. */
+const MAX_FINDINGS = 5;
+
+/**
+ * One finding → one terse line: `file:line · rule · WCAG SC · fix`.
+ * The rule id is stripped of its `jsx-a11y/` prefix; the fix falls back to the
+ * eslint message when the baseline catalog has no representative fix for the SC.
+ */
+function formatLine(f: EnrichedFinding, root: string): string {
+  const where = `${relative(root, f.file)}:${f.line}`;
+  const rule = f.ruleId.replace(/^jsx-a11y\//, "");
+  const sc = f.wcag.length > 0 ? `WCAG ${f.wcag.join(", ")}` : "no WCAG mapping";
+  const fix = evidenceFix(f.corpus) ?? f.message;
+  return `  ${where} · ${rule} · ${sc} · ${fix}`;
+}
+
+/**
+ * Build the `additionalContext` string for a file's findings, framed
+ * imperatively so the model corrects the edit it just made. Returns null when
+ * there is nothing to say (no findings) — the caller then no-ops.
+ */
+export function formatWhisper(
+  filePath: string,
+  findings: readonly EnrichedFinding[],
+  root: string,
+): string | null {
+  if (findings.length === 0) return null;
+  const shown = findings.slice(0, MAX_FINDINGS);
+  const header = `You just edited ${relative(root, filePath)}. It has these accessibility issues — fix them now:`;
+  const lines = shown.map((f) => formatLine(f, root));
+  const more =
+    findings.length > shown.length
+      ? [`  …and ${findings.length - shown.length} more (run \`a11y-checker check\` for all).`]
+      : [];
+  return [header, ...lines, ...more].join("\n");
+}
+
+
+/** Markers of a Unity project root, checked walking up from an edited asset.
+ * `Assets` + `ProjectSettings` are the two canonical top-level dirs Unity creates;
+ * either one present is enough to call a directory the project root. */
+const UNITY_ROOT_MARKERS = ["Assets", "ProjectSettings"] as const;
+
+/**
+ * Locate the enclosing Unity project for an edited `.prefab`/`.unity` asset.
+ * Walks up from the asset's directory looking for a Unity root marker
+ * (`Assets`/`ProjectSettings`); returns the first directory that has one. Falls
+ * back to the asset's own directory when no marker is found (a loose fixture or a
+ * detached asset) so the aggregator still scans something rather than no-op'ing —
+ * `collectUnityFindings` is forgiving, so a directory with no further assets just
+ * yields the findings for this one file's siblings.
+ */
+function findUnityProjectRoot(filePath: string): string {
+  let dir = dirname(filePath);
+  for (;;) {
+    if (UNITY_ROOT_MARKERS.some((m) => existsSync(join(dir, m)))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached the filesystem root
+    dir = parent;
+  }
+  return dirname(filePath);
+}
+
+/**
+ * The Unity branch of {@link runHook}: an edited `.prefab`/`.unity` asset. Locate
+ * the enclosing project, run the Unity finding-emission aggregator over it
+ * (`collectUnityFindings` — the SAME spine the CLI/MCP use), enrich the findings,
+ * and emit the SAME floor whisper as the `.tsx` path, scoped to the edited asset so
+ * the model fixes the file it just touched (per-file parity with React). No
+ * Unity-specific report path — it reuses `enrichAll` + `formatWhisper` verbatim.
+ *
+ * Fail-safe like the `.tsx` branch: any throw → null (the edit is advisory-only).
+ */
+async function runUnityHook(filePath: string, base: string): Promise<HookOutput | null> {
+  try {
+    const projectRoot = findUnityProjectRoot(filePath);
+    const raw = await collectUnityFindings(projectRoot);
+    // Scope to the asset just edited (the aggregator scans the whole project) so the
+    // whisper speaks only to the file the model touched — per-file parity with .tsx.
+    const forFile = raw.filter((f) => resolve(f.file) === resolve(filePath));
+    const findings = enrichAll(forFile);
+
+    const floor = formatWhisper(filePath, findings, base);
+    if (floor === null) return null;
+    return { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: floor } };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the checker on ONE edited file and return the `additionalContext`
+ * envelope, or null to no-op. Pulls `file_path` from `tool_input`, resolves it
+ * against `cwd` if relative, and dispatches by extension: `.tsx` runs the React
+ * scan (floor only), `.prefab`/`.unity` runs the Unity aggregator; anything
+ * else no-ops.
+ *
+ * Reused by both the CLI entry and the tests — the tests call it directly with
+ * a sample payload, the CLI feeds it parsed stdin.
+ */
+export async function runHook(raw: unknown): Promise<HookOutput | null> {
+  const parsed = PostToolUseInput.safeParse(raw);
+  if (!parsed.success) return null;
+
+  const filePathRaw = parsed.data.tool_input?.file_path;
+  if (filePathRaw === undefined) return null;
+
+  // Resolve relative paths against the event's cwd; absolute paths pass through.
+  const base = parsed.data.cwd ?? process.cwd();
+  const filePath = isAbsolute(filePathRaw) ? filePathRaw : resolve(base, filePathRaw);
+
+  // Unity assets take the aggregator path; .tsx takes the React scan below.
+  if (filePath.endsWith(".prefab") || filePath.endsWith(".unity")) {
+    return runUnityHook(filePath, base);
+  }
+
+  // Only .tsx files are scannable on the React path — silently no-op on the rest.
+  if (!filePath.endsWith(".tsx")) return null;
+
+  // FAIL-SAFE (module contract): from the scan onward, any throw → null. This
+  // wraps the direct (test/non-CLI) callers too, not just `runHookCli`.
+  try {
+    const result = await scan([filePath]);
+    const findings = enrichAll(result.findings);
+
+    // Relativize against the file's directory so the whisper shows a short path,
+    // not the absolute one ESLint reports.
+    const root = base;
+    // The PRECISE static floor ("fix these"). Emit nothing when it is empty.
+    const floor = formatWhisper(filePath, findings, root);
+    if (floor === null) return null;
+
+    return {
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: floor },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Read all of stdin to a string. Returns "" if stdin is empty/closed. */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * CLI entry for `a11y-checker hook`: read the PostToolUse JSON from stdin, run
+ * the checker on the edited file, and print the `additionalContext` envelope.
+ *
+ * Wrapped end-to-end so NOTHING escapes as a non-zero exit or an unhandled
+ * throw — a hook that crashes would heckle the model on every edit. On any
+ * problem (bad JSON, scan failure, non-tsx) it prints nothing and exits 0.
+ */
+export async function runHookCli(): Promise<void> {
+  try {
+    const stdin = await readStdin();
+    if (stdin.trim() === "") return;
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(stdin);
+    } catch {
+      return; // malformed input → no-op
+    }
+
+    const output = await runHook(raw);
+    if (output !== null) {
+      process.stdout.write(JSON.stringify(output));
+    }
+  } catch {
+    // Fail-safe: any error → silent no-op, exit 0. Never block the edit.
+  }
+}

package/src/impact-gate.ts

@@ -0,0 +1,107 @@
+/**
+ * The `check` command's OPT-IN blocking gate (issue #2134).
+ *
+ * By default `check` exits non-zero only when a contract-BLOCKING finding fired
+ * (`enforcement === "block"`); a scan that surfaces only warn-level findings is a
+ * clean build. This module adds a strictly opt-in overlay: `--fail-on <impact>`
+ * fails the check when any finding is at or above an impact threshold, and
+ * `--max-violations <n>` fails it when the finding count exceeds `n`.
+ *
+ * DEFAULT-SAFE BY CONSTRUCTION: with an unset gate the exit code is EXACTLY
+ * today's behavior — findings never fail the check on impact or volume alone.
+ * Both knobs are opt-in; there is no impact default.
+ */
+import { Impact } from "@binclusive/a11y-contract";
+import { evidenceImpact, type EnrichedFinding } from "./evidence";
+
+/**
+ * The canonical impact ordering — most-severe first (`critical` < `serious` <
+ * `moderate` < `minor` < `unknown`) — read straight from the contract's own
+ * `Impact` enum. We source the order from the enum's `.options` rather than
+ * hand-rolling a second rank map, so the gate can never disagree with the
+ * contract's impact vocabulary.
+ */
+export const IMPACT_ORDER: readonly Impact[] = Impact.options;
+
+/** Rank of an impact in {@link IMPACT_ORDER} — lower index = more severe. */
+function impactRank(s: Impact): number {
+  return IMPACT_ORDER.indexOf(s);
+}
+
+/**
+ * The exit-policy config. Two independent overlays on the exit code:
+ *
+ * - `failOn` / `maxViolations` — the OPT-IN blocking gate (#2134). Both default
+ *   to `null` (unset), the default-safe state in which the gate never fails the
+ *   check on findings alone.
+ * - `advisory` — the generic CI runner mode (#2236). When `true`, the run's
+ *   BASELINE exit is 0 even when contract-blocking findings fired: the engine
+ *   reports every finding but never fails the check by itself. This is the
+ *   first-class non-blocking default a CI runner selects (via `check --ci`),
+ *   replacing the old shell `|| true` swallow with an exit policy the engine
+ *   owns. The opt-in gate still overrides in advisory mode — set `failOn` /
+ *   `maxViolations` and the run fails when the threshold trips — so blocking
+ *   stays available but is strictly opt-in.
+ */
+export interface GateConfig {
+  readonly failOn: Impact | null;
+  readonly maxViolations: number | null;
+  readonly advisory: boolean;
+}
+
+/**
+ * The default exit policy: blocking-on-contract-block, gate off. This is the
+ * plain-CLI default — a local `check` still exits non-zero on a blocking finding.
+ */
+export const GATE_OFF: GateConfig = { failOn: null, maxViolations: null, advisory: false };
+
+/**
+ * The generic CI runner default (#2236): non-blocking baseline (exit 0 on any
+ * findings) with no opt-in gate. `check --ci` selects this so any CI can consume
+ * the SARIF/JSON artifact without the check failing; layering `failOn` /
+ * `maxViolations` on top re-enables a failing exit.
+ */
+export const GATE_ADVISORY: GateConfig = { failOn: null, maxViolations: null, advisory: true };
+
+/** The minimal per-finding projection the gate reasons over. */
+export interface GateFinding {
+  readonly impact: Impact;
+  /** Whether the contract BLOCKS this finding (`enforcement === "block"`). */
+  readonly blocking: boolean;
+}
+
+/** Project an enriched finding onto the gate's minimal shape. */
+export function toGateFinding(f: EnrichedFinding): GateFinding {
+  // Absent impact ⇒ the contract's `unknown` (least severe): the gate reads the
+  // finding's own resolved impact, never a re-derived band.
+  return { impact: evidenceImpact(f) ?? "unknown", blocking: f.enforcement === "block" };
+}
+
+/**
+ * The `check` command's exit code, honoring the opt-in gate.
+ *
+ * With an unset gate (`failOn` and `maxViolations` both `null`) the result is
+ * today's behavior EXACTLY: non-zero iff a contract-blocking finding fired —
+ * UNLESS `advisory` is set, in which case the baseline is 0 (the generic CI
+ * runner mode, #2236: findings are reported but never fail the check on their
+ * own).
+ *
+ * When the gate IS set, the exit reflects the gate: non-zero when any finding is
+ * at or above `failOn` (impact rank ≤ threshold rank), or when the finding
+ * count exceeds `maxViolations`; zero otherwise. The opt-in gate applies in
+ * advisory mode too, so a CI runner can still opt into a failing exit.
+ */
+export function gateExitCode(findings: readonly GateFinding[], gate: GateConfig): number {
+  const gated = gate.failOn !== null || gate.maxViolations !== null;
+  if (!gated) {
+    // Advisory baseline (#2236): non-blocking even with contract-blocking findings.
+    if (gate.advisory) return 0;
+    return findings.some((f) => f.blocking) ? 1 : 0;
+  }
+  if (gate.failOn !== null) {
+    const threshold = impactRank(gate.failOn);
+    if (findings.some((f) => impactRank(f.impact) <= threshold)) return 1;
+  }
+  if (gate.maxViolations !== null && findings.length > gate.maxViolations) return 1;
+  return 0;
+}

package/src/imports-resolve.ts

@@ -0,0 +1,248 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+
+/**
+ * package.json `imports`-subpath resolver: follow a `#`-prefixed internal import
+ * (`#app/components/ui/button`) to its REAL source file by reading the nearest
+ * package.json's `imports` map, the same way Node + bundlers do.
+ *
+ * Why this exists. The checker already resolves tsconfig `paths` aliases and
+ * workspace packages to own-code so it can TRACE them. Node's `imports` field is
+ * the third own-code alias source — the `#`-prefixed internal subpath imports
+ * Epic Stack and modern Remix-style repos use (`"#app/*": "./app/*"`). A bare
+ * `import { Button } from "#app/components/ui/button"` (no extension) is invisible
+ * to TypeScript's module resolution, so the own-code component it points at falls
+ * into the opaque/declare set and hollows the `checked` count. (TS DOES follow a
+ * `#`-import that carries an explicit extension — `#app/.../icon.tsx` — but not
+ * the extensionless form, which is the common one.) This module fills that gap.
+ *
+ * It is ONE MORE ALIAS SOURCE, not a new subsystem — it mirrors
+ * `resolveWorkspaceImport`'s shape (find root → match pattern → resolve target to
+ * a file on disk) so a `#`-resolved target feeds the SAME trace/own-code
+ * machinery as a tsconfig-`paths` target.
+ *
+ * Everything is best-effort + boundary-parsed: a missing/malformed package.json,
+ * an `imports` value in an unrecognized shape, or a subpath no pattern covers all
+ * yield `null` — the caller then keeps the wrapper opaque rather than guessing.
+ */
+
+/** File extensions we treat as resolvable source, in resolution-preference order. */
+const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"] as const;
+
+/**
+ * Conditional-`imports` keys we read to pick the RUNTIME target, in preference
+ * order. `default` first (the unconditional fallback Node always honors), then
+ * the runtime conditions; `types` is deliberately absent — a `.d.ts` is not the
+ * source we trace. Probed in this order so the actual code path wins.
+ */
+const IMPORT_CONDITIONS = ["default", "import", "require", "node", "browser"] as const;
+
+/** A compiled `imports` entry: a `#`-prefixed subpath pattern and its target. */
+interface ImportPattern {
+  /** The key as written (`"#app/*"`, `"#config"`). */
+  readonly key: string;
+  /** The resolved runtime target string (`"./app/*"`), already condition-picked. */
+  readonly target: string;
+}
+
+/** A discovered `imports` map: the dir its targets resolve against + the patterns. */
+interface ImportsMap {
+  readonly baseDir: string;
+  readonly patterns: readonly ImportPattern[];
+}
+
+const importsCache = new Map<string, ImportsMap | null>();
+
+/**
+ * Find the nearest package.json at or above `fromDir` that declares an `imports`
+ * field, returning its compiled patterns + base dir. Walks UP to the filesystem
+ * root (the same root-detection the checker uses for stack/tsconfig), so a scan
+ * pointed at a nested route file still finds the app's package.json. A
+ * package.json WITHOUT `imports` does not stop the walk — a parent may carry it.
+ * Cached per starting directory. Returns `null` when none is found.
+ */
+function findImportsMap(fromDir: string): ImportsMap | null {
+  const cached = importsCache.get(fromDir);
+  if (cached !== undefined) return cached;
+
+  let dir = fromDir;
+  for (;;) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const patterns = parseImportsField(readFileSafe(pkgPath));
+      if (patterns.length > 0) {
+        const map: ImportsMap = { baseDir: dir, patterns };
+        importsCache.set(fromDir, map);
+        return map;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  importsCache.set(fromDir, null);
+  return null;
+}
+
+function readFileSafe(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function parseJson(text: string): Record<string, unknown> | null {
+  if (text === "") return null;
+  try {
+    const v: unknown = JSON.parse(text);
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+      ? (v as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compile the `imports` field of a package.json into its `#`-prefixed patterns.
+ * Each value is reduced to a single runtime target string: a plain string is the
+ * target verbatim; a conditional object (`{ types, import, default }`) is probed
+ * in {@link IMPORT_CONDITIONS} order (runtime target, never `types`). A value in
+ * an unrecognized shape (array, no usable condition) is skipped — it never
+ * crashes the parse. Only `#`-prefixed keys are kept (the `imports` spec requires
+ * the `#` prefix; anything else is malformed and ignored).
+ */
+function parseImportsField(text: string): ImportPattern[] {
+  const pkg = parseJson(text);
+  if (pkg === null) return [];
+  const imports = pkg.imports;
+  if (typeof imports !== "object" || imports === null || Array.isArray(imports)) return [];
+  const out: ImportPattern[] = [];
+  for (const [key, value] of Object.entries(imports)) {
+    if (!key.startsWith("#")) continue;
+    const target = pickConditionTarget(value);
+    if (target !== null) out.push({ key, target });
+  }
+  return out;
+}
+
+/**
+ * Reduce an `imports` entry to a single RUNTIME target string. A plain string is
+ * the target; a conditions object is probed in our preference order (`default`
+ * first, then runtime conditions; `types` ignored). Nested condition objects
+ * recurse. Returns `null` when no usable string target is found — the caller
+ * skips that pattern gracefully.
+ */
+function pickConditionTarget(entry: unknown): string | null {
+  if (typeof entry === "string") return entry;
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return null;
+  const obj = entry as Record<string, unknown>;
+  for (const cond of IMPORT_CONDITIONS) {
+    if (cond in obj) {
+      const nested = pickConditionTarget(obj[cond]);
+      if (nested !== null) return nested;
+    }
+  }
+  // Fall back to the first usable target in declaration order, but never a
+  // `types`-only entry (a `.d.ts` is not the source we want to trace).
+  for (const [cond, value] of Object.entries(obj)) {
+    if (cond === "types") continue;
+    const nested = pickConditionTarget(value);
+    if (nested !== null) return nested;
+  }
+  return null;
+}
+
+/**
+ * Match a `#`-prefixed specifier against a pattern and substitute the `*`. Two
+ * shapes, same as Node + tsconfig path globs:
+ *   - wildcard `"#app/*"` -> `"./app/*"`: capture the text after the prefix and
+ *     substitute it into the target's `*`.
+ *   - exact `"#config"` -> `"./config.ts"`: the specifier must equal the key.
+ * Returns the target with the wildcard filled, or `null` when no match.
+ */
+function applyPattern(pattern: ImportPattern, specifier: string): string | null {
+  const star = pattern.key.indexOf("*");
+  if (star === -1) {
+    return specifier === pattern.key ? pattern.target : null;
+  }
+  const prefix = pattern.key.slice(0, star);
+  const suffix = pattern.key.slice(star + 1);
+  if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) return null;
+  if (specifier.length < prefix.length + suffix.length) return null;
+  const matched = specifier.slice(prefix.length, specifier.length - suffix.length);
+  return pattern.target.replace("*", matched);
+}
+
+/**
+ * Resolve a `#`-prefixed import specifier to its own-code source file via the
+ * nearest package.json `imports` map, or `null` when it is not an `imports`
+ * subpath (or its target can't be mapped to a file). Longest-key-first so a more
+ * specific pattern wins over a catch-all.
+ *
+ * @param specifier the bare module specifier as written (`#app/components/button`)
+ * @param fromFile  the importing file, used to locate the package.json
+ */
+export function resolveImportsSubpath(specifier: string, fromFile: string): string | null {
+  if (!specifier.startsWith("#")) return null;
+
+  const map = findImportsMap(dirname(fromFile));
+  if (map === null) return null;
+
+  // Longest static prefix first: `#app/ui/*` beats `#app/*`.
+  const ordered = [...map.patterns].sort((a, b) => b.key.length - a.key.length);
+  for (const pattern of ordered) {
+    const target = applyPattern(pattern, specifier);
+    if (target === null) continue;
+    const hit = resolveFileTarget(join(map.baseDir, target));
+    if (hit !== null) return hit;
+  }
+  return null;
+}
+
+/**
+ * Turn a target path into an existing source file: try it verbatim, then with
+ * each known source extension, then as a directory `index.*`. This is what lets
+ * an extensionless `#app/components/button` (extension-appended) and a target
+ * that already carries an extension both land on a real file. Returns the
+ * absolute path of the first hit, or `null`.
+ */
+function resolveFileTarget(target: string): string | null {
+  const abs = resolve(target);
+  if (isFile(abs)) return abs;
+  for (const ext of SOURCE_EXTS) {
+    if (isFile(abs + ext)) return abs + ext;
+  }
+  if (isDir(abs)) {
+    for (const ext of SOURCE_EXTS) {
+      const idx = join(abs, `index${ext}`);
+      if (isFile(idx)) return idx;
+    }
+  }
+  // A target that already carries an extension we didn't list but exists.
+  const { ext } = parse(abs);
+  if (ext !== "" && isFile(abs)) return abs;
+  return null;
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Reset the cache — test-only, so fixtures don't bleed across cases. */
+export function __resetImportsCacheForTest(): void {
+  importsCache.clear();
+}