npm - @afokapu/atdd-bun - Versions diffs - 0.4.0 → 0.6.0 - Mend

@afokapu/atdd-bun 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (209) hide show

package/detectors/bun_responsive_detector/checks/responsive_viewport_meta.mjs ADDED Viewed

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+// coder.bun.responsive-viewport-meta: every full HTML document declares a device-width viewport and never blocks zoom.
+import { runCheck } from "./_responsive.mjs";
+const RULE = "coder.bun.responsive-viewport-meta";
+runCheck("responsive-viewport-meta", (root, files, report) => {
+  for (const { file, text } of files) {
+    const html = text.search(/<html[\s>]/i);
+    if (file.endsWith(".css") || html === -1) continue;
+    const meta = [...text.matchAll(/<meta\b[^>]*>/gi)].find((m) => /name\s*=\s*["']viewport["']/i.test(m[0]));
+    // A head assembled from a partial (`<head>${head}</head>`, `<head>{head}</head>`) is judged where the partial is written.
+    const head = text.slice(html).match(/<head\b[^>]*>([\s\S]*?)<\/head>/i)?.[1] ?? "";
+    if (!meta && /\$\{|\{/.test(head)) continue;
+    if (!meta) { report(RULE, file, text, html, 'document has no <meta name="viewport" content="width=device-width, initial-scale=1">; phones render it as a zoomed-out desktop page'); continue; }
+    if (/content\s*=\s*\{/.test(meta[0])) continue; // a JSX expression is not statically known; its presence is enough
+    const content = meta[0].match(/content\s*=\s*["']([^"']*)["']/i)?.[1] ?? "";
+    if (!/width\s*=\s*device-width/i.test(content)) report(RULE, file, text, meta.index, `viewport content "${content}" does not set width=device-width`);
+    const scale = content.match(/maximum-scale\s*=\s*([\d.]+)/i);
+    if (/user-scalable\s*=\s*(no|0)\b/i.test(content) || (scale && Number(scale[1]) < 2)) report(RULE, file, text, meta.index, `viewport content "${content}" blocks zoom (user-scalable=no or maximum-scale below 2), which fails users who need to enlarge text`);
+  }
+});

package/detectors/bun_responsive_detector/detect.mjs ADDED Viewed

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+// FAMILY validator: bun_responsive_detector
+// Runs each member check (checks/*.mjs) VERBATIM as a subprocess and merges their
+// RAW v1.1 reports into one — ONE implementation realizing a family of rule_ids
+// (the Core pattern; see frontend.workspace.runtime's families).
+//
+// Members are spawned with `process.execPath`, which under this provider IS the
+// bun binary, so a member may be authored as .mjs OR .ts with no build step.
+// Files whose name begins with `_` are skipped: they are shared helpers, not
+// checks. (The node-runtime families have no such convention because each of
+// their checks re-implements its own walker; this provider factors the walk into
+// lib/scan.mjs instead.)
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+const reportPath = process.env.ATDD_VIOLATIONS_REPORT;
+if (!reportPath) {
+  process.stderr.write("family: ATDD_VIOLATIONS_REPORT not set\n");
+  process.exit(2);
+}
+const checks = readdirSync(join(here, "checks"))
+  .filter((f) => (f.endsWith(".mjs") || f.endsWith(".ts")) && !f.startsWith("_"))
+  .sort();
+const td = mkdtempSync(join(tmpdir(), "atdd-bun-fam-"));
+const out = [];
+for (const c of checks) {
+  const rep = join(td, c + ".json");
+  try {
+    execFileSync(process.execPath, [join(here, "checks", c)], {
+      env: { ...process.env, ATDD_VIOLATIONS_REPORT: rep },
+      stdio: ["ignore", "ignore", "inherit"],
+    });
+  } catch {
+    /* a member may exit non-zero; still try to read its report */
+  }
+  try {
+    out.push(...JSON.parse(readFileSync(rep, "utf8")).violations);
+  } catch {}
+}
+writeFileSync(reportPath, JSON.stringify({ violations: out }, null, 2), "utf8");
+process.stderr.write("family bun_responsive_detector: " + out.length + " violation(s)\n");
+process.exit(0);

package/detectors/bun_responsive_detector/fixtures/clean/public/index.html ADDED Viewed

@@ -0,0 +1,9 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Shop</title>
+</head>
+<body><main class="page">Shop</main></body>
+</html>

package/detectors/bun_responsive_detector/fixtures/clean/src/app.css ADDED Viewed

@@ -0,0 +1,13 @@
+:root {
+  --page: 1200px;
+}
+.page {
+  width: 100%;
+  max-width: 1200px;
+  min-width: 0;
+  border: 1px solid currentColor;
+}
+.sidebar { width: 280px; }
+@media (min-width: 768px) { .page { padding: 2rem; } }
+@media (max-width: 767.98px) { .sidebar { width: 100%; } }
+@media (min-width: 64em) { .page { margin: 0 auto; } }

package/detectors/bun_responsive_detector/fixtures/clean/src/document.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import { head } from "./head";
+export const page = (body: string) => `<!doctype html>
+<html lang="en">
+<head>${head}</head>
+<body>${body}</body>
+</html>`;

package/detectors/bun_responsive_detector/fixtures/clean/src/fragment.html ADDED Viewed

	@@ -0,0 +1 @@
1	+ <section class="card"><p>No document here, so no viewport meta is required.</p></section>

package/detectors/bun_responsive_detector/fixtures/clean/src/head.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export const head = `<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">`;

package/detectors/bun_responsive_detector/fixtures/clean/src/layout.tsx ADDED Viewed

@@ -0,0 +1,8 @@
+export function Layout(props: { children: unknown }) {
+  return (
+    <html lang="en">
+      <head><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5" /></head>
+      <body style={{ maxWidth: 1200, width: "100%" }}>{props.children}</body>
+    </html>
+  );
+}

package/detectors/bun_responsive_detector/fixtures/clean/src/range.css ADDED Viewed

@@ -0,0 +1,3 @@
+@media (width >= 768px) { .page { padding: 1rem; } }
+@media (1024px <= width) { .page { margin: 0 auto; } }
+.narrow { width: 20rem; }

package/detectors/bun_responsive_detector/fixtures/clean/src/viewport-expression.tsx ADDED Viewed

@@ -0,0 +1,5 @@
+const VIEWPORT = "width=device-width, initial-scale=1";
+export function Shell() {
+  return <html lang="en"><head><meta name="viewport" content={VIEWPORT} /></head><body /></html>;
+}

package/detectors/bun_responsive_detector/fixtures/dirty/public/fixed-viewport.html ADDED Viewed

@@ -0,0 +1,5 @@
+<!doctype html>
+<html>
+<head><meta name="viewport" content="width=1024"></head>
+<body>Fixed viewport</body>
+</html>

package/detectors/bun_responsive_detector/fixtures/dirty/public/no-meta.html ADDED Viewed

@@ -0,0 +1,5 @@
+<!doctype html>
+<html>
+<head><title>No viewport</title></head>
+<body>Desktop only</body>
+</html>

package/detectors/bun_responsive_detector/fixtures/dirty/public/no-zoom.html ADDED Viewed

@@ -0,0 +1,5 @@
+<!doctype html>
+<html>
+<head><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"></head>
+<body>Zoom blocked</body>
+</html>

package/detectors/bun_responsive_detector/fixtures/dirty/public/scale.html ADDED Viewed

@@ -0,0 +1,5 @@
+<!doctype html>
+<html>
+<head><meta name="viewport" content="width=device-width, maximum-scale=1.5"></head>
+<body></body>
+</html>

package/detectors/bun_responsive_detector/fixtures/dirty/src/app.css ADDED Viewed

@@ -0,0 +1,4 @@
+.page { width: 960px; }
+.panel { min-width: 480px; }
+@media (min-width: 900px) { .page { width: 100%; } }
+@media (max-width: 600px) { .panel { min-width: 0; } }

package/detectors/bun_responsive_detector/fixtures/dirty/src/render.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export const page = () => `<!doctype html>
2	+ <html lang="en"><head><title>No viewport</title></head><body></body></html>`;

package/detectors/bun_responsive_detector/fixtures/dirty/src/units.css ADDED Viewed

@@ -0,0 +1,3 @@
+.wide { width: 40rem; }
+@media (width >= 900px) { .wide { width: 100%; } }
+@media screen and (600px <= width) { .wide { color: currentColor; } }

package/detectors/bun_responsive_detector/fixtures/dirty/src/wide.tsx ADDED Viewed

@@ -0,0 +1,3 @@
+export function Wide() {
+  return <div style={{ width: 1024 }}>Too wide</div>;
+}

package/detectors/bun_tester_discipline_detector/checks/t_acceptance_resolves.mjs CHANGED Viewed

@@ -48,9 +48,9 @@ function planFiles(dir, excludes) {
 // and WMBT documents, and a reference is resolvable if the plan states that URN
 // anywhere. Over-accepting here is safe — the failure this rule exists to catch is a
 // reference to something the plan never mentions at all.
-function declaredUrns(croot, excludes) {
+function declaredUrns(croot, excludes, planRoot) {
   const urns = new Set();
-  for (const f of planFiles(join(croot, "plan"), excludes)) {
+  for (const f of planFiles(join(croot, planRoot), excludes)) {
     for (const m of read(f).matchAll(/\b((?:acc|wmbt):[a-z0-9][\w.-]*(?::[\w.-]+)?)/gi)) {
       urns.add(m[1]);
     }
@@ -58,13 +58,13 @@ function declaredUrns(croot, excludes) {
   return urns;
 }
-function consumerRoots(root, excludes) {
+function consumerRoots(root, excludes, planRoot) {
   const roots = [];
   (function rec(d) {
     let st;
     try { st = statSync(d); } catch { return; }
     if (!st.isDirectory()) return;
-    try { if (statSync(join(d, "plan")).isDirectory()) { roots.push(d); return; } } catch {}
+    try { if (statSync(join(d, planRoot)).isDirectory()) { roots.push(d); return; } } catch {}
     let entries;
     try { entries = readdirSync(d).sort(); } catch { return; }
     for (const n of entries) if (!excludes.includes(n)) rec(join(d, n));
@@ -79,10 +79,11 @@ if (!reportPath) {
 }
 const excludes = [...DEFAULT_EXCLUDES, ...parseJsonEnv("ATDD_SCAN_EXCLUDES", [])];
 const violations = [];
+const planRoot = process.env.ATDD_PLAN_ROOT || "plan";
 for (const root of parseJsonEnv("ATDD_SCAN_ROOTS", [])) {
-  for (const croot of consumerRoots(root, excludes)) {
-    const declared = declaredUrns(croot, excludes);
+  for (const croot of consumerRoots(root, excludes, planRoot)) {
+    const declared = declaredUrns(croot, excludes, planRoot);
     if (!declared.size) continue;          // nothing declared: nothing to resolve against
     for (const file of walkTests(croot, excludes)) {
       const H = parseHeader(read(file));

package/detectors/htmx_e2e_detector/atdd.implementation.yaml ADDED Viewed

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+kind: implementation
+subtype: validator
+implementation_id: htmx_e2e_detector
+targets_workspace: atdd.workspace.bun
+contract_version: 1.1.0
+emits_rule_ids:
+- tester.htmx.e2e-spec-naming
+- tester.htmx.journey-binding-header
+- tester.htmx.journey-urn-format
+- tester.htmx.journey-layer-assembly
+- tester.htmx.journey-no-acceptance-marker
+- tester.htmx.e2e-binds-declared-subject
+- tester.htmx.covered-train-is-routed
+- tester.htmx.train-e2e-coverage
+- tester.htmx.exposed-journey-e2e-coverage
+- tester.htmx.presentation-smoke-coverage
+- tester.htmx.a11y-harness
+- tester.htmx.visual-harness
+- tester.htmx.responsive-harness
+- tester.htmx.responsive-journey-coverage
+entrypoint: detect.mjs
+report: detect.mjs
+realizes_convention:
+# The Bun/htmx browser tester: Playwright specs (*.e2e.ts), their bindings to plan/, and the
+# harnesses they must use. Ported from frontend.extension.tester.vite, strict throughout.
+- tester.htmx.e2e-spec-naming
+- tester.htmx.journey-binding-header
+- tester.htmx.journey-urn-format
+- tester.htmx.journey-layer-assembly
+- tester.htmx.journey-no-acceptance-marker
+- tester.htmx.e2e-binds-declared-subject
+- tester.htmx.covered-train-is-routed
+- tester.htmx.train-e2e-coverage
+- tester.htmx.exposed-journey-e2e-coverage
+- tester.htmx.presentation-smoke-coverage
+- tester.htmx.a11y-harness
+- tester.htmx.visual-harness
+- tester.htmx.responsive-harness
+- tester.htmx.responsive-journey-coverage

package/detectors/htmx_e2e_detector/checks/_e2e.mjs ADDED Viewed

@@ -0,0 +1,98 @@
+// Shared model for the htmx_e2e_detector family: browser (Playwright) specs and the plan they cover.
+//
+// A BROWSER SPEC is a `*.e2e.ts` file. It is named that way, not `*.spec.ts`, because `bun test`
+// collects every `*.spec.*` and `*.test.*` file and would try to run a Playwright spec with the
+// wrong runner. A JOURNEY SPEC is a browser spec, or any test file whose header comments carry a
+// journey marker (`// Train:`, `// Journey:`, `// URN: test:train|journey:`), so a misnamed one is still judged.
+//
+// A journey spec binds to ONE plan subject through its header, and every test URN it carries
+// must agree with that binding:
+//
+//   // Train: train:orders:place-order          or   // Journey: journey:buy
+//   // Layer: assembly
+//   test:train:orders:place-order:E2E-001-places-an-order   (harness E2E | SMOKE | A11Y | VIS | RESP)
+import { basename, join, resolve } from "node:path";
+import { walk, readText, maskLiteralsAndComments } from "../../../lib/scan.mjs";
+import { loadPlan } from "../../../src/planner-kernel.ts";
+export const TRAIN_ID = /^train:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/;
+export const JOURNEY_ID = /^journey:[a-z][a-z0-9-]*$/;
+export const HARNESSES = ["E2E", "SMOKE", "A11Y", "VIS", "RESP"];
+const URN_STRICT = /^test:(train:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*|journey:[a-z][a-z0-9-]*):(E2E|SMOKE|A11Y|VIS|RESP)-\d{3}-[a-z0-9][a-z0-9-]*$/;
+const URN_CANDIDATE = /test:(?:train|journey):[A-Za-z0-9:_-]+/g;
+const SPEC_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"]);
+const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+export const E2E_RE = /\.e2e\.[cm]?[jt]sx?$/;
+const header = (text, name) => { const m = text.match(new RegExp(`^[ \\t]*//[ \\t]*${name}:[ \\t]*(\\S+)[ \\t]*$`, "m")); return m ? { value: m[1], line: lineOf(text, m.index) } : null; };
+export const lineOf = (text, index) => text.slice(0, index).split("\n").length;
+export const firstLine = (text) => (text.split(/\r?\n/)[0] || "").trim();
+/** Everything a check needs to know about one test file. */
+export function parseSpec(file, text) {
+  const train = header(text, "Train"), journey = header(text, "Journey");
+  const urns = [...text.matchAll(URN_CANDIDATE)].map((m) => ({ urn: m[0], index: m.index, valid: URN_STRICT.test(m[0]) }));
+  const harnesses = new Set(urns.filter((u) => u.valid).map((u) => u.urn.split(":").at(-1).split("-")[0]));
+  const name = basename(file).toLowerCase();
+  if (/(^|[.-])a11y([.-]|$)/.test(name)) harnesses.add("A11Y");
+  if (/(^|[.-])(visual|vis)([.-]|$)/.test(name)) harnesses.add("VIS");
+  if (/(^|[.-])(responsive|resp)([.-]|$)/.test(name)) harnesses.add("RESP");
+  if (/(^|[.-])smoke([.-]|$)/.test(name)) harnesses.add("SMOKE");
+  const binding = train ? { kind: "train", id: train.value, line: train.line } : journey ? { kind: "journey", id: journey.value, line: journey.line } : null;
+  const bindingCount = [...text.matchAll(/^[ \t]*\/\/[ \t]*(Train|Journey):/gm)].length;
+  return {
+    file, text, binding, bindingCount, urns, harnesses,
+    layer: header(text, "Layer"),
+    acceptance: text.match(/^[ \t]*\/\/[ \t]*(Acceptance|WMBT):[ \t]*\S/m),
+    playwright: /from\s+["']@playwright\/test["']/.test(text),
+    // A spec declares tests; a config (`defineConfig`) or a fixture module (`base.extend`) only imports the runner.
+    declaresTests: !/(^|[\\/])playwright\.config\.[cm]?[jt]s$/.test(file) && /(^|[^.\w])test(\.(describe|only|skip|fixme|fail|slow|step))?\s*\(/m.test(maskLiteralsAndComments(text)),
+    e2eNamed: E2E_RE.test(file),
+    // Outside *.e2e.ts only HEADER comments mark a journey spec; a unit test that merely mentions a
+    // journey URN in a string is not one.
+    journeyMarked: Boolean(train || journey) || /^[ \t]*\/\/[ \t]*URN:[ \t]*test:(train|journey):/m.test(text),
+  };
+}
+/** Every file a check should look at: browser specs, test files, and anything importing Playwright. */
+export function collectSpecs(roots, excludes) {
+  const out = new Map();
+  for (const root of roots) for (const file of walk(root, excludes, SPEC_EXT, true)) {
+    if (out.has(resolve(file))) continue;
+    const text = readText(file); if (text === null) continue;
+    if (E2E_RE.test(file) || TEST_RE.test(file) || /@playwright\/test/.test(text)) out.set(resolve(file), parseSpec(file, text));
+  }
+  return [...out.values()];
+}
+export const isJourneySpec = (spec) => spec.e2eNamed || spec.journeyMarked;
+/** The plan subjects a spec can bind to, read with the package's own loader. */
+export async function planOf(root) {
+  const graph = await loadPlan(root);
+  const trainArtifacts = graph.artifacts.filter((a) => a.kind === "train"), trains = new Set(trainArtifacts.map((a) => a.id));
+  const trainFiles = new Map(trainArtifacts.map((a) => [a.id, join(root, a.file)]));
+  // A train is human-facing when a person takes part in it; only those have a screen a browser spec can drive.
+  const refs = (a) => [...(Array.isArray(a.data.participants) ? a.data.participants : []), ...(Array.isArray(a.data.sequence) ? a.data.sequence.flatMap((s) => [s?.from, s?.to]) : [])].map(String);
+  const humanTrains = new Set(trainArtifacts.filter((a) => refs(a).some((r) => r.startsWith("user:"))).map((a) => a.id));
+  const interlockings = graph.artifacts.filter((a) => a.kind === "interlocking");
+  const routed = new Set(interlockings.flatMap((il) => (Array.isArray(il.data.routes) ? il.data.routes : []).map((r) => String(r?.train_id ?? ""))).filter(Boolean));
+  // A journey has a browser surface unless its entrypoint declares surfaces that exclude `frontend`.
+  const frontend = (surfaces) => !Array.isArray(surfaces) || surfaces.map(String).includes("frontend");
+  const journeys = graph.artifacts.filter((a) => a.kind === "journey").map((a) => ({ id: a.id, file: a.file, exposed: a.data?.entrypoint?.exposed === true, frontend: frontend(a.data?.entrypoint?.surfaces) }));
+  return { trains, trainFiles, humanTrains, routed, journeys: journeys.map((j) => ({ ...j, path: join(root, j.file) })), journeyIds: new Set(journeys.map((j) => j.id)), hasPlan: trains.size > 0 || journeys.length > 0 };
+}
+export { frontendConfig, DEFAULT_VIEWPORTS, DEFAULT_BREAKPOINTS } from "../../../lib/frontend.mjs";
+/** Run one check over every scan root: `judge(root, specs, plan, report)`. */
+export async function runCheck(tag, judge) {
+  const { readRoots, readExcludes, emit } = await import("../../../lib/scan.mjs");
+  const violations = [];
+  for (const root of readRoots()) {
+    const report = (rule_id, file, line, evidence, source_line = "") => violations.push({ rule_id, file, line, col: 1, evidence, source_line });
+    await judge(resolve(root), collectSpecs([root], readExcludes()), await planOf(resolve(root)), report);
+  }
+  process.stderr.write(`bun-detector[${tag}]: ${violations.length} violation(s)\n`);
+  emit(violations);
+}

package/detectors/htmx_e2e_detector/checks/_map.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "e2e_spec_naming": "tester.htmx.e2e-spec-naming",
+  "journey_binding_header": "tester.htmx.journey-binding-header",
+  "journey_urn_format": "tester.htmx.journey-urn-format",
+  "journey_layer_assembly": "tester.htmx.journey-layer-assembly",
+  "journey_no_acceptance_marker": "tester.htmx.journey-no-acceptance-marker",
+  "e2e_binds_declared_subject": "tester.htmx.e2e-binds-declared-subject",
+  "covered_train_is_routed": "tester.htmx.covered-train-is-routed",
+  "train_e2e_coverage": "tester.htmx.train-e2e-coverage",
+  "exposed_journey_e2e_coverage": "tester.htmx.exposed-journey-e2e-coverage",
+  "presentation_smoke_coverage": "tester.htmx.presentation-smoke-coverage",
+  "a11y_harness": "tester.htmx.a11y-harness",
+  "visual_harness": "tester.htmx.visual-harness",
+  "responsive_harness": "tester.htmx.responsive-harness",
+  "responsive_journey_coverage": "tester.htmx.responsive-journey-coverage"
+}

package/detectors/htmx_e2e_detector/checks/a11y_harness.mjs ADDED Viewed

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+// tester.htmx.a11y-harness: an A11Y spec runs axe and asserts, in a way that can fail, on its violations.
+import { maskLiteralsAndComments } from "../../../lib/scan.mjs";
+import { runCheck, isJourneySpec } from "./_e2e.mjs";
+// The builder may be imported under any name: `import Axe from ...` or `import { AxeBuilder as Axe } from ...`.
+const IMPORT = /import\s+(?:(\w+)|\{\s*AxeBuilder(?:\s+as\s+(\w+))?\s*\})\s+from\s+["']@axe-core\/playwright["']/;
+// The assertion must be able to fail: the violations compared with none, or with a bounded count. A tautology
+// such as `toBeGreaterThanOrEqual(0)` or `toBeDefined()` asserts nothing about the page.
+const ASSERTS = /expect\s*\([^;]*?violations[^;]*?\)\s*\.\s*(toEqual\s*\(\s*\[\s*\]\s*\)|toStrictEqual\s*\(\s*\[\s*\]\s*\)|toHaveLength\s*\(\s*0\s*\)|toBe\s*\(\s*0\s*\)|toBeLessThanOrEqual\s*\(\s*\d+\s*\)|toBeLessThan\s*\(\s*\d+\s*\))/;
+await runCheck("a11y-harness", (root, specs, plan, report) => {
+  for (const s of specs) {
+    if (!isJourneySpec(s) || !s.harnesses.has("A11Y")) continue;
+    const code = maskLiteralsAndComments(s.text), imported = s.text.match(IMPORT), builder = imported ? imported[1] ?? imported[2] ?? "AxeBuilder" : null, missing = [];
+    if (!builder) missing.push("import AxeBuilder from @axe-core/playwright");
+    else if (!new RegExp(`new\\s+${builder}\\s*\\(`).test(code) || !/\.analyze\s*\(/.test(code)) missing.push(`construct ${builder} and call .analyze()`);
+    if (!ASSERTS.test(code)) missing.push("assert that the violations are none (toEqual([]), toHaveLength(0)) or bounded (toBeLessThanOrEqual(n))");
+    if (missing.length) report("tester.htmx.a11y-harness", s.file, 1, `A11Y spec does not ${missing.join("; ")}; an accessibility check that never runs axe, or cannot fail, passes whatever the page's state`);
+  }
+});

package/detectors/htmx_e2e_detector/checks/covered_train_is_routed.mjs ADDED Viewed

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+// tester.htmx.covered-train-is-routed: a train a spec covers is selected by some interlocking route.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("covered-train-is-routed", (root, specs, plan, report) => {
+  for (const s of specs) if (isJourneySpec(s) && s.binding?.kind === "train" && plan.trains.has(s.binding.id) && !plan.routed.has(s.binding.id)) report("tester.htmx.covered-train-is-routed", s.file, s.binding.line, `${s.binding.id} is declared but no interlocking route selects it, so nothing in the application can reach what this spec exercises`);
+});

package/detectors/htmx_e2e_detector/checks/e2e_binds_declared_subject.mjs ADDED Viewed

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+// tester.htmx.e2e-binds-declared-subject: the train or journey a spec binds to is declared in plan/.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("e2e-binds-declared-subject", (root, specs, plan, report) => {
+  if (!plan.hasPlan) return;
+  for (const s of specs) {
+    if (!isJourneySpec(s) || !s.binding) continue;
+    const declared = s.binding.kind === "train" ? plan.trains.has(s.binding.id) : plan.journeyIds.has(s.binding.id);
+    if (!declared && (s.binding.kind === "train" ? TRAIN_ID : JOURNEY_ID).test(s.binding.id)) report("tester.htmx.e2e-binds-declared-subject", s.file, s.binding.line, `bound to ${s.binding.id}, which plan/ does not declare; the spec is orphaned from the plan`);
+  }
+});

package/detectors/htmx_e2e_detector/checks/e2e_spec_naming.mjs ADDED Viewed

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+// tester.htmx.e2e-spec-naming: a Playwright spec is named *.e2e.ts, so `bun test` never runs it.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("e2e-spec-naming", (root, specs, plan, report) => {
+  for (const s of specs) if (s.playwright && s.declaresTests && !s.e2eNamed) report("tester.htmx.e2e-spec-naming", s.file, 1, "imports @playwright/test but is not named *.e2e.ts; bun test collects *.test.* and *.spec.* files and would run it with the wrong runner", firstLine(s.text));
+});

package/detectors/htmx_e2e_detector/checks/exposed_journey_e2e_coverage.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// tester.htmx.exposed-journey-e2e-coverage: every exposed journey has an E2E or SMOKE browser spec bound to it.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("exposed-journey-e2e-coverage", (root, specs, plan, report) => {
+  const covered = new Set(specs.filter((s) => isJourneySpec(s) && s.binding?.kind === "journey" && (s.harnesses.has("E2E") || s.harnesses.has("SMOKE"))).map((s) => s.binding.id));
+  for (const j of plan.journeys) if (j.exposed && j.frontend && !covered.has(j.id)) report("tester.htmx.exposed-journey-e2e-coverage", j.path, 1, `exposed journey ${j.id} has no E2E or SMOKE browser spec bound by \`// Journey: ${j.id}\``);
+});

package/detectors/htmx_e2e_detector/checks/journey_binding_header.mjs ADDED Viewed

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+// tester.htmx.journey-binding-header: a journey spec binds to exactly one train or journey by a well-formed header.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+const RULE = "tester.htmx.journey-binding-header";
+await runCheck("journey-binding-header", (root, specs, plan, report) => {
+  for (const s of specs) {
+    if (!isJourneySpec(s)) continue;
+    if (!s.binding) { report(RULE, s.file, 1, "journey spec has no `// Train: train:<subject>:<slug>` or `// Journey: journey:<id>` header", firstLine(s.text)); continue; }
+    if (s.bindingCount > 1) report(RULE, s.file, s.binding.line, `journey spec declares ${s.bindingCount} \`// Train:\`/\`// Journey:\` headers; bind it to exactly one plan subject`);
+    const valid = s.binding.kind === "train" ? TRAIN_ID : JOURNEY_ID;
+    if (!valid.test(s.binding.id)) report(RULE, s.file, s.binding.line, `\`${s.binding.id}\` is not a valid ${s.binding.kind} id (${valid.source})`);
+  }
+});

package/detectors/htmx_e2e_detector/checks/journey_layer_assembly.mjs ADDED Viewed

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+// tester.htmx.journey-layer-assembly: a journey spec declares `// Layer: assembly`.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+const RULE = "tester.htmx.journey-layer-assembly";
+await runCheck("journey-layer-assembly", (root, specs, plan, report) => {
+  for (const s of specs) {
+    if (!isJourneySpec(s)) continue;
+    if (!s.layer) report(RULE, s.file, 1, "journey spec has no `// Layer:` header; it MUST be `// Layer: assembly`", firstLine(s.text));
+    else if (s.layer.value !== "assembly") report(RULE, s.file, s.layer.line, `\`// Layer: ${s.layer.value}\`: a journey spec exercises the assembled application and MUST declare Layer: assembly`);
+  }
+});

package/detectors/htmx_e2e_detector/checks/journey_no_acceptance_marker.mjs ADDED Viewed

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+// tester.htmx.journey-no-acceptance-marker: journey and acceptance identities are exclusive.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("journey-no-acceptance-marker", (root, specs, plan, report) => {
+  for (const s of specs) if (isJourneySpec(s) && s.acceptance) report("tester.htmx.journey-no-acceptance-marker", s.file, lineOf(s.text, s.acceptance.index + s.acceptance[0].search(/\S/)), `journey spec carries \`// ${s.acceptance[1]}:\`; a journey test binds to a train or journey, an acceptance test to an Acceptance/WMBT pair, never both`);
+});

package/detectors/htmx_e2e_detector/checks/journey_urn_format.mjs ADDED Viewed

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+// tester.htmx.journey-urn-format: a journey spec carries test URNs of the canonical grammar, all for its bound subject.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+const RULE = "tester.htmx.journey-urn-format";
+await runCheck("journey-urn-format", (root, specs, plan, report) => {
+  for (const s of specs) {
+    if (!isJourneySpec(s)) continue;
+    if (!s.urns.length) { report(RULE, s.file, 1, "journey spec carries no test URN test:{train|journey}:<id>:{E2E|SMOKE|A11Y|VIS|RESP}-NNN-<slug>", firstLine(s.text)); continue; }
+    const seen = new Set(), bound = s.binding && (s.binding.kind === "train" ? TRAIN_ID : JOURNEY_ID).test(s.binding.id) ? s.binding.id : null;
+    for (const u of s.urns) {
+      if (seen.has(u.urn)) continue;
+      seen.add(u.urn);
+      if (!u.valid) { report(RULE, s.file, lineOf(s.text, u.index), `test URN \`${u.urn}\` is malformed; want test:{train|journey}:<id>:{E2E|SMOKE|A11Y|VIS|RESP}-NNN-<slug>`); continue; }
+      const subject = u.urn.slice("test:".length, u.urn.lastIndexOf(":"));
+      if (bound && subject !== bound) report(RULE, s.file, lineOf(s.text, u.index), `test URN \`${u.urn}\` names ${subject}, but the spec is bound to ${s.binding.id}`);
+    }
+  }
+});

package/detectors/htmx_e2e_detector/checks/presentation_smoke_coverage.mjs ADDED Viewed

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+// tester.htmx.presentation-smoke-coverage: every presentation component is covered by a SMOKE browser spec naming its wagon.
+import { relative, sep } from "node:path";
+import { walk } from "../../../lib/scan.mjs";
+import { runCheck, isJourneySpec } from "./_e2e.mjs";
+await runCheck("presentation-smoke-coverage", async (root, specs, plan, report) => {
+  const { readExcludes } = await import("../../../lib/scan.mjs");
+  const smoke = specs.filter((s) => isJourneySpec(s) && s.harnesses.has("SMOKE")).map((s) => relative(root, s.file));
+  for (const file of walk(root, readExcludes(), new Set([".tsx", ".jsx"]))) {
+    const parts = relative(root, file).split(sep), at = parts.lastIndexOf("presentation");
+    if (at < 1 || at === parts.length - 1) continue;
+    const wagon = parts[at - 1], token = new RegExp(`(^|[^a-z0-9])${wagon.replace(/[^a-z0-9-]/gi, "")}([^a-z0-9]|$)`, "i");
+    if (!smoke.some((path) => token.test(path))) report("tester.htmx.presentation-smoke-coverage", file, 1, `presentation component of wagon "${wagon}" has no SMOKE browser spec whose path names the wagon`);
+  }
+});

package/detectors/htmx_e2e_detector/checks/responsive_harness.mjs ADDED Viewed

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+// tester.htmx.responsive-harness: a RESP spec renders at every declared viewport and asserts no horizontal overflow.
+import { maskLiteralsAndComments } from "../../../lib/scan.mjs";
+import { runCheck, isJourneySpec, frontendConfig } from "./_e2e.mjs";
+/** The widths a spec actually renders at: literal viewport widths, or a list of widths it iterates. */
+function renderedWidths(code) {
+  const widths = new Set([...code.matchAll(/(?:setViewportSize\s*\(\s*\{|viewport\s*:\s*\{)[^}]*?width\s*:\s*(\d+)/g)].map((m) => Number(m[1])));
+  const add = (list) => { for (const n of list.split(",")) if (n.trim()) widths.add(Number(n)); };
+  for (const m of code.matchAll(/for\s*\(\s*(?:const|let|var)\s+\w+\s+of\s+\[([\d\s,]+)\]/g)) add(m[1]);
+  // A named list counts only when it is iterated; picking `VIEWPORTS[0]` renders one width, not all of them.
+  for (const m of code.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*\[([\d\s,]+)\]/g)) if (new RegExp(`(of\\s+${m[1]}\\b|\\b${m[1]}\\s*\\.\\s*(forEach|map)\\s*\\()`).test(code)) add(m[2]);
+  return widths;
+}
+/** Whether some expect() takes scrollWidth, directly or through a variable measured from it. */
+function assertsOverflow(code) {
+  const measured = [...code.matchAll(/(?:const|let|var)\s+(\w+)\s*=[^;]*scrollWidth/g)].map((m) => m[1]);
+  return [...code.matchAll(/expect\s*\(([^;]*?)\)\s*\./g)].some((m) => /scrollWidth/.test(m[1]) || measured.some((name) => new RegExp(`\\b${name}\\b`).test(m[1])));
+}
+await runCheck("responsive-harness", (root, specs, plan, report) => {
+  const { viewports } = frontendConfig(root);
+  for (const s of specs) {
+    if (!isJourneySpec(s) || !s.harnesses.has("RESP")) continue;
+    const code = maskLiteralsAndComments(s.text), widths = renderedWidths(code), missing = viewports.filter((w) => !widths.has(w));
+    if (missing.length) report("tester.htmx.responsive-harness", s.file, 1, `RESP spec never renders at viewport width(s) ${missing.join(", ")} of the declared ${viewports.join("/")}`);
+    if (!assertsOverflow(code)) report("tester.htmx.responsive-harness", s.file, 1, "RESP spec never asserts on scrollWidth; it must fail when the page overflows the viewport horizontally");
+  }
+});

package/detectors/htmx_e2e_detector/checks/responsive_journey_coverage.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// tester.htmx.responsive-journey-coverage: every exposed journey has a RESP browser spec bound to it.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("responsive-journey-coverage", (root, specs, plan, report) => {
+  const covered = new Set(specs.filter((s) => isJourneySpec(s) && s.binding?.kind === "journey" && s.harnesses.has("RESP")).map((s) => s.binding.id));
+  for (const j of plan.journeys) if (j.exposed && j.frontend && !covered.has(j.id)) report("tester.htmx.responsive-journey-coverage", j.path, 1, `exposed journey ${j.id} has no RESP browser spec bound by \`// Journey: ${j.id}\`; nothing proves its screens work from mobile to desktop`);
+});

package/detectors/htmx_e2e_detector/checks/train_e2e_coverage.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// tester.htmx.train-e2e-coverage: every human-facing train (a `user:` takes part) has at least one browser spec bound to it.
+import { runCheck, isJourneySpec, TRAIN_ID, JOURNEY_ID, firstLine, lineOf, frontendConfig } from "./_e2e.mjs";
+await runCheck("train-e2e-coverage", (root, specs, plan, report) => {
+  const covered = new Set(specs.filter((s) => isJourneySpec(s) && s.binding?.kind === "train").map((s) => s.binding.id));
+  for (const train of [...plan.humanTrains].sort()) if (!covered.has(train)) report("tester.htmx.train-e2e-coverage", plan.trainFiles.get(train), 1, `${train} has no browser spec bound by \`// Train: ${train}\`; the journey it declares can regress with nothing turning red`);
+});

package/detectors/htmx_e2e_detector/checks/visual_harness.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// tester.htmx.visual-harness: a VIS spec compares a screenshot.
+import { maskLiteralsAndComments } from "../../../lib/scan.mjs";
+import { runCheck, isJourneySpec } from "./_e2e.mjs";
+await runCheck("visual-harness", (root, specs, plan, report) => {
+  for (const s of specs) if (isJourneySpec(s) && s.harnesses.has("VIS") && !/\.(toHaveScreenshot|toMatchSnapshot)\s*\(/.test(maskLiteralsAndComments(s.text))) report("tester.htmx.visual-harness", s.file, 1, "VIS spec never calls toHaveScreenshot() or toMatchSnapshot(); a visual spec that compares no screenshot performs no visual regression");
+});