@afokapu/atdd-bun 0.1.0

package/detectors/htmx_hypermedia_detector/checks/htmx_verb_endpoint_is_routed.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env bun
+// Member check: coder.htmx.verb-endpoint-is-routed  (htmx hypermedia family)
+//
+// A MUTATING htmx endpoint must be served by the Station Master surface.
+//
+// This stack's own convention says "an htmx endpoint is declared in the MARKUP, so the
+// markup is this stack's route space" (tester.htmx.verb-endpoint-coverage). That is
+// right, and it is also why the markup can mint a route space nobody planned. Measured:
+// an `hx-post="/orders/void-all"` carrying a confirm, an indicator and a passing test,
+// bound to no wagon, train or interlocking, passed EVERY gated bun+htmx rule. The button
+// posts into nothing.
+//
+// That is the parallel-route-space shape this hub already rejects elsewhere — the
+// interlocking families fail a consumer that declares reachability in a second, private
+// field instead of the declared one. htmx had the same hole with none of the teeth.
+//
+// MUTATIONS ONLY, DELIBERATELY. hx-get fetches a fragment: that is presentation, and
+// requiring every read to be routed by the Station Master would fail ordinary htmx.
+// hx-post / hx-put / hx-patch / hx-delete ADVANCE STATE, which is what a journey does,
+// so those are the ones that owe a route.
+//
+// STATIC PATHS ONLY. An endpoint built by interpolation (`/orders/${id}/void`) cannot be
+// compared to a server route by text, and guessing would report on correct code. Those
+// are skipped, exactly as the Vite family treats an unresolvable trainId as advisory
+// rather than inventing a verdict.
+//
+// NOT_APPLICABLE when no Station Master surface resolves: a consumer with no JOURNEY_MAP
+// has no journey space to be outside of.
+//
+// CONTRACT (v1.1): reads ATDD_SCAN_ROOTS / ATDD_SCAN_EXCLUDES, writes RAW violations to
+// ATDD_VIOLATIONS_REPORT, exits 0 regardless of count.
+import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const RULE = "coder.htmx.verb-endpoint-is-routed";
+const EXCLUDES = ["node_modules", "dist", "build", ".next", ".git", "_generated"];
+const SRC = /\.(ts|tsx|js|jsx|mjs|html)$/;
+const TEST = /\.(test|spec)\.[cm]?[jt]sx?$/;
+// A mutating verb bound to a STATIC path — no `${...}` interpolation.
+const MUTATING = /\bhx-(post|put|patch|delete)\s*=\s*"([^"${}]+)"/g;
+
+const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return ""; } };
+
+function parseJsonEnv(name, fallback) {
+  try { const v = JSON.parse(process.env[name] || ""); return Array.isArray(v) ? v : fallback; }
+  catch { return fallback; }
+}
+
+function walk(dir, excludes) {
+  const out = [];
+  (function rec(d) {
+    let entries;
+    try { entries = readdirSync(d).sort(); } catch { return; }
+    for (const n of entries) {
+      if (excludes.includes(n)) continue;
+      const full = join(d, n);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) rec(full);
+      else out.push(full);
+    }
+  })(dir);
+  return out;
+}
+
+// Comments masked so a path MENTIONED in prose cannot stand in for a served route.
+export function maskComments(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/(^|[^:\\])\/\/[^\n]*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
+}
+
+// The Station Master is the module DECLARING a JOURNEY_MAP — found by that claim, not by
+// filename, matching how the interlocking binding family locates it.
+export function stationMasterText(files) {
+  const parts = [];
+  for (const f of files) {
+    const t = read(f);
+    if (/\bJOURNEY_MAP\b/.test(t)) parts.push(maskComments(t));
+  }
+  return parts.length ? parts.join("\n") : null;
+}
+
+const reportPath = process.env.ATDD_VIOLATIONS_REPORT;
+if (!reportPath) {
+  process.stderr.write("htmx-check: ATDD_VIOLATIONS_REPORT not set\n");
+  process.exit(2);
+}
+const excludes = [...EXCLUDES, ...parseJsonEnv("ATDD_SCAN_EXCLUDES", [])];
+const violations = [];
+
+for (const root of parseJsonEnv("ATDD_SCAN_ROOTS", [])) {
+  const all = walk(root, excludes).filter((f) => SRC.test(f) && !TEST.test(f));
+  // Group by CONSUMER ROOT — the directory holding the Station Master — rather than
+  // judging a whole scan root at once. A scan root can hold several independent
+  // projects (this workspace's fixture trees do), and one project's JOURNEY_MAP must
+  // not be used to judge another's endpoints.
+  const stations = all.filter((f) => /\bJOURNEY_MAP\b/.test(read(f)));
+  if (!stations.length) continue;              // no journey space to be outside of
+
+  for (const stationFile of stations) {
+    const croot = stationFile.slice(0, stationFile.lastIndexOf("/"));
+    const station = maskComments(read(stationFile));
+    const files = all.filter((f) => f.startsWith(croot + "/"));
+
+  for (const file of files) {
+    const text = read(file);
+    for (const m of text.matchAll(MUTATING)) {
+      const [, verb, path] = m;
+      // Served if the Station Master names the whole path, or its DISTINCTIVE terminal
+      // segment — a pattern router rarely repeats a literal path, but it does name the
+      // action it dispatches. Matching on any segment was the first attempt and made the
+      // rule vacuous: the Station Master imports from ./src/orders/, so "orders" matched
+      // and every /orders/* endpoint was treated as routed.
+      const segments = path.split("/").filter(Boolean).filter((s) => !/^[:{]|^\d+$/.test(s));
+      const terminal = segments[segments.length - 1];
+      const named = station.includes(path) || (terminal && station.includes(terminal));
+      if (named) continue;
+      const line = text.slice(0, m.index).split(/\r?\n/).length;
+      violations.push({
+        rule_id: RULE, file, line, col: 1,
+        evidence:
+          `hx-${verb}="${path}" advances state but the Station Master surface routes nothing ` +
+          `matching it; the markup declares a route space the journey space never admitted`,
+        source_line: (text.split(/\r?\n/)[line - 1] || "").trim(),
+      });
+    }
+  }
+  }
+}
+writeFileSync(reportPath, JSON.stringify({ violations }, null, 2), "utf8");
+process.stderr.write(`htmx[verb-endpoint-is-routed]: ${violations.length} violation(s)\n`);
+process.exit(0);

package/detectors/htmx_hypermedia_detector/checks/htmx_verb_endpoint_same_origin.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+// Detector: coder.htmx.verb-endpoint-same-origin  (disposition: strict)
+//
+// An htmx verb attribute (hx-get/post/put/patch/delete) must address a
+// SAME-ORIGIN path, not a hardcoded absolute URL. htmx swaps the response body
+// straight into the DOM, so a cross-origin endpoint is both a CORS failure
+// waiting to happen and an untrusted-HTML injection point; a baked-in
+// `https://staging.example.com` is also the classic way a staging host ships to
+// production. The hypermedia control belongs to the origin that served the page.
+import { walk, readRoots, readExcludes, readText, emit, locate, SOURCE_EXT, TEMPLATE_EXT } from "../../../lib/scan.mjs";
+
+const RULE_ID = "coder.htmx.verb-endpoint-same-origin";
+const ABSOLUTE_VERB_RE = /\bhx-(get|post|put|patch|delete)\s*=\s*(['"])(https?:)?\/\/[^'"]*\2/gi;
+const EXTS = new Set([...SOURCE_EXT, ...TEMPLATE_EXT]);
+
+const violations = [];
+const excludes = readExcludes();
+for (const root of readRoots()) {
+  for (const file of walk(root, excludes, EXTS)) {
+    const text = readText(file);
+    if (!text) continue;
+    for (const m of text.matchAll(ABSOLUTE_VERB_RE)) {
+      violations.push({
+        rule_id: RULE_ID,
+        file,
+        ...locate(text, m.index),
+        evidence: `hx-${m[1].toLowerCase()} targets an absolute URL; htmx endpoints must be same-origin paths`,
+      });
+    }
+  }
+}
+process.stderr.write(`bun-detector[endpoint-not-absolute-url]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/htmx_hypermedia_detector/checks/htmx_verb_mutation_signals_progress.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+// Detector: coder.htmx.verb-mutation-signals-progress  (disposition: suppress-and-clean)
+//
+// A mutating htmx request (hx-post/put/patch/delete) must declare either
+// `hx-indicator` or `hx-disabled-elt`. htmx swaps in place with no navigation, so
+// without one of these the page is visually identical while the request is in
+// flight: the user gets no feedback and re-clicks, and a non-idempotent POST runs
+// twice. The two attributes are the declarative answers — show progress, or
+// disable the control — and one of them is required.
+//
+// GET is deliberately out of scope: a read is idempotent, so a duplicate is
+// harmless and an indicator there is a UX preference, not an obligation.
+import { walk, readRoots, readExcludes, readText, emit, locate, enclosingTag, SOURCE_EXT, TEMPLATE_EXT } from "../../../lib/scan.mjs";
+
+const RULE_ID = "coder.htmx.verb-mutation-signals-progress";
+const MUTATING_RE = /\bhx-(post|put|patch|delete)\s*=/gi;
+const SIGNALS_RE = /\bhx-(indicator|disabled-elt)\s*=/i;
+const EXTS = new Set([...SOURCE_EXT, ...TEMPLATE_EXT]);
+
+const violations = [];
+const excludes = readExcludes();
+const seen = new Set(); // one finding per element, not one per mutating verb on it
+for (const root of readRoots()) {
+  for (const file of walk(root, excludes, EXTS)) {
+    const text = readText(file);
+    if (!text) continue;
+    for (const m of text.matchAll(MUTATING_RE)) {
+      const tag = enclosingTag(text, m.index);
+      if (tag && SIGNALS_RE.test(tag.text)) continue;
+      const key = `${file}:${tag ? tag.start : m.index}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      violations.push({
+        rule_id: RULE_ID,
+        file,
+        ...locate(text, m.index),
+        evidence: `hx-${m[1].toLowerCase()} declares neither hx-indicator nor hx-disabled-elt; an in-flight mutation is invisible and gets re-submitted`,
+      });
+    }
+  }
+}
+process.stderr.write(`bun-detector[mutation-signals-progress]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/htmx_hypermedia_detector/detect.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+// FAMILY validator: htmx_hypermedia_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 htmx_hypermedia_detector: " + out.length + " violation(s)\n");
+process.exit(0);

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_fragment_escapes_interpolation/render.ts

@@ -0,0 +1,6 @@
+import { escapeHtml } from "./escape";
+
+export const orderRow = (order) =>
+  `<li class="order" id="order-${escapeHtml(order.id)}">${escapeHtml(order.title)}</li>`;
+
+export const orderList = (orders) => `<ul id="orders">${orders.map(orderRow).join("")}</ul>`;

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_swap_no_inline_handler/row.html

@@ -0,0 +1 @@
+<button hx-get="/rows/1" hx-target="#row" hx-on::after-request="this.blur()">Open</button>

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_swap_oob_carries_id/fragment.html

@@ -0,0 +1 @@
+<div id="cart-count" hx-swap-oob="true">3</div>

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_verb_destructive_confirms/delete.html

@@ -0,0 +1 @@
+<button hx-delete="/orders/7" hx-confirm="Delete order 7?" hx-indicator="#spin">Delete</button>

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_verb_endpoint_is_routed/server.ts

@@ -0,0 +1,10 @@
+// Station Master — JOURNEY_MAP is the declared journey space.
+export const JOURNEY_MAP: Record<string, string> = {
+  confirm_order: "3007-confirm-order-standard",
+};
+
+export function handle(req: Request): Response {
+  const path = new URL(req.url).pathname;
+  if (req.method === "POST" && path === "/orders/confirm") return new Response("ok");
+  return new Response("ok");
+}

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_verb_endpoint_is_routed/src/OrderRow.ts

@@ -0,0 +1,7 @@
+// The mutating affordance posts to a path the Station Master routes.
+const escapeHtml = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+   .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+export const OrderRow = (id: string) =>
+  `<li id="order-${escapeHtml(id)}"><button hx-post="/orders/confirm" hx-confirm="Confirm?" hx-indicator="#spinner">Confirm</button></li>`;

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_verb_endpoint_same_origin/panel.html

@@ -0,0 +1,3 @@
+<div hx-get="/api/orders" hx-target="#orders" hx-trigger="load">
+  <span class="loading">Loading…</span>
+</div>

package/detectors/htmx_hypermedia_detector/fixtures/clean/htmx_verb_mutation_signals_progress/form.html

@@ -0,0 +1,4 @@
+<form hx-post="/orders" hx-indicator="#spinner" hx-target="#result">
+  <input name="sku" />
+</form>
+<a hx-get="/orders/next">Next</a>

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_fragment_escapes_interpolation/render.ts

@@ -0,0 +1,3 @@
+export const orderRow = (order) => `<li class="order">${order.title}</li>`;
+
+export const orderList = (orders) => `<ul id="orders">${orders.map(orderRow).join("")}</ul>`;

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_swap_no_inline_handler/row.html

@@ -0,0 +1 @@
+<button hx-get="/rows/1" hx-target="#row" onclick="track('open')">Open</button>

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_swap_oob_carries_id/fragment.html

@@ -0,0 +1 @@
+<div class="cart-count" hx-swap-oob="true">3</div>

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_verb_destructive_confirms/delete.html

@@ -0,0 +1 @@
+<button hx-delete="/orders/7" hx-indicator="#spin">Delete</button>

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_verb_endpoint_is_routed/server.ts

@@ -0,0 +1,10 @@
+// Station Master — JOURNEY_MAP is the declared journey space.
+export const JOURNEY_MAP: Record<string, string> = {
+  confirm_order: "3007-confirm-order-standard",
+};
+
+export function handle(req: Request): Response {
+  const path = new URL(req.url).pathname;
+  if (req.method === "POST" && path === "/orders/confirm") return new Response("ok");
+  return new Response("ok");
+}

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_verb_endpoint_is_routed/src/OrderRow.ts

@@ -0,0 +1,9 @@
+// BUG: the markup mints a state-changing route the Station Master never admits.
+// The confirm and indicator satisfy the other htmx rules, and a test can exercise the
+// markup, so before this rule the button posted into nothing and everything passed.
+const escapeHtml = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+   .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+export const OrderRow = (id: string) =>
+  `<li id="order-${escapeHtml(id)}"><button hx-post="/orders/void-all" hx-confirm="Void?" hx-indicator="#spinner">Void</button></li>`;

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_verb_endpoint_same_origin/panel.html

@@ -0,0 +1,3 @@
+<div hx-get="https://staging.example.com/api/orders" hx-target="#orders">
+  <span class="loading">Loading…</span>
+</div>

package/detectors/htmx_hypermedia_detector/fixtures/dirty/htmx_verb_mutation_signals_progress/form.html

@@ -0,0 +1,3 @@
+<form hx-post="/orders" hx-target="#result">
+  <input name="sku" />
+</form>

package/detectors/htmx_tester_detector/atdd.implementation.yaml

@@ -0,0 +1,21 @@
+schema_version: 1.1.0
+kind: implementation
+subtype: validator
+implementation_id: htmx_tester_detector
+targets_workspace: atdd.workspace.bun
+contract_version: 1.1.0
+# The htmx half of the tester surface. Bun is the RUNTIME; htmx is a library layered
+# on it, and a Bun repo serving JSON wants the Bun tester rules and none of these.
+#
+# Three rules, which is what makes the package viable at all: core refuses an orphan
+# convention node, and a one-rule extension has no intra-package pair to relate.
+emits_rule_ids:
+- tester.htmx.verb-endpoint-coverage
+- tester.htmx.fragment-asserts-returned-markup
+- tester.htmx.swap-oob-asserts-destination-id
+entrypoint: detect.mjs
+report: detect.mjs
+realizes_convention:
+- tester.htmx.verb-endpoint-coverage
+- tester.htmx.fragment-asserts-returned-markup
+- tester.htmx.swap-oob-asserts-destination-id

package/detectors/htmx_tester_detector/checks/_map.json

@@ -0,0 +1,5 @@
+{
+  "t_fragment_asserts_returned_markup": "tester.htmx.fragment-asserts-returned-markup",
+  "t_verb_endpoint_coverage": "tester.htmx.verb-endpoint-coverage",
+  "t_swap_oob_asserts_destination_id": "tester.htmx.swap-oob-asserts-destination-id"
+}

package/detectors/htmx_tester_detector/checks/t_fragment_asserts_returned_markup.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+// Member check: tester.htmx.fragment-asserts-returned-markup  (htmx tester family)
+//
+// THE htmx-SPECIFIC TESTER RULE, and the one with no counterpart in any other
+// stack's tester extension.
+//
+// In a JSON API the response contract is the payload, and asserting on status plus
+// a parsed field is a complete test. In htmx the response contract IS THE MARKUP:
+// the server returns a fragment and htmx swaps it into the live DOM, so the
+// hx-attributes, the element ids the next swap targets, and the structure itself
+// are the interface. A test that asserts `expect(res.status).toBe(200)` and stops
+// has proven the route exists and NOTHING about what the user will see — including
+// whether the fragment still carries the `id` a subsequent out-of-band swap needs.
+//
+// So: a test case that exercises an HTTP response must assert on the BODY, not only
+// on the status line.
+import { runCheck, testCases, caseBody } from "../test_header.mjs";
+
+const RULE = "tester.htmx.fragment-asserts-returned-markup";
+
+// The case performs an HTTP round trip.
+const DOES_FETCH = /\b(?:fetch|request)\s*\(|\.\s*fetch\s*\(/;
+// It asserts on the status line only.
+const ASSERTS_STATUS = /expect\s*\(\s*[\w.]*\.\s*(?:status|ok|statusText)\b/;
+// It reaches the body in some form: text/json/html, or a markup assertion.
+const ASSERTS_BODY = /\.\s*(?:text|json)\s*\(\s*\)|toContain\s*\(|toMatch\s*\(|innerHTML|outerHTML|hx-[a-z]/;
+
+runCheck(RULE, (H, file, text) => {
+  const out = [];
+  for (const c of testCases(text)) {
+    const body = caseBody(text, c.line);
+    if (!DOES_FETCH.test(body)) continue;
+    if (!ASSERTS_STATUS.test(body)) continue;   // not a status-only test
+    if (ASSERTS_BODY.test(body)) continue;      // reaches the markup — fine
+    out.push({ line: c.line,
+      evidence: "htmx endpoint test asserts only on the status line; the fragment it swaps into the DOM is the contract, so assert on the markup",
+      source_line: c.text });
+  }
+  return out;
+});

package/detectors/htmx_tester_detector/checks/t_swap_oob_asserts_destination_id.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+// Member check: tester.htmx.swap-oob-asserts-destination-id  (htmx tester family)
+//
+// The tester half of `coder.htmx.swap-oob-carries-id`. That rule makes the SERVER
+// emit an id on an out-of-band element; this one makes the TEST prove the id is the
+// one the page will actually match.
+//
+// The pair matters because the failure is silent from both sides: htmx drops an oob
+// element whose id matches nothing in the document, with no error and no swap. A
+// test that asserts the response merely CONTAINS `hx-swap-oob` has confirmed the
+// server's half and nothing about the destination — which is the half that breaks
+// when a template is refactored.
+//
+// Mirrors tester.convex.interlocking-trace-binds-declared-route in shape: an
+// assertion on a runtime artefact must bind back to the declaration it came from.
+import { runCheck, testCases, caseBody } from "../test_header.mjs";
+
+const RULE = "tester.htmx.swap-oob-asserts-destination-id";
+const MENTIONS_OOB = /hx-swap-oob/;
+// An assertion that reaches the destination id: an `id=` in an expected string, or
+// a DOM lookup by id.
+const ASSERTS_ID = /id\s*=\s*["'\\]|getElementById|querySelector\s*\(\s*['"`]#|toHaveAttribute\s*\(\s*['"`]id/;
+
+runCheck(RULE, (H, file, text) => {
+  const out = [];
+  for (const c of testCases(text)) {
+    const body = caseBody(text, c.line);
+    if (!MENTIONS_OOB.test(body)) continue;
+    if (ASSERTS_ID.test(body)) continue;
+    // Name the case: the finding is per `it()`, and a report of three identical
+    // sentences makes the reader diff line numbers to tell them apart.
+    const title = (c.text.match(/["'`]([^"'`]+)["'`]/) || [])[1] || "this case";
+    out.push({ line: c.line,
+      evidence: `test case "${title}" asserts an hx-swap-oob element is present but never asserts the destination id; htmx drops an oob element that matches nothing, silently`,
+      source_line: c.text });
+  }
+  return out;
+});

package/detectors/htmx_tester_detector/checks/t_verb_endpoint_coverage.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+// Member check: tester.htmx.verb-endpoint-coverage  (htmx tester family)
+//
+// Mirrors tester.convex.interlocking-route-coverage — "every admissible route
+// declared in the guarded route space MUST have at least one end-to-end test that
+// exercises it". The declaration source differs and that is the whole adaptation:
+// Convex reads `plan/_trains/_interlockings/**/*.yaml`, because a Convex route is
+// declared in the plan. An htmx endpoint is declared IN THE MARKUP — `hx-get`,
+// `hx-post` — so the markup is this stack's route space.
+//
+// NO-OP WHEN THERE IS NO SUITE. Given a tree with markup and no test files the
+// check emits nothing, mirroring the frontend provider's design-no-op pattern: a
+// coverage rule needs both sides, and reporting every endpoint as uncovered
+// because the caller scoped the scan to source would be noise, not a finding. It
+// also keeps the persona boundary honest — a tester family must not produce
+// findings on a source-only tree.
+import { walk, readRoots, readExcludes, readText, emit, locate, SOURCE_EXT, TEMPLATE_EXT, TEST_RE } from "../../../lib/scan.mjs";
+
+const RULE = "tester.htmx.verb-endpoint-coverage";
+const VERB_ATTR = /\bhx-(?:get|post|put|patch|delete)\s*=\s*(['"])(\/[^'"]*)\1/g;
+const EXTS = new Set([...SOURCE_EXT, ...TEMPLATE_EXT]);
+
+// A path is covered when a test mentions it literally, or mentions a prefix of it
+// up to a dynamic segment — `/orders/1` covers a template `/orders/:id`.
+function covers(testText, endpoint) {
+  if (testText.includes(endpoint)) return true;
+  const stem = endpoint.replace(/\/:[^/]+/g, "/").replace(/\/+$/, "");
+  return stem.length > 1 && testText.includes(stem);
+}
+
+const violations = [];
+const excludes = readExcludes();
+for (const root of readRoots()) {
+  const endpoints = [];          // {file, path, index}
+  let suite = "";
+  let sawTest = false;
+  for (const file of walk(root, excludes, EXTS, true)) {
+    const text = readText(file);
+    if (!text) continue;
+    if (TEST_RE.test(file)) { sawTest = true; suite += "\n" + text; continue; }
+    for (const m of text.matchAll(VERB_ATTR)) {
+      endpoints.push({ file, path: m[2], index: m.index, text });
+    }
+  }
+  if (!sawTest) continue;        // no suite in this mount: nothing to measure against
+  const seen = new Set();
+  for (const e of endpoints) {
+    const key = `${e.file}:${e.path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (covers(suite, e.path)) continue;
+    violations.push({
+      rule_id: RULE, file: e.file, ...locate(e.text, e.index),
+      evidence: `htmx endpoint "${e.path}" is declared in markup but no test exercises it`,
+    });
+  }
+}
+process.stderr.write(`htmx-tester[endpoint-coverage]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/htmx_tester_detector/detect.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+// FAMILY validator: htmx_tester_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 htmx_tester_detector: " + out.length + " violation(s)\n");
+process.exit(0);

package/detectors/htmx_tester_detector/fixtures/clean/orders.test.ts

@@ -0,0 +1,23 @@
+// URN: test:orders:checkout:E040-SMOKE-001-panel
+// Acceptance: acc:orders:E040-SMOKE-001-panel
+// Phase: SMOKE
+// Layer: integration
+import { describe, it, expect } from "bun:test";
+
+describe("orders", () => {
+  // @covers acc:orders:E040-SMOKE-001-panel
+  it("serves the orders fragment with a swappable id", async () => {
+    const res = await fetch("http://localhost:3000/orders");
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('id="order-1"');
+  });
+
+  // @covers acc:orders:E040-SMOKE-002-oob
+  it("updates the cart badge out of band", async () => {
+    const res = await fetch("http://localhost:3000/orders", { method: "POST" });
+    const html = await res.text();
+    expect(html).toContain("hx-swap-oob");
+    expect(html).toContain('id="cart-count"');
+  });
+});

package/detectors/htmx_tester_detector/fixtures/clean/panel.html

@@ -0,0 +1,7 @@
+<!-- URN: component:orders:checkout:panel:frontend:presentation -->
+<!-- Tested-By: -->
+<!-- - test:orders:checkout:E040-SMOKE-001-panel -->
+<!-- Runtime: browser -->
+<!-- Purpose: the orders panel htmx swaps into -->
+<div hx-get="/orders" hx-target="#orders" hx-indicator="#spin"></div>
+<button hx-post="/orders" hx-indicator="#spin">Add</button>

package/detectors/htmx_tester_detector/fixtures/dirty/orders.test.ts

@@ -0,0 +1,20 @@
+// URN: test:orders:checkout:E041-SMOKE-001
+// Acceptance: acc:orders:E041-SMOKE-001
+// Phase: SMOKE
+// Layer: integration
+import { describe, it, expect } from "bun:test";
+
+describe("orders", () => {
+  it("serves the orders fragment", async () => {
+    const res = await fetch("http://localhost:3000/orders");
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("order");
+  });
+
+  it("updates the badge out of band", async () => {
+    const res = await fetch("http://localhost:3000/orders", { method: "POST" });
+    const html = await res.text();
+    expect(html).toContain("hx-swap-oob");
+  });
+});

package/detectors/htmx_tester_detector/fixtures/dirty/panel.html

@@ -0,0 +1,7 @@
+<!-- URN: component:orders:checkout:panel:frontend:presentation -->
+<!-- Tested-By: -->
+<!-- - test:orders:checkout:E041-SMOKE-001 -->
+<!-- Runtime: browser -->
+<!-- Purpose: the orders panel htmx swaps into -->
+<div hx-get="/orders" hx-target="#orders"></div>
+<div hx-get="/invoices/overdue" hx-target="#late"></div>