@binclusive/a11y 0.1.0

package/src/commands.ts

@@ -0,0 +1,314 @@
+/**
+ * The local "scan → contract → learn" loop, as filesystem operations.
+ *
+ * Each exported command is a thin IO shell around the pure layers
+ * (`detect-stack`, `contract`, `agents-block`): read disk → compute → write
+ * disk. The pure pieces are what the tests exercise; this module is what the
+ * CLI calls. Nothing here ever writes a secret into `binclusive.json`.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractBlock, renderBlock, slugify, spliceBlock } from "./agents-block";
+import { collectTsx } from "./collect";
+import {
+  type Contract,
+  defaultEnforcement,
+  emptyDeclarations,
+  type LearnedRule,
+  parseContract,
+  type Stack,
+  serializeContract,
+} from "./contract";
+import { detectStack } from "./detect-stack";
+import { resolveComponents } from "./resolve-components";
+import { type SuggestResult, suggestComponentMap } from "./suggest";
+import { ownAliasMatcherFor } from "./tsconfig-aliases";
+
+/** The committed contract file name, and the two managed-block targets. */
+export const CONTRACT_FILE = "binclusive.json";
+export const BLOCK_TARGETS = ["AGENTS.md", "CLAUDE.md"] as const;
+
+/** Read a UTF-8 file, or `null` if it doesn't exist. */
+async function readMaybe(path: string): Promise<string | null> {
+  if (!existsSync(path)) return null;
+  return readFile(path, "utf8");
+}
+
+/**
+ * Load and boundary-parse the contract at `dir/binclusive.json`. Returns `null`
+ * when the file is absent; THROWS (loud) when present-but-malformed — a broken
+ * committed contract must never be silently overwritten.
+ */
+export async function loadContract(dir: string): Promise<Contract | null> {
+  const text = await readMaybe(join(dir, CONTRACT_FILE));
+  if (text === null) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `binclusive.json is not valid JSON: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+  return parseContract(raw);
+}
+
+/**
+ * Merge a freshly-detected stack over the customer's existing one so a re-`init`
+ * refreshes what detection KNOWS without clobbering a manual override.
+ *
+ * `framework` and `language` are hard signals (deps + tsconfig) — the detected
+ * value always wins. `router` and `designSystem` are the soft, overridable
+ * fields: detection NEVER downgrades a specific committed value to its generic
+ * fallback (`null` router / `"custom"` design system). So a customer who hand-set
+ * `designSystem: "@acme/ui"` keeps it even on a scan where nothing resolves,
+ * while a real detection (`@mui/material`) still refreshes a stale value.
+ */
+function mergeStack(detected: Stack, existing: Stack | undefined): Stack {
+  if (existing === undefined) return detected;
+  return {
+    framework: detected.framework,
+    language: detected.language,
+    router: detected.router ?? existing.router,
+    designSystem:
+      detected.designSystem === "custom" ? existing.designSystem : detected.designSystem,
+  };
+}
+
+/**
+ * The default enforcement policy for a fresh contract. The corpus left the engine
+ * (ADR 0041 §G), so there is no frequency signal to auto-select which SCs block —
+ * a fresh contract blocks nothing by default and the team opts SCs into `block`
+ * explicitly. Impact still gates via the impact-gate; enforcement is the
+ * per-SC override on top of it.
+ */
+function defaultContractEnforcement(): ReturnType<typeof defaultEnforcement> {
+  return defaultEnforcement([], []);
+}
+
+/**
+ * Write the managed block into every target file (`AGENTS.md`, `CLAUDE.md`),
+ * creating the file when absent and preserving all content outside the markers
+ * when present. Returns the list of written file paths.
+ */
+async function writeBlockTargets(dir: string, contract: Contract): Promise<string[]> {
+  const block = renderBlock(contract);
+  const written: string[] = [];
+  for (const name of BLOCK_TARGETS) {
+    const path = join(dir, name);
+    const existing = await readMaybe(path);
+    const next = spliceBlock(existing, block);
+    if (next !== existing) {
+      await writeFile(path, next, "utf8");
+    }
+    written.push(path);
+  }
+  return written;
+}
+
+/** Options for {@link init}. */
+export interface InitOptions {
+  /**
+   * When `true` (the `--suggest` flag), scaffold the `components` map: guess a
+   * host for each unresolved design-system wrapper from its NAME and merge the
+   * guesses into the written contract for the user to review. Absent/`false` →
+   * plain `init`: no guessed map, behavior byte-for-byte unchanged.
+   */
+  readonly suggest?: boolean;
+}
+
+/** The result of `init`, for the CLI to report. */
+export interface InitResult {
+  readonly contract: Contract;
+  readonly contractPath: string;
+  readonly blockPaths: readonly string[];
+  readonly preservedLearned: number;
+  /**
+   * The component-map suggestions, present ONLY when `init` ran with
+   * `suggest: true` (the `--suggest` flag). `null` for a plain `init`, so the
+   * default behavior — and its output — is byte-for-byte unchanged. When
+   * present, the guessed hosts are ALSO merged into the written contract's
+   * `declarations.components` (existing manual entries win on conflict).
+   */
+  readonly suggestions: SuggestResult | null;
+}
+
+/**
+ * `init [dir]`: detect the stack, then write `binclusive.json` and refresh the
+ * managed block in the target files. If a contract already exists, EVERYTHING
+ * the customer declared is PRESERVED — `learned[]`, `enforcement`, and the
+ * escape-hatch `declarations` (`components` / `injectsChildren` / `ignore`).
+ * Only the auto-derived `stack` is refreshed. Re-running init must never clobber
+ * the team's accumulated rules, policy, or manual declarations.
+ *
+ * The one auto-derived field — `stack` — is also non-clobbering for the parts a
+ * customer can override: `detectStack` reads disk, but a hand-set `designSystem`
+ * or `router` is re-detected the same way it was first detected, so a stable
+ * repo yields a stable stack. (Manual stack overrides survive because they are
+ * the detector's own output; a re-init re-derives identical values.)
+ */
+export async function init(dir: string, opts: InitOptions = {}): Promise<InitResult> {
+  const tsxFiles = await collectTsx(dir);
+  const stack = detectStack(dir, tsxFiles);
+
+  const existing = await loadContract(dir);
+  const baseDeclarations = existing?.declarations ?? emptyDeclarations();
+
+  // `--suggest` scaffolds the `components` map: guess a host for each genuine
+  // unknown (declare-bucket) wrapper from its name, for the user to review. The
+  // guessed hosts are merged UNDER any the customer already declared — a manual
+  // entry always wins (it was a deliberate decision; a guess is not).
+  let suggestions: SuggestResult | null = null;
+  let declarations = baseDeclarations;
+  if (opts.suggest === true) {
+    // Resolve against the EXISTING declared map so already-declared wrappers
+    // don't reappear as declare-bucket candidates to re-suggest.
+    const { resolutions } = resolveComponents(tsxFiles, baseDeclarations.components);
+    suggestions = suggestComponentMap(resolutions, {
+      isOwnAlias: ownAliasMatcherFor(dir).isOwnAlias,
+      designSystem: stack.designSystem,
+    });
+    const guessed: Record<string, string> = {};
+    for (const s of suggestions.suggestions) guessed[s.name] = s.host;
+    declarations = {
+      ...baseDeclarations,
+      // Manual entries last so they OVERRIDE a guess for the same name.
+      components: { ...guessed, ...baseDeclarations.components },
+    };
+  }
+
+  const contract: Contract = {
+    version: 1,
+    stack: mergeStack(stack, existing?.stack),
+    enforcement: existing?.enforcement ?? defaultContractEnforcement(),
+    learned: existing?.learned ?? [],
+    declarations,
+  };
+
+  const contractPath = join(dir, CONTRACT_FILE);
+  await writeFile(contractPath, serializeContract(contract), "utf8");
+  const blockPaths = await writeBlockTargets(dir, contract);
+
+  return {
+    contract,
+    contractPath,
+    blockPaths,
+    preservedLearned: existing?.learned.length ?? 0,
+    suggestions,
+  };
+}
+
+/** Inputs for `learn`, already parsed from CLI flags. */
+export interface LearnInput {
+  readonly rule: string;
+  readonly wcag: readonly string[];
+  readonly fix: string | null;
+  readonly source: string;
+}
+
+/**
+ * Append a learned rule to a contract, deduping on identical rule text (case-
+ * and whitespace-normalized). Returns the next contract and whether anything
+ * was added — pure, so the dedupe behavior is unit-testable without disk.
+ */
+export function appendLearned(
+  contract: Contract,
+  input: LearnInput,
+  addedAt: string,
+): { readonly next: Contract; readonly added: boolean } {
+  const norm = (s: string): string => s.trim().toLowerCase().replace(/\s+/g, " ");
+  const exists = contract.learned.some((r) => norm(r.rule) === norm(input.rule));
+  if (exists) return { next: contract, added: false };
+
+  const rule: LearnedRule = {
+    id: slugify(input.rule),
+    rule: input.rule,
+    wcag: [...input.wcag],
+    fix: input.fix,
+    source: input.source,
+    addedAt,
+  };
+  return { next: { ...contract, learned: [...contract.learned, rule] }, added: true };
+}
+
+/** The result of `learn`, for the CLI to report. */
+export interface LearnResult {
+  readonly added: boolean;
+  readonly id: string;
+  readonly contractPath: string;
+  readonly blockPaths: readonly string[];
+}
+
+/**
+ * `learn "<rule>" [flags]`: append the rule to `binclusive.json` `learned[]`
+ * (ISO `addedAt`, slug id) and regenerate the managed block. Requires an
+ * existing contract — `init` must run first so the stack is real, not guessed.
+ * Idempotent on identical rule text: a duplicate is a no-op (no second entry,
+ * but the block is still regenerated so the files stay in sync).
+ */
+export async function learn(dir: string, input: LearnInput): Promise<LearnResult> {
+  const contract = await loadContract(dir);
+  if (contract === null) {
+    throw new Error(`no ${CONTRACT_FILE} in ${dir} — run \`a11y-checker init\` first`);
+  }
+  const { next, added } = appendLearned(contract, input, new Date().toISOString());
+
+  const contractPath = join(dir, CONTRACT_FILE);
+  if (added) {
+    await writeFile(contractPath, serializeContract(next), "utf8");
+  }
+  const blockPaths = await writeBlockTargets(dir, next);
+  return { added, id: slugify(input.rule), contractPath, blockPaths };
+}
+
+/** A per-file drift result from `gen --check`. */
+export interface DriftEntry {
+  readonly path: string;
+  readonly status: "ok" | "drift" | "missing";
+}
+
+/** The result of `gen`. In `--check` mode `inSync` gates the CLI exit code. */
+export interface GenResult {
+  readonly check: boolean;
+  readonly inSync: boolean;
+  readonly entries: readonly DriftEntry[];
+  readonly blockPaths: readonly string[];
+}
+
+/**
+ * `gen [--check]`: regenerate the managed block from `binclusive.json`.
+ *
+ * Without `--check`: write the block into every target (preserving surrounding
+ * content) and report the paths.
+ *
+ * With `--check`: write NOTHING. Compare each target's on-disk block against a
+ * freshly-rendered one and report drift — `inSync` is false if any target's
+ * block differs or is missing. This is the CI guard against hand-editing the
+ * generated half instead of `binclusive.json`.
+ */
+export async function gen(dir: string, check: boolean): Promise<GenResult> {
+  const contract = await loadContract(dir);
+  if (contract === null) {
+    throw new Error(`no ${CONTRACT_FILE} in ${dir} — run \`a11y-checker init\` first`);
+  }
+  const fresh = renderBlock(contract);
+
+  if (!check) {
+    const blockPaths = await writeBlockTargets(dir, contract);
+    return { check: false, inSync: true, entries: [], blockPaths };
+  }
+
+  const entries: DriftEntry[] = [];
+  for (const name of BLOCK_TARGETS) {
+    const path = join(dir, name);
+    const content = await readMaybe(path);
+    const onDisk = content === null ? null : extractBlock(content);
+    const status: DriftEntry["status"] =
+      onDisk === null ? "missing" : onDisk === fresh ? "ok" : "drift";
+    entries.push({ path, status });
+  }
+  const inSync = entries.every((e) => e.status === "ok");
+  return { check: true, inSync, entries, blockPaths: entries.map((e) => e.path) };
+}

package/src/config-scan.ts

@@ -0,0 +1,177 @@
+/**
+ * The bridge between a committed `binclusive.json` and a scan.
+ *
+ * `scan` is config-OPTIONAL: with no contract it behaves exactly as before.
+ * This module is what makes it config-AWARE when a contract IS present — it
+ * finds the nearest contract at or above the scanned files, and turns the
+ * customer's escape-hatch declarations + enforcement policy into the small,
+ * pure predicates `scan` applies:
+ *
+ *   - `ignore` globs   -> drop matching files before they are ever linted
+ *   - `ignore` rule ids -> drop findings for a disabled rule ("off")
+ *   - `enforcement`     -> tag each surviving finding `block` vs `warn`
+ *
+ * Everything here is a pure function of the contract + a path/rule id, so the
+ * scan stays deterministic and the behavior is unit-testable without disk.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { type Contract, parseContract } from "./contract";
+
+/** The committed contract file name — single source, shared with `commands.ts`. */
+const CONTRACT_FILE = "binclusive.json";
+
+/**
+ * Walk UP from `dir` (inclusive) to the nearest ancestor holding a
+ * `binclusive.json`, load + boundary-parse it, and return the contract — or
+ * `null` when none is found (the zero-config case). A present-but-malformed
+ * contract THROWS via `parseContract`: a broken committed config must surface,
+ * not be silently ignored mid-scan.
+ *
+ * This is the package-up rule the rest of the toolchain uses: a scan pointed at
+ * a nested `src/` still picks up the app's contract one or more levels above.
+ */
+export function findContractFrom(dir: string): Contract | null {
+  let cur = dir;
+  for (;;) {
+    const path = join(cur, CONTRACT_FILE);
+    if (existsSync(path)) {
+      const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+      return parseContract(raw);
+    }
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+/**
+ * Given a set of absolute file paths, find the contract that governs them by
+ * walking up from their longest common directory. Returns `null` for an empty
+ * set or when no contract exists at or above the files.
+ */
+export function contractForFiles(filePaths: readonly string[]): Contract | null {
+  if (filePaths.length === 0) return null;
+  return findContractFrom(commonBaseDir(filePaths));
+}
+
+/**
+ * Longest common directory of the given absolute paths. Shared by the scan
+ * (as ESLint's `cwd`, so targets fall inside the flat-config base path —
+ * otherwise ESLint silently reports "outside of base path" and yields zero
+ * findings) and by contract find-up (the dir to walk up from). Falls back to
+ * `process.cwd()` for empty input; root `sep` when the paths share no prefix.
+ */
+export function commonBaseDir(paths: readonly string[]): string {
+  if (paths.length === 0) return process.cwd();
+  const segmentLists = paths.map((p) => dirname(p).split(sep));
+  const first = segmentLists[0] ?? [];
+  const common: string[] = [];
+  for (let i = 0; i < first.length; i++) {
+    const seg = first[i];
+    if (segmentLists.every((segs) => segs[i] === seg)) common.push(seg);
+    else break;
+  }
+  const joined = common.join(sep);
+  return joined === "" ? sep : joined;
+}
+
+/**
+ * Compile one `ignore` glob into a matcher. Supported, deliberately small, glob
+ * vocabulary (these are file-skip patterns, not a full shell glob):
+ *
+ *   - `**` matches across path separators (any depth)
+ *   - `*`  matches within a single path segment (no separator)
+ *   - `?`  matches one non-separator character
+ *
+ * Anchored with `(^|/)…$`, so a no-`/` pattern matches the BASENAME at any
+ * depth (`*.test.tsx` matches `a/b/x.test.tsx`) and a `/`-bearing pattern
+ * matches a path suffix (`src/legacy/*`, `**​/generated/**`). Everything outside
+ * the glob tokens is escaped, so `.` is literal — what you want for a filename.
+ */
+function globToRegExp(glob: string): RegExp {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**` → any chars incl. separator. Swallow a trailing `/` so
+        // `**/x` also matches `x` at the root, not just `dir/x`.
+        out += "[^]*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        out += "[^/]*"; // single-segment wildcard
+      }
+    } else if (c === "?") {
+      out += "[^/]";
+    } else if (c !== undefined && /[.+^${}()|[\]\\]/.test(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c ?? "";
+    }
+  }
+  return new RegExp(`(^|/)${out}$`);
+}
+
+/**
+ * A reusable file-skip predicate built from the `ignore` globs. Patterns are
+ * matched against the path with `/` separators (normalized from the OS sep) so
+ * the same contract behaves identically on every platform. Rule-id entries in
+ * `ignore` are NOT file globs — they are filtered out here (a rule id has no
+ * path separator and is handled by {@link ignoredRuleIds}).
+ */
+export function fileIgnoreMatcher(ignore: readonly string[]): (filePath: string) => boolean {
+  // A jsx-a11y rule id (e.g. `alt-text`, `jsx-a11y/alt-text`) is not a file
+  // glob; only treat an entry as a glob if it looks like a path pattern.
+  const globs = ignore.filter(isFileGlob).map(globToRegExp);
+  if (globs.length === 0) return () => false;
+  return (filePath: string): boolean => {
+    const norm = filePath.split(sep).join("/");
+    return globs.some((re) => re.test(norm));
+  };
+}
+
+/**
+ * Whether an `ignore` entry is a FILE GLOB rather than a rule id. A rule id is a
+ * bare jsx-a11y name (optionally `jsx-a11y/`-prefixed) with no glob/path
+ * punctuation; anything carrying `*`, `?`, `.`, or a path separator is a glob.
+ * The two namespaces never collide because jsx-a11y ids are kebab-case words.
+ */
+function isFileGlob(entry: string): boolean {
+  if (entry.startsWith("jsx-a11y/")) return false; // explicit rule id
+  return /[*?./\\]/.test(entry);
+}
+
+/**
+ * The set of jsx-a11y rule ids to drop, normalized to the full `jsx-a11y/<id>`
+ * form so a finding's `ruleId` can be tested directly. Accepts both the bare
+ * (`alt-text`) and prefixed (`jsx-a11y/alt-text`) spellings in the contract.
+ */
+export function ignoredRuleIds(ignore: readonly string[]): ReadonlySet<string> {
+  const out = new Set<string>();
+  for (const entry of ignore) {
+    if (isFileGlob(entry)) continue; // a path glob, not a rule id
+    out.add(entry.startsWith("jsx-a11y/") ? entry : `jsx-a11y/${entry}`);
+  }
+  return out;
+}
+
+/** A finding's enforcement level, decided by the contract's policy. */
+export type EnforcementLevel = "block" | "warn";
+
+/**
+ * Decide a finding's enforcement level from its WCAG SC against the contract.
+ * A finding is `block` iff ANY of its SC is in `enforcement.block`; otherwise
+ * `warn`. With no contract the level is `block` for everything — the historical
+ * behavior where every finding gated the CLI exit code.
+ */
+export function enforcementFor(
+  wcag: readonly string[],
+  contract: Contract | null,
+): EnforcementLevel {
+  if (contract === null) return "block";
+  const block = new Set(contract.enforcement.block);
+  return wcag.some((sc) => block.has(sc)) ? "block" : "warn";
+}