@binclusive/a11y 0.1.0

package/src/detect-stack.ts

@@ -0,0 +1,207 @@
+/**
+ * Generic stack detection for any customer repo — never hardcoded to one
+ * design system. Three independent signals, each boundary-parsed:
+ *
+ *   - framework + router : `package.json` deps + `app/` vs `pages/` on disk
+ *   - designSystem       : the dominant component-source MODULE across all
+ *                          resolved wrappers (registry + traced), so the team's
+ *                          actual UI library wins regardless of which one it is
+ *   - language           : tsconfig presence
+ *
+ * The design-system signal reuses `resolveComponents` (the same map the scanner
+ * builds) so detection and scanning agree on what a "component import" is.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Language, Router, Stack } from "./contract";
+import { familyLabel, isFrameworkPrimitive, isOwnModule, packageNameOf } from "./module-scope";
+import { resolveComponents } from "./resolve-components";
+import { ownAliasMatcherFor } from "./tsconfig-aliases";
+
+// Re-export the shared module-scoping rules so existing importers of
+// `packageNameOf` from this module keep working; the rules now live in
+// `module-scope.ts` so `suggest.ts` shares them without a circular import.
+export { isFrameworkPrimitive, isOwnModule, packageNameOf } from "./module-scope";
+
+/**
+ * Walk UP from `dir` (inclusive) to the nearest ancestor containing `marker`,
+ * stopping at the filesystem root. Returns that directory, or `null` when no
+ * ancestor has it. This is package-up semantics: a scan pointed at a nested
+ * `src/` still finds the app's `package.json` / `tsconfig.json` one or more
+ * levels above, so framework/language detection doesn't silently degrade to
+ * "unknown".
+ */
+function findUp(dir: string, marker: string): string | null {
+  let cur = dir;
+  for (;;) {
+    if (existsSync(join(cur, marker))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+/** A `package.json`'s merged dependency names — the only fields we read. */
+interface PackageDeps {
+  readonly all: ReadonlyMap<string, string>;
+}
+
+/**
+ * Read and boundary-parse a `package.json` into its merged dep map. A missing
+ * file yields an empty map (not every repo has one at the scanned root); a
+ * present-but-malformed file also degrades to empty rather than throwing —
+ * stack detection is best-effort signal, not a hard gate.
+ */
+function readPackageDeps(dir: string): PackageDeps {
+  const path = join(dir, "package.json");
+  if (!existsSync(path)) return { all: new Map() };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { all: new Map() };
+  }
+  if (typeof raw !== "object" || raw === null) return { all: new Map() };
+  const merged = new Map<string, string>();
+  for (const key of ["dependencies", "devDependencies", "peerDependencies"] as const) {
+    const section = (raw as Record<string, unknown>)[key];
+    if (typeof section !== "object" || section === null) continue;
+    for (const [name, version] of Object.entries(section)) {
+      if (typeof version === "string") merged.set(name, version);
+    }
+  }
+  return { all: merged };
+}
+
+/**
+ * Framework detected from a repo's dependency NAMES, with a generic fallback.
+ * Exported (taking a name set, not the whole `PackageDeps`) so the ordering
+ * rules are unit-testable without a fixture on disk.
+ */
+export function detectFrameworkFromDeps(names: ReadonlySet<string>): string {
+  // Order matters: meta-frameworks before the view library they build on.
+  if (names.has("next")) return "next";
+  if (names.has("@remix-run/react") || names.has("@remix-run/node")) return "remix";
+  // React Router v7 "framework mode" is the Remix successor — it dropped the
+  // `@remix-run/*` packages for `@react-router/*` + `react-router`, so a RRv7
+  // app (Documenso) would otherwise fall through to the bare `react` label. We
+  // gate on the framework-mode packages, NOT bare `react-router`: a plain SPA
+  // that uses react-router only for client routing is still just `react`.
+  if (names.has("@react-router/node") || names.has("@react-router/serve")) {
+    return "react-router";
+  }
+  if (names.has("astro")) return "astro";
+  if (names.has("gatsby")) return "gatsby";
+  if (names.has("@angular/core")) return "angular";
+  if (names.has("vue")) return "vue";
+  if (names.has("svelte")) return "svelte";
+  if (names.has("react")) return "react";
+  return "unknown";
+}
+
+/** Framework detected from deps, with a generic fallback. */
+function detectFramework(deps: PackageDeps): string {
+  return detectFrameworkFromDeps(new Set(deps.all.keys()));
+}
+
+/**
+ * Next router from on-disk layout: `app/` (or `src/app/`) is the App Router,
+ * `pages/` (or `src/pages/`) is the Pages Router. Only meaningful for Next —
+ * `null` for every other framework. App wins if both exist (incremental
+ * migrations keep `pages/` around).
+ */
+function detectRouter(dir: string, framework: string): Router {
+  if (framework !== "next") return null;
+  const hasApp = existsSync(join(dir, "app")) || existsSync(join(dir, "src", "app"));
+  if (hasApp) return "app";
+  const hasPages = existsSync(join(dir, "pages")) || existsSync(join(dir, "src", "pages"));
+  if (hasPages) return "pages";
+  return null;
+}
+
+/** Language from tsconfig presence at or above the scanned dir (package-up). */
+function detectLanguage(dir: string): Language {
+  return findUp(dir, "tsconfig.json") !== null ? "ts" : "js";
+}
+
+/**
+ * The repo's design system: the published package that contributes the most
+ * components RESOLVING TO A KNOWN INTERACTIVE HOST (registry or traced). That
+ * is what a design system *is* for a11y purposes — it wraps form/interactive
+ * primitives. Ranking on resolved-host count (not raw usage) is what keeps an
+ * icon library from winning: icons are opaque (no host) and drop out, even
+ * when imported at far more call sites than the real UI library.
+ *
+ * Fallbacks, in order:
+ *   1. most resolved-host wrappers among external packages (the real signal)
+ *   2. if nothing resolves, most-used external package by raw usage (so a repo
+ *      whose wrappers are all opaque still names its dominant library)
+ *   3. `"custom"` when no external package is used at all
+ *
+ * Ties break by package name for determinism. Own-code modules (relative
+ * imports + path aliases) and framework primitives (`next`, `react`, ...) never
+ * count — the design system is the UI-component package, not the platform.
+ *
+ * The winning package is then collapsed to its canonical FAMILY name for the
+ * human-facing label via {@link familyLabel}: a Radix app's dominant package is
+ * some per-component sub-package (`@radix-ui/react-checkbox`), but the reported
+ * design system is `Radix`. Single-package design systems (`bootstrap`) and
+ * workspace packages (`@acme/ui`) pass through unchanged. The collapse is the
+ * label only — it does not affect trusted-library resolution, which keys off the
+ * raw module specifier in `registry.ts`.
+ *
+ * `rootDir` is where the repo's tsconfig is found (find-up), so its
+ * `compilerOptions.paths` aliases that map into own source are excluded too. It
+ * defaults to the directory of the first scanned file — find-up climbs from
+ * there to the governing tsconfig.
+ */
+export function detectDesignSystem(tsxFiles: readonly string[], rootDir?: string): string {
+  if (tsxFiles.length === 0) return "custom";
+  const from = rootDir ?? dirname(tsxFiles[0] ?? ".");
+  const ownAlias = ownAliasMatcherFor(from).isOwnAlias;
+  const { resolutions } = resolveComponents(tsxFiles);
+  const resolvedHost = new Map<string, number>();
+  const rawUsage = new Map<string, number>();
+  for (const r of resolutions) {
+    if (isOwnModule(r.module, ownAlias)) continue; // own component, not a library
+    const pkg = packageNameOf(r.module);
+    if (isFrameworkPrimitive(pkg)) continue; // platform primitive, not a design system
+    rawUsage.set(pkg, (rawUsage.get(pkg) ?? 0) + 1);
+    if (r.host !== null) resolvedHost.set(pkg, (resolvedHost.get(pkg) ?? 0) + 1);
+  }
+
+  const pickMax = (counts: ReadonlyMap<string, number>): string | null => {
+    let best: { pkg: string; n: number } | null = null;
+    for (const [pkg, n] of counts) {
+      if (best === null || n > best.n || (n === best.n && pkg < best.pkg)) {
+        best = { pkg, n };
+      }
+    }
+    return best === null ? null : best.pkg;
+  };
+
+  const winner = pickMax(resolvedHost) ?? pickMax(rawUsage);
+  // Collapse a known multi-package family (Radix, MUI, …) to its canonical name
+  // for the human-facing label; an unknown/single-package DS passes through.
+  return winner === null ? "custom" : familyLabel(winner);
+}
+
+/**
+ * Detect the full stack for a repo rooted at `dir`, given its scannable `.tsx`
+ * files (the same set the checker scans). Each field is independent best-effort
+ * signal; see the per-field helpers for what each reads.
+ */
+export function detectStack(dir: string, tsxFiles: readonly string[]): Stack {
+  // Package-up: a scan pointed at a nested `src/` finds the app's package.json
+  // (and the on-disk app/pages layout) one or more levels above.
+  const pkgRoot = findUp(dir, "package.json") ?? dir;
+  const deps = readPackageDeps(pkgRoot);
+  const framework = detectFramework(deps);
+  return {
+    framework,
+    router: detectRouter(pkgRoot, framework),
+    designSystem: detectDesignSystem(tsxFiles, dir),
+    language: detectLanguage(dir),
+  };
+}

package/src/diff-scope-cli.ts

@@ -0,0 +1,12 @@
+/**
+ * The thin CLI over {@link scopeChangedTsxFromEnv} that `entrypoint.sh` invokes,
+ * so the CI Action resolves its changed-file scope through the SAME module the
+ * engine imports — no second copy of the diff logic in shell. Reads the CI env
+ * (`CHANGED_FILES` / `BASE_SHA` / `HEAD_SHA` / `GITHUB_WORKSPACE`) and prints the
+ * resolved `.tsx` paths, one per line, to stdout.
+ */
+import { scopeChangedTsxFromEnv } from "./diff-scope";
+
+for (const file of scopeChangedTsxFromEnv()) {
+  process.stdout.write(`${file}\n`);
+}

package/src/diff-scope.ts

@@ -0,0 +1,150 @@
+/**
+ * Changed-file diff-scoping — the ONE shared module the engine and the CI Action
+ * both import, replacing the ad-hoc `git diff | grep` shell that used to live
+ * inline in `entrypoint.sh`. Contract-independent: it resolves WHICH `.tsx`
+ * files a run should scan; it knows nothing about findings.
+ *
+ * Resolution order mirrors the tracer-bullet shell, highest priority first:
+ *   1. an explicit `CHANGED_FILES` list (the caller already knows the diff),
+ *   2. a `BASE..HEAD` git diff in the workspace,
+ *   3. nothing — the caller falls back to a wholesale scan.
+ */
+import { execFileSync } from "node:child_process";
+
+export interface DiffScopeInput {
+  /** Explicit changed-file list (whitespace-split upstream), highest priority. */
+  readonly changedFiles?: readonly string[];
+  /** Base commit of the diff (git range lower bound). */
+  readonly baseSha?: string;
+  /** Head commit of the diff (git range upper bound). */
+  readonly headSha?: string;
+  /** Working tree the git diff runs against. */
+  readonly workspace: string;
+}
+
+const TSX = /\.tsx$/;
+
+/** Split a raw whitespace-separated `CHANGED_FILES` value into a path list. */
+export function parseChangedFiles(raw: string): string[] {
+  return raw.split(/\s+/).filter((p) => p !== "");
+}
+
+function isGitRepo(workspace: string): boolean {
+  try {
+    execFileSync("git", ["-C", workspace, "rev-parse", "--git-dir"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function gitDiffNames(workspace: string, baseSha: string, headSha: string): string[] {
+  try {
+    const out = execFileSync(
+      "git",
+      ["-C", workspace, "diff", "--name-only", `${baseSha}...${headSha}`],
+      { encoding: "utf8" },
+    );
+    return out.split("\n").filter((p) => p !== "");
+  } catch {
+    // Advisory gate: a git failure is an empty scope, never a throw.
+    return [];
+  }
+}
+
+/**
+ * The TRUE deletions in a diff — files whose content is GONE, never MOVED.
+ *
+ * `--diff-filter=D` selects deleted entries; `--find-renames` (`-M`) is pinned ON
+ * EXPLICITLY (never left to git's config/context-dependent default) so a MOVE
+ * classifies as `R` and its old path is EXCLUDED — a rename is not a deletion. This
+ * closes a false-resolve hole (ADR 0043 v2): a renamed file's old path must NOT be
+ * reported deleted, or a move out of scan-scope silently vanishes its finding.
+ * Paths are repo-root-relative, forward-slash (git's native output).
+ */
+function gitDeletedNames(workspace: string, baseSha: string, headSha: string): string[] {
+  try {
+    const out = execFileSync(
+      "git",
+      ["-C", workspace, "diff", "--diff-filter=D", "--find-renames", "--name-only", `${baseSha}...${headSha}`],
+      { encoding: "utf8" },
+    );
+    return out.split("\n").filter((p) => p !== "");
+  } catch {
+    // Advisory gate: a git failure is an empty deletion set, never a throw.
+    return [];
+  }
+}
+
+/**
+ * Resolve the source files DELETED in this run's diff (ADR 0043 v2 — the
+ * `deletedPaths` coverage half). A deleted-file's source ticket resolves because the
+ * code — and so the issue — is gone. Derived ONLY from a real `BASE...HEAD` git diff:
+ * an explicit `CHANGED_FILES` name list cannot classify deleted-vs-added, and a full
+ * scan (no base ref) has no deletion context, so both yield `[]` — never a fabricated
+ * deletion (the safe direction: under-report, never over-report).
+ */
+export function deletedPaths(input: DiffScopeInput): string[] {
+  if (
+    input.baseSha !== undefined &&
+    input.baseSha !== "" &&
+    input.headSha !== undefined &&
+    input.headSha !== "" &&
+    isGitRepo(input.workspace)
+  ) {
+    return gitDeletedNames(input.workspace, input.baseSha, input.headSha);
+  }
+  return [];
+}
+
+/**
+ * Resolve the changed `.tsx` files for a run. Returns only `.tsx` paths (the
+ * engine's static React surface); an empty array means "no diff context —
+ * fall back to a wholesale scan", the same signal the shell encoded as an empty
+ * `FILES`.
+ */
+export function scopeChangedTsx(input: DiffScopeInput): string[] {
+  const explicit = input.changedFiles;
+  if (explicit !== undefined && explicit.length > 0) {
+    return explicit.filter((p) => TSX.test(p));
+  }
+  if (
+    input.baseSha !== undefined &&
+    input.baseSha !== "" &&
+    input.headSha !== undefined &&
+    input.headSha !== "" &&
+    isGitRepo(input.workspace)
+  ) {
+    return gitDiffNames(input.workspace, input.baseSha, input.headSha).filter((p) => TSX.test(p));
+  }
+  return [];
+}
+
+/**
+ * Resolve the scope from the CI environment (the Action's contract): reads the
+ * same `CHANGED_FILES` / `BASE_SHA` / `HEAD_SHA` / `GITHUB_WORKSPACE` variables
+ * the shell used, so the Action delegates its file-resolution here verbatim.
+ */
+export function scopeChangedTsxFromEnv(env: NodeJS.ProcessEnv = process.env): string[] {
+  const rawChanged = env.CHANGED_FILES;
+  return scopeChangedTsx({
+    changedFiles: rawChanged !== undefined && rawChanged !== "" ? parseChangedFiles(rawChanged) : undefined,
+    baseSha: env.BASE_SHA,
+    headSha: env.HEAD_SHA,
+    workspace: env.GITHUB_WORKSPACE ?? process.cwd(),
+  });
+}
+
+/**
+ * Resolve the run's TRUE deletions from the CI env — the sibling of
+ * {@link scopeChangedTsxFromEnv} for the `deletedPaths` coverage half. Reads the same
+ * `BASE_SHA` / `HEAD_SHA` / `GITHUB_WORKSPACE` the diff-scope uses; with no base ref
+ * it yields `[]` (never a fabricated deletion).
+ */
+export function deletedPathsFromEnv(env: NodeJS.ProcessEnv = process.env): string[] {
+  return deletedPaths({
+    baseSha: env.BASE_SHA,
+    headSha: env.HEAD_SHA,
+    workspace: env.GITHUB_WORKSPACE ?? process.cwd(),
+  });
+}

package/src/emit-contract.ts

@@ -0,0 +1,181 @@
+/**
+ * The wire projection: `localFinding -> contract`.
+ *
+ * The engine's canonical model is the source-anchored, corpus-enriched
+ * {@link EnrichedFinding} (carries `file`/`line`/`selector`/`ruleId`). It is the
+ * single internal source of truth and NEVER leaves the customer's machine.
+ *
+ * The imported `@binclusive/a11y-contract` `Finding` is the METADATA-ONLY WIRE
+ * DTO — the narrowing boundary projection this module owns. It is what the
+ * phone-home / ingestion path emits. The projection deliberately DROPS every
+ * source locator (`file`, `line`, `ruleId`, `helpUrl`) so no source can cross
+ * the wire: metadata-only by construction, on top of the contract's own
+ * `.strict()` allowlist. This is Parse-Don't-Validate at the emit boundary —
+ * {@link toFindingPayload} re-parses the assembled batch through the contract's
+ * own schema, so an engine that drifts from the shape fails loud here, not on
+ * the platform.
+ *
+ * This is NOT a competing schema. There is ONE model (the local finding) and
+ * ONE wire DTO (the contract). Local renderers (the PR-comment reviewer, the
+ * SARIF renderer) read the RICH local finding directly and never route through
+ * this narrowing — only the emit path does.
+ */
+import {
+  Finding as ContractFindingSchema,
+  type Finding as ContractFinding,
+  type FindingPayload,
+  type Location as ContractLocation,
+  parseFindingPayload,
+  type Provenance as ContractProvenance,
+} from "@binclusive/a11y-contract";
+import type { FindingProvenance } from "./core";
+import type { EnrichedFinding } from "./evidence";
+import { type LocationOptions, resolveLocations } from "./source-identity";
+
+/**
+ * Collapse the engine's 7-value {@link FindingProvenance} onto the contract's
+ * binary origin: the corpus-grounded agent layer is `agent`; every deterministic
+ * static/rendered pass (`jsx-a11y`/`enforce`/`axe`/`swiftui`/`liquid`/`unity`)
+ * is `deterministic`.
+ */
+export function toContractProvenance(p: FindingProvenance): ContractProvenance {
+  return p === "corpus-agent" ? "agent" : "deterministic";
+}
+
+/**
+ * A selector locates a live rendered element. Empty or whitespace-only is NOT a
+ * selector — a source-static pass has no live DOM node, and `??` would let `""`
+ * through as if it were present. The single predicate both the SARIF
+ * logicalLocation and the contract `element` fallback read, so the two can never
+ * disagree on "present vs absent".
+ */
+export function hasSelector(selector: string | undefined): selector is string {
+  return selector !== undefined && selector.trim() !== "";
+}
+
+/**
+ * Project one enriched local finding onto the contract DTO, given its already
+ * resolved wire {@link ContractLocation}. Every source locator (`file`, `line`,
+ * `ruleId`, raw line content) is dropped: the ONLY location that crosses is the
+ * pre-computed `location` — a page `url`, or a source `{ path, lineHash, index }`
+ * fingerprint carrying neither the line number nor the content (ADR 0042). `index`
+ * disambiguation is a batch property, so the location is resolved by the batch
+ * ({@link toFindingPayload}) and threaded in here, keeping this projection pure.
+ *
+ * `element` falls back to the rule id when there is no rendered DOM selector — a
+ * source-static pass has no live element, and the rule id is the honest non-source
+ * locator for the occurrence.
+ */
+export function toContractFinding(
+  f: EnrichedFinding,
+  scope: string,
+  location: ContractLocation,
+): ContractFinding {
+  const base = {
+    location,
+    criterion: f.wcag[0] ?? "",
+    element: hasSelector(f.selector) ? f.selector : f.ruleId,
+    evidence: f.message,
+    scope,
+  } as const;
+
+  if (toContractProvenance(f.provenance) === "agent") {
+    return { provenance: "agent", ...base, rationale: f.message };
+  }
+  return { provenance: "deterministic", ...base };
+}
+
+/**
+ * The emit path: project a batch of local findings onto the wire payload and
+ * re-parse it through the contract's own schema. The parse is the boundary
+ * guarantee — a payload that drifts from the metadata-only shape throws here
+ * (`ZodError`) rather than reaching the platform.
+ *
+ * Locations are resolved for the WHOLE batch up front — a source finding's
+ * `index` disambiguates identical line-content within one file, so it can only be
+ * assigned with the batch in hand (ADR 0042). `options` injects the repo root
+ * (for the relative `path`) and the line-content source (default: read from disk).
+ */
+export function toFindingPayload(
+  findings: readonly EnrichedFinding[],
+  scope: string,
+  options?: LocationOptions,
+): FindingPayload {
+  const locations = resolveLocations(findings, options);
+  return parseFindingPayload({
+    findings: findings.map((f) => toContractFinding(f, scope, mustLocate(locations, f))),
+  });
+}
+
+/** A finding is always in the resolved map ({@link resolveLocations} covers the batch). */
+function mustLocate(locations: ReadonlyMap<EnrichedFinding, ContractLocation>, f: EnrichedFinding): ContractLocation {
+  const location = locations.get(f);
+  if (location === undefined) throw new Error("finding missing from resolved location map");
+  return location;
+}
+
+/** A lenient emit that projects each finding independently, keeping the valid ones. */
+export interface LenientPayload {
+  readonly payload: FindingPayload;
+  /** How many findings failed the contract re-parse and were dropped. */
+  readonly dropped: number;
+  /**
+   * The enriched sources that SURVIVED projection, in `payload.findings` order (1:1).
+   * The metadata-only wire `Finding` carries no impact field, so a transport layer
+   * that must send the 4-level `impact` (Kontrol's `CiFindingInput` extra) reads it
+   * off the paired source here — no second projection, and no widening of the wire
+   * contract.
+   */
+  readonly sources: readonly EnrichedFinding[];
+}
+
+/**
+ * The NON-BLOCKING emit path — same projection as {@link toFindingPayload}, but a
+ * single finding that fails the contract re-parse is DROPPED, not thrown.
+ *
+ * Two emit disciplines, one projection: the deterministic engine emits with the
+ * strict {@link toFindingPayload} (its output is reproducible — drift is a bug that
+ * must fail loud). The AI lane emits with THIS — one malformed model output must
+ * never fail the whole run (the runner always exits 0). Both reuse
+ * {@link toContractFinding} + the contract's own `Finding` schema, so there is no
+ * second projection and no second wire schema.
+ */
+export function toFindingPayloadLenient(
+  findings: readonly EnrichedFinding[],
+  scope: string,
+  options?: LocationOptions,
+): LenientPayload {
+  const locations = resolveLocations(findings, options);
+  const projected: ContractFinding[] = [];
+  const sources: EnrichedFinding[] = [];
+  let dropped = 0;
+  for (const f of findings) {
+    // Guard the WHOLE projection, not just the parse: a malformed finding can
+    // throw inside toContractFinding (a bad wcag/corpus shape) as easily as it
+    // can fail the schema. Either way the one finding is dropped, never the run.
+    const contract = tryProject(f, scope, locations.get(f));
+    if (contract === null) dropped += 1;
+    else {
+      // Push in lockstep so `sources[i]` is the source `payload.findings[i]` came
+      // from — the alignment a transport layer relies on to recover a source-only field.
+      projected.push(contract);
+      sources.push(f);
+    }
+  }
+  return { payload: parseFindingPayload({ findings: projected }), dropped, sources };
+}
+
+/** Project one finding, returning `null` if it throws, has no location, or fails the contract. */
+function tryProject(
+  f: EnrichedFinding,
+  scope: string,
+  location: ContractLocation | undefined,
+): ContractFinding | null {
+  if (location === undefined) return null;
+  try {
+    const parsed = ContractFindingSchema.safeParse(toContractFinding(f, scope, location));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}