@lariocpt/flawless-react 0.0.0-stage → 0.3.0

package/src/skills/spec.ts

@@ -0,0 +1,227 @@
+// The `flawless-react skills` subcommand's grammar, in one pure function.
+//
+// Two consumers need this to agree with the shipped prose, and neither of them
+// runs anything: main() dispatches on it, and `--check` parses the
+// `flawless-react skills install …` lines in the README, the skills and the
+// website so a flag that was renamed cannot survive in documentation. That is
+// also why it lives apart from cli.ts rather than inside it — a subcommand that
+// only main() understands is a subcommand the docs lint cannot see.
+//
+// Without this file, `flawless-react skills install --all` would parse as
+// entry glob = `skills` and then fail on an unknown `--install`… or worse, in a
+// docs lint, pass for the wrong reason.
+import { type FlagDoc, renderBlock } from "../cliFlags.ts";
+
+export const SKILLS_SUBCOMMAND = "skills";
+
+/** True when argv is a subcommand invocation rather than a generation run. */
+export function isSkillsArgv(argv: readonly string[]): boolean {
+  return argv[0] === SKILLS_SUBCOMMAND;
+}
+
+export type SkillsVerb = "list" | "install" | "help";
+
+export interface SkillsCommand {
+  verb: SkillsVerb;
+  /** Every skill, no menu. Implied when stdout is not a terminal. */
+  all: boolean;
+  /** Only these skills. Repeatable AND comma-separated, because it reads both ways. */
+  select: string[];
+  /** `$HOME`-scoped instead of project-scoped. */
+  global: boolean;
+  /** Overwrite a canonical file that differs from the embedded copy. */
+  force: boolean;
+  /** Copy into the compat directory instead of linking it. */
+  copy: boolean;
+}
+
+/**
+ * Flags of the `install` verb, as documentation.
+ *
+ * `--force` is deliberately NOT repeated here: it is already a run flag with the
+ * same word for the same idea (overwrite what a run would otherwise keep), so
+ * listing it twice would give the inventory two entries for one spelling.
+ */
+export const SKILL_FLAGS: readonly FlagDoc[] = [
+  {
+    name: "--all",
+    summary: "Every skill, no menu.",
+  },
+  {
+    name: "--select",
+    value: "<names>",
+    summary: ["Only the named skills, comma-separated or", "repeated. Unknown names exit 2."],
+  },
+  {
+    name: "--global",
+    alias: "-g",
+    summary: [
+      "Install into ~/.agents/skills (and link into",
+      "~/.claude/skills) instead of the project's.",
+    ],
+  },
+  {
+    name: "--copy",
+    summary: [
+      "Copy into .claude/skills instead of linking.",
+      "Automatic when the system refuses symlinks.",
+    ],
+  },
+];
+
+/**
+ * What exists, in display order: the umbrella first, because it is the router.
+ *
+ * A literal tuple, not derived from the embedded files, so that this module —
+ * the grammar — is importable without importing the ~70 KB of markdown. main()'s
+ * parse-only surfaces (`--help`, `--flags`, `--check`) and the docs lint pay for
+ * the words only; the bytes come in with the runner. data.ts maps these names
+ * onto file contents with a Record, so the two cannot drift.
+ */
+export const SKILL_CHOICES = [
+  "flawless-react",
+  "flawless-nextjs",
+  "flawless-unit-browser",
+  "flawless-perf-harness",
+  "flawless-perf-static",
+  "flawless-a11y",
+  "flawless-react-rules",
+  "flawless-findings",
+  "flawless-e2e",
+  "flawless-load",
+  "flawless-api-fixtures",
+  "flawless-regen",
+  "flawless-api",
+  "flawless-expo",
+] as const;
+
+/** The names a `--select` may use. */
+export const SKILL_NAMES: readonly string[] = SKILL_CHOICES;
+
+const USAGE = `flawless-react skills <list|install> [options]
+
+Agent skills that teach a coding agent to drive flawless-react — the same files
+this repo lints against the CLI, embedded in the binary.
+
+  skills list                    list the embedded skills and their status
+  skills install                 on a terminal: pick which ones to install;
+                                 otherwise (piped, CI): install every one
+  skills install --all           every skill, no menu
+  skills install --select a,b    only the named skills (repeatable)
+  skills install --global        target ~/.agents/skills instead of ./.agents/skills
+  skills install --force         overwrite a SKILL.md you have edited locally
+  skills install --copy          copy into .claude/skills instead of linking it
+
+Each skill is written once, to .agents/skills/<name>/SKILL.md — the cross-client
+location Codex, Cursor and OpenCode read — and linked into
+.claude/skills/<name>, because Claude Code is the one mainstream host that does
+not read the standard path. A real directory there was not written by
+flawless-react, so it is reported and left alone: remove it by hand if you want
+the link. A locally-edited SKILL.md is refused without --force.
+
+Options for 'install':
+`;
+
+/**
+ * The `skills --help` text. `--force` and `--help` are rendered from the same
+ * table as the rest, so the left column aligns by the same rule as the main
+ * help rather than by a padEnd copied into a second place.
+ */
+export function renderSkillsHelp(): string {
+  const rows: FlagDoc[] = [
+    ...SKILL_FLAGS,
+    {
+      name: "--force",
+      alias: "-f",
+      summary: [
+        "Overwrite a SKILL.md you have edited locally.",
+        "Never deletes a .claude/skills directory.",
+      ],
+    },
+    { name: "--help", alias: "-h", summary: "Show this help." },
+  ];
+  return `${USAGE}${renderBlock(rows)}`;
+}
+
+function splitNames(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+}
+
+/**
+ * Parse the arguments AFTER the `skills` word (main() strips the subcommand).
+ *
+ * Throws on anything invalid, with the message naming the offender and the
+ * choices, because "bad usage → exit 2" is only useful if it says what was bad.
+ */
+export function parseSkillsCommand(argv: readonly string[]): SkillsCommand {
+  const first = argv[0];
+  if (first === undefined || first === "help" || first === "-h" || first === "--help") {
+    return { verb: "help", all: false, select: [], global: false, force: false, copy: false };
+  }
+  if (first !== "list" && first !== "install") {
+    throw new Error(`unknown skills verb: ${first}. Available: list, install`);
+  }
+  const cmd: SkillsCommand = {
+    verb: first,
+    all: false,
+    select: [],
+    global: false,
+    force: false,
+    copy: false,
+  };
+
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i] as string;
+    if (a === "--all") cmd.all = true;
+    else if (a.startsWith("--select=")) cmd.select.push(...splitNames(a.slice("--select=".length)));
+    else if (a === "--select") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error("--select requires skill names");
+      cmd.select.push(...splitNames(v));
+    } else if (a === "--global" || a === "-g") cmd.global = true;
+    else if (a === "--force" || a === "-f") cmd.force = true;
+    else if (a === "--copy") cmd.copy = true;
+    else if (a === "-h" || a === "--help") {
+      cmd.verb = "help";
+      break;
+    } else if (a.startsWith("-")) {
+      throw new Error(`unknown flag for 'skills ${cmd.verb}': ${a}`);
+    } else {
+      throw new Error(`unexpected argument after 'skills ${cmd.verb}': ${a}`);
+    }
+  }
+
+  // `skills list --global` used to be accepted and ignored. A flag that does
+  // nothing is worse than a refusal: it reads as if the scope it names had been
+  // honoured. `list` needs no scope because it reports BOTH of them as columns, and
+  // every install flag is meaningless for it — which is why the check below is
+  // "any flag at all", not a hand-maintained subset that a new flag could slip past.
+  if (cmd.verb === "list") {
+    const ignored = [
+      cmd.all && "--all",
+      cmd.select.length > 0 && "--select",
+      cmd.global && "--global",
+      cmd.force && "--force",
+      cmd.copy && "--copy",
+    ].filter((s): s is string => s !== false);
+    if (ignored.length > 0) {
+      throw new Error(
+        `skills list takes no flags (${ignored.join(", ")}): it reports every embedded skill, with its status in both scopes`,
+      );
+    }
+    return cmd;
+  }
+
+  if (cmd.all && cmd.select.length > 0) {
+    throw new Error("--all and --select are mutually exclusive: say which you mean");
+  }
+
+  const unknown = cmd.select.filter((n) => !(SKILL_CHOICES as readonly string[]).includes(n));
+  if (unknown.length > 0) {
+    throw new Error(`unknown skill: ${unknown.join(", ")}. Available: ${SKILL_CHOICES.join(", ")}`);
+  }
+  return cmd;
+}

package/src/suiteScripts.ts

@@ -0,0 +1,110 @@
+/**
+ * The standalone suite's package.json script names and commands, in one place.
+ *
+ * Two tasks write `<outDir>/package.json` — perf-harness through
+ * scaffold/templates.ts, unit-browser through scaffold-tests/index.ts — and both
+ * used to declare `test:perf`. perf-harness said `playwright test`, unit-browser
+ * said `playwright test profile`, so which one survived depended on which task
+ * ran last. Nothing failed, which is exactly why it lasted: both commands work,
+ * and only the bytes differed by task order.
+ *
+ * Deciding which emitter wins is the wrong axis. The disagreement exists because
+ * one intent is spelled twice, so it is spelled here once instead and neither
+ * emitter keeps a private copy. Two emitters may both declare a key — they
+ * cannot disagree about it — so merge order stops being observable by
+ * construction rather than by policy. tests/core.test.ts fails if they ever do
+ * diverge again.
+ */
+export const SUITE_SCRIPT = {
+  test: "test",
+  unit: "test:unit",
+  perf: "test:perf",
+  browser: "test:browser",
+  headed: "test:headed",
+  report: "report",
+} as const;
+
+/**
+ * The same actions in Next.js mode, where the TARGET app's package.json holds
+ * them and there is no suite package.json at all.
+ *
+ * A separate map rather than a prefix of SUITE_SCRIPT, deliberately: these run
+ * different commands, not the same commands under another name — `flawless:perf`
+ * carries an explicit --config and --project that `test:perf` gets from the
+ * config it already sits beside. Deriving one from the other would encode a
+ * coincidence as a rule. The commands themselves stay in core.ts, which is the
+ * only place that knows the out dir they have to be written relative to.
+ */
+export const NEXT_SCRIPT = {
+  unit: "flawless:unit",
+  perf: "flawless:perf",
+  browser: "flawless:browser",
+  e2e: "flawless:e2e",
+  load: "flawless:load",
+  report: "flawless:report",
+} as const;
+
+/**
+ * The vitest config's filename — `.mts`, not `.ts`.
+ *
+ * Vite decides whether a config is ESM or CJS from the nearest package.json,
+ * and in Next.js mode the nearest one is the TARGET APP's, which typically has
+ * no `"type": "module"`. The emitted config is ESM, so Vite loaded it as
+ * CommonJS and warned that its own strict loader — "planned to become the
+ * default in a future major version" — will reject it. Standalone was fine only
+ * by accident, because the suite's own package.json sets `"type": "module"`.
+ *
+ * `.mts` is unambiguous wherever it sits, so the same name works in both modes
+ * and nothing has to reason about whose package.json is nearest. Auto-discovery
+ * (`vitest run --root <out>`) finds it, and so does an explicit `--config`.
+ */
+export const VITEST_CONFIG = "vitest.config.mts";
+
+export const SUITE_COMMAND = {
+  unit: "vitest run",
+  /**
+   * No positional filter, deliberately.
+   *
+   * `playwright test profile` duplicated `testDir: "./profile"` from the very
+   * config it runs under, and that duplication has already cost a release: the
+   * profile specs moved from `tests/` to `profile/`, the filter did not, and
+   * `bun run test:perf` silently selected nothing while --run-tests reported a
+   * correct suite as failing (d47abbe). Scope belongs to playwright.config.ts
+   * alone, which cannot fall out of step with itself. The browser specs are not
+   * swept up by this: they live under `browser/` with their own config.
+   */
+  perf: "playwright test",
+  browser: "playwright test --config browser/playwright.config.ts",
+  headed: "playwright test --headed",
+  report: "node ./scripts/report.mjs",
+} as const;
+
+/**
+ * The same actions in Expo mode.
+ *
+ * A separate map from NEXT_SCRIPT, for the reason NEXT_SCRIPT is separate from
+ * SUITE_SCRIPT: these run different commands, not the same commands under
+ * another name. The KEY NAMES match NEXT_SCRIPT's where the action is the same,
+ * so a project that was Next and became Expo upgrades the key rather than
+ * accumulating two namespaces.
+ *
+ * `perf` and `browser` are deliberately absent: nothing emits their targets yet,
+ * and core.ts's whole gating rule is that a script whose target does not exist is
+ * a broken promise.
+ */
+export const EXPO_SCRIPT = {
+  unit: "flawless:unit",
+  e2e: "flawless:e2e",
+  load: "flawless:load",
+  report: "flawless:report",
+} as const;
+
+/**
+ * The emitted jest config's filename — `.cjs`, not `.js`.
+ *
+ * Jest loads `jest.config.js` through `require`, which is CJS unless the nearest
+ * package.json says `"type": "module"`; in Expo mode the nearest one is the
+ * TARGET APP's, whose type we do not control. Exactly the reasoning behind
+ * VITEST_CONFIG being `.mts`.
+ */
+export const JEST_CONFIG = "jest.config.cjs";

package/src/tasks/a11yNative.ts

@@ -0,0 +1,281 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import {
+  VALID_ACCESSIBILITY_ROLES,
+  VALID_ROLES,
+  VECTOR_ICON_FAMILIES,
+} from "../analyse/nativeProps.ts";
+import type {
+  ComponentInfo,
+  ComponentTree,
+  Finding,
+  NativeA11yElement,
+  RunContext,
+  TaskResult,
+} from "../types.ts";
+import { findingsByComponent, groupFindingsByFile } from "./biomeSweep.ts";
+
+/** The sweep writes ONE aggregate, not one report per component. Declared here
+ *  and re-exported from a11yScan.ts (its historical home) so the web and native
+ *  engines cannot disagree about the file the sidecar pointer names. */
+export const A11Y_REPORT = "a11y.json";
+
+/**
+ * The native accessibility analyser — wave 5 of the Expo mode.
+ *
+ * Biome cannot be the native a11y engine: all 29 of the web task's rules are
+ * HTML/ARIA, and over 31 React Native files carrying 82 unlabelled Pressables
+ * they returned ZERO findings while finding 3/3 on the DOM offender fixture —
+ * a clean report that meant "these rules do not apply", presented as coverage.
+ * This module is the replacement: six rules over the a11y census the analysis
+ * retains for native-dialect files (NativeA11yElement), judged at task time the
+ * way perf-static judges retained ComponentInfo.
+ *
+ * Two structural properties matter more than any single rule:
+ *
+ *   - THE DENOMINATOR. The summary and the aggregate always carry how many
+ *     press targets / text inputs / icons were examined and how many rules ran,
+ *     so "0 findings" can never again be confused with "the rules do not apply".
+ *   - ZERO FALSE POSITIVES over completeness. Every rule stands down where the
+ *     source is not readable (a dynamic accessibilityLabel, a spread) — a miss
+ *     costs coverage, a guess costs a false finding. The declined rules and the
+ *     evidence live in docs/archive/backlog-completed-2026-10.md's B-16 row.
+ */
+export const NATIVE_A11Y_RULES = [
+  "a11y/unnamed-control",
+  "a11y/missing-role",
+  "a11y/textinput-unlabelled",
+  "a11y/icon-unhidden",
+  "a11y/label-text-mismatch",
+  "a11y/invalid-role",
+] as const;
+
+export interface NativeA11yStats {
+  /** Unique files behind native-dialect components — the filesScanned denominator. */
+  nativeFiles: string[];
+  /** Unique files behind dom-dialect components: counted and NAMED, never silently skipped. */
+  domDialectFiles: string[];
+  pressTargets: number;
+  textInputs: number;
+  icons: number;
+}
+
+const ICON_FAMILIES: ReadonlySet<string> = new Set(VECTOR_ICON_FAMILIES);
+
+/**
+ * Pure rule evaluation over the retained census, exported for the tests: the
+ * mutation probes re-analyse a fixture and call this directly, so they stay
+ * fast and ungated while still exercising the exact production path.
+ */
+export function nativeA11yFindings(trees: ComponentTree[]): {
+  findings: Finding[];
+  stats: NativeA11yStats;
+} {
+  const infos = collectComponents(trees);
+
+  const nativeFiles = new Set<string>();
+  const domFiles = new Set<string>();
+  // Every component analysed out of a file carries the file's whole census
+  // (the walk covers same-file siblings on purpose), so elements dedupe by
+  // their own position before any counting or judging happens.
+  const elements = new Map<string, NativeA11yElement>();
+  for (const info of infos) {
+    if (info.hostDialect === "native") {
+      nativeFiles.add(path.resolve(info.filePath));
+      for (const e of info.interactions?.a11yElements ?? []) {
+        const key = `${e.pos.file}:${e.pos.line}:${e.pos.column}`;
+        if (!elements.has(key)) elements.set(key, e);
+      }
+    } else {
+      domFiles.add(path.resolve(info.filePath));
+    }
+  }
+
+  const stats: NativeA11yStats = {
+    nativeFiles: [...nativeFiles].sort(),
+    domDialectFiles: [...domFiles].sort(),
+    pressTargets: 0,
+    textInputs: 0,
+    icons: 0,
+  };
+  const findings: Finding[] = [];
+  for (const e of elements.values()) {
+    if (e.pressable) stats.pressTargets += 1;
+    if (e.element === "TextInput") stats.textInputs += 1;
+    if (ICON_FAMILIES.has(e.element)) stats.icons += 1;
+    judge(e, findings);
+  }
+  findings.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      a.column - b.column ||
+      a.rule.localeCompare(b.rule),
+  );
+  return { findings, stats };
+}
+
+function judge(e: NativeA11yElement, out: Finding[]): void {
+  const finding = (rule: string, severity: "error" | "warn", message: string): void => {
+    out.push({
+      rule,
+      severity,
+      file: e.pos.file,
+      line: e.pos.line,
+      column: e.pos.column,
+      message,
+      source: "a11y",
+    });
+  };
+
+  // Only the PROVABLY nameless case: children that are all textless (the
+  // iconOnly proof) or absent. A pressable rendering `{building.name}` DOES
+  // announce at runtime, so label-absence there is not a finding — that
+  // restraint is what keeps this rule at zero false positives.
+  if (e.pressable && e.textless && !e.hints.ariaLabel && !e.dynamicLabel) {
+    finding(
+      "a11y/unnamed-control",
+      "error",
+      `<${e.element}> renders no text and carries no accessibilityLabel — it is silent ` +
+        `to a screen reader and unaddressable to a spec. One accessibilityLabel retires both.`,
+    );
+  }
+
+  // RN has no implicit roles: RNTL's getRole() reads the explicit prop, else
+  // "text" for Text, else "none" — and the platforms announce accordingly. RN's
+  // own <Button> is exempt for free: collectHints injects its one implicit role.
+  if (e.pressable && e.hints.role === undefined && !e.dynamicRole) {
+    finding(
+      "a11y/missing-role",
+      "error",
+      `<${e.element}> has no accessibilityRole — TalkBack and VoiceOver announce its ` +
+        `content without saying it can be activated. Add accessibilityRole="button" ` +
+        `(or the role it actually plays).`,
+    );
+  }
+
+  if (e.element === "TextInput" && !e.hints.ariaLabel && !e.dynamicLabel) {
+    finding(
+      "a11y/textinput-unlabelled",
+      "error",
+      e.hints.placeholder === undefined
+        ? `<TextInput> has no accessibilityLabel and no placeholder — the field is announced as nothing at all.`
+        : `<TextInput placeholder="${e.hints.placeholder}"> has no accessibilityLabel — a ` +
+            `placeholder is not a label: it disappears on input and is not the field's accessible name.`,
+    );
+  }
+
+  if (ICON_FAMILIES.has(e.element) && !e.hiddenFromA11y && !e.exemptAncestor) {
+    finding(
+      "a11y/icon-unhidden",
+      "warn",
+      `<${e.element}> is exposed to the accessibility tree with nothing to announce — a ` +
+        `vector icon renders a private-use glyph. Add aria-hidden, or move it inside the ` +
+        `labelled control it decorates.`,
+    );
+  }
+
+  // WCAG 2.5.3 Label in Name: voice-control users say what they SEE, and an
+  // accessibilityLabel that does not contain the visible text makes the visible
+  // words a command that activates nothing.
+  if (
+    e.hints.ariaLabel !== undefined &&
+    (e.label.kind === "text" || e.label.kind === "text-partial") &&
+    !e.hints.ariaLabel.toLowerCase().includes(e.label.value.toLowerCase())
+  ) {
+    finding(
+      "a11y/label-text-mismatch",
+      "error",
+      `accessibilityLabel "${e.hints.ariaLabel}" does not contain the visible text ` +
+        `"${e.label.value}" — voice-control users say what they see, and saying it here ` +
+        `activates nothing (WCAG 2.5.3).`,
+    );
+  }
+
+  for (const { attr, value } of e.roleLiterals ?? []) {
+    const valid = attr === "role" ? VALID_ROLES : VALID_ACCESSIBILITY_ROLES;
+    if (!valid.has(value)) {
+      finding(
+        "a11y/invalid-role",
+        "error",
+        `${attr}="${value}" is not a value React Native recognises, so the platform ` +
+          `announces no role at all — and the union widens with \`| string\`, so tsc ` +
+          `cannot catch it either.`,
+      );
+    }
+  }
+}
+
+/** The native engine behind the `a11y` task under --expo. */
+export async function runNativeA11y(ctx: RunContext): Promise<TaskResult> {
+  const reportsDir = path.join(ctx.outDir, "reports");
+  await mkdir(reportsDir, { recursive: true });
+
+  const { findings, stats } = nativeA11yFindings(ctx.trees);
+  const byFile = groupFindingsByFile(findings);
+  const written: string[] = [];
+
+  const aggregatePath = path.join(reportsDir, A11Y_REPORT);
+  const aggregate = {
+    task: "a11y",
+    engine: "native",
+    filesScanned: stats.nativeFiles.length,
+    findingCount: findings.length,
+    // The denominator that makes 0 findings distinguishable from "the rules do
+    // not apply" — the vacuous green this wave exists to kill.
+    elementsExamined: {
+      pressTargets: stats.pressTargets,
+      textInputs: stats.textInputs,
+      icons: stats.icons,
+    },
+    rulesApplied: [...NATIVE_A11Y_RULES],
+    ...(stats.domDialectFiles.length > 0 ? { domDialectFilesNotSwept: stats.domDialectFiles } : {}),
+    findingsByFile: Object.fromEntries(byFile),
+  };
+  await Bun.write(aggregatePath, `${JSON.stringify(aggregate, null, 2)}\n`);
+  written.push(aggregatePath);
+
+  for (const owner of findingsByComponent(ctx.trees, byFile)) {
+    const out = path.join(reportsDir, `${owner.tree.entry.componentName}.a11y.json`);
+    const report = {
+      component: owner.tree.entry.componentName,
+      file: owner.tree.entry.filePath,
+      findings: owner.findings,
+    };
+    await Bun.write(out, `${JSON.stringify(report, null, 2)}\n`);
+    written.push(out);
+  }
+
+  const denominator =
+    `${stats.pressTargets} press target(s), ${stats.textInputs} text input(s), ` +
+    `${stats.icons} icon(s) examined, ${NATIVE_A11Y_RULES.length} native rules`;
+  const domNote =
+    stats.domDialectFiles.length > 0
+      ? `; ${stats.domDialectFiles.length} dom-dialect file(s) NOT swept — run without --expo for those`
+      : "";
+  return {
+    id: "a11y",
+    ok: true,
+    outputs: written,
+    findings,
+    summary: `a11y: ${findings.length} finding(s) across ${stats.nativeFiles.length} file(s) — ${denominator}${domNote}`,
+  };
+}
+
+function collectComponents(trees: ComponentTree[]): ComponentInfo[] {
+  const infos: ComponentInfo[] = [];
+  const visited = new Set<ComponentTree>();
+  const seen = new Set<string>();
+  const collect = (t: ComponentTree): void => {
+    if (visited.has(t)) return;
+    visited.add(t);
+    const key = `${path.resolve(t.entry.filePath)}::${t.entry.componentName}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      infos.push(t.entry);
+    }
+    for (const child of t.children) collect(child);
+  };
+  for (const tree of trees) collect(tree);
+  return infos;
+}

package/src/tasks/a11yScan.ts

@@ -0,0 +1,67 @@
+import type { RunContext, Task, TaskResult } from "../types.ts";
+import { A11Y_REPORT, runNativeA11y } from "./a11yNative.ts";
+import { runBiomeSweep } from "./biomeSweep.ts";
+
+/** The sweep writes ONE aggregate, not one report per component. Exported so
+ *  that anything pointing a reader at it cannot name a file that is never
+ *  written — which is exactly what the inline sidecar used to do. Declared in
+ *  a11yNative.ts (both engines write it); re-exported here, its historical
+ *  import path. */
+export { A11Y_REPORT } from "./a11yNative.ts";
+
+export const a11yScan: Task = {
+  id: "a11y",
+  label: "Accessibility / web-standards scan",
+  description: "Biome a11y rules over the targeted tree (file:line); native analyser under --expo",
+  needsTree: true,
+  async run(ctx: RunContext): Promise<TaskResult> {
+    // The wave-3 shape: one TaskId, a sibling engine per platform. Biome cannot
+    // be the native engine — all 29 rules below are HTML/ARIA, and over a React
+    // Native tree they return zero while the offender fixture scores 3/3.
+    if (ctx.expo) return runNativeA11y(ctx);
+    return runBiomeSweep({
+      id: "a11y",
+      ctx,
+      rules: biomeA11yRules(),
+      categoryPrefix: "lint/a11y",
+      aggregateFile: A11Y_REPORT,
+    });
+  },
+};
+
+function biomeA11yRules(): unknown {
+  return {
+    recommended: false,
+    a11y: {
+      noAccessKey: "error",
+      noAriaUnsupportedElements: "error",
+      noAutofocus: "warn",
+      noDistractingElements: "error",
+      noHeaderScope: "error",
+      noInteractiveElementToNoninteractiveRole: "error",
+      noLabelWithoutControl: "warn",
+      noNoninteractiveElementToInteractiveRole: "error",
+      noNoninteractiveTabindex: "warn",
+      noPositiveTabindex: "warn",
+      noRedundantAlt: "warn",
+      noRedundantRoles: "error",
+      useAltText: "error",
+      useAnchorContent: "error",
+      useAriaActivedescendantWithTabindex: "error",
+      useAriaPropsForRole: "error",
+      useButtonType: "error",
+      useFocusableInteractive: "warn",
+      useHeadingContent: "error",
+      useHtmlLang: "error",
+      useIframeTitle: "error",
+      useKeyWithClickEvents: "warn",
+      useKeyWithMouseEvents: "warn",
+      useMediaCaption: "warn",
+      useValidAnchor: "warn",
+      useValidAriaProps: "error",
+      useValidAriaRole: "error",
+      useValidAriaValues: "error",
+      useValidLang: "error",
+    },
+  };
+}