@afokapu/atdd-bun 0.1.0

package/conventions/tester.bun/tester.bun.telemetry-emit.convention.yaml

@@ -0,0 +1,46 @@
+schema_version: 1.1.0
+rule_id: tester.bun.telemetry-emit
+kind: rule
+status: active
+name: Telemetry tests assert on emission
+statement: >-
+  A test identified as a telemetry test by its URN kind segment (`-TELEMETRY-`, `-EVENT-`, `-METRIC-`) or
+  by `*.telemetry.test.*` colocation MUST contain an emission assertion — `toHaveBeenCalled[With|Times]`,
+  or an expectation on `.emit` / `.emitted` / `.capture` / `.track` / `.record`. Bun realization of core
+  `tester.telemetry.emit`, mirroring `tester.convex.telemetry-emit`.
+terms:
+- term_id: telemetry_test
+  text: >-
+    a test identified by a TELEMETRY, EVENT or METRIC URN segment, or by `*.telemetry.test.*`
+    colocation.
+- term_id: emission_assertion
+  text: >-
+    toHaveBeenCalled[With|Times], or an expectation on .emit / .emitted / .capture / .track. A
+    return-value check proves the function ran, not that the event fired.
+content:
+  summary: >-
+    Identifies telemetry tests from the URN or the filename and flags those with no emission assertion.
+  normative_text: |
+    A telemetry test that checks a return value has proven the function ran. It has not proven the event fired — and the event is the entire point, because dashboards, alerts and downstream analytics are built on the emission, not on the return.
+    This is the one rule in the family where filename colocation is accepted alongside the URN, mirroring the Convex sibling: `*.telemetry.test.ts` is a strong enough signal on its own.
+  fix_hint: |
+    Assert the emission, with a spy or a captured emitter:
+
+      const emit = mock(() => {});
+      placeOrder({ sku: "x" }, { emit });
+      expect(emit).toHaveBeenCalledWith("order_placed", { sku: "x" });
+  exceptions:
+  - Only telemetry-identified tests are scanned.
+  - Filename colocation (`*.telemetry.test.*`) identifies a telemetry test even without a URN kind segment.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from convex.extension.tester.base :: tester.convex.telemetry-emit
+  # Core obligation: tester.telemetry.emit
+  - TESTER-TELEMETRY-EMIT-001
+  - BUN-TELEMETRY-EMIT-001
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.test-carries-urn-identity.convention.yaml

@@ -0,0 +1,51 @@
+schema_version: 1.1.0
+rule_id: tester.bun.test-carries-urn-identity
+kind: rule
+status: active
+name: Every test file declares its test URN
+statement: >-
+  Every `*.test.*` / `*.spec.*` file MUST carry a `// URN: test:{wagon}:{feature}:{ACCEPTANCE-ID}` header.
+  Stack-neutral obligation, Bun-specific line-comment detector. Core's counterpart is explicit that a
+  test's authoritative identity is its HEADER and not its filename, and this realization follows that
+  exactly — it never parses a filename for identity. Realized by `bun_tester_discipline_detector`.
+terms:
+- term_id: test_urn
+  text: >-
+    `test:{wagon}:{feature}:{ACCEPTANCE-ID}` in the file's leading comment block.
+- term_id: header_authority
+  text: >-
+    core's rule that a test's identity is its HEADER, not its filename — so a wagon-level file
+    covering several acceptances needs no rename to be bound.
+content:
+  summary: >-
+    Parses the leading comment block for a `URN:` field and requires the `test:` scheme. The header region
+    ends at the first line of real code, so a URN below the imports reads as missing.
+  normative_text: |
+    This is the foundation the whole coverage gate stands on. Without a test URN there is no edge from a test to anything, so the gate cannot attribute the test, cannot report coverage, and — worst — reports the acceptance as uncovered while the test sits right there passing.
+    Header rather than filename is a deliberate and load-bearing choice, and it is the same conclusion issue #1783 reached independently for backend TypeScript: a real suite's files are wagon-level and cover several acceptances, so a one-acceptance-per-filename rule would force a rename of the entire suite to satisfy a tool. The header binds without touching the team's file layout.
+  fix_hint: |
+    Add the header above the imports:
+
+      // URN: test:orders:checkout:E001-SMOKE-001-renders-row
+      // Acceptance: acc:orders:E001-SMOKE-001-renders-row
+      // Phase: SMOKE
+      // Layer: integration
+  exceptions:
+  - Only test files are scanned; source files are the coder extension's business.
+  - Vendored and build directories are never scanned.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.filename.test-carries-urn-identity`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-TEST-CARRIES-URN-IDENTITY-001
+  severity: 2
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.test-imports-bun-test.convention.yaml

@@ -0,0 +1,55 @@
+schema_version: 1.1.0
+rule_id: tester.bun.test-imports-bun-test
+kind: rule
+status: active
+name: Tests import their harness from bun:test
+statement: >-
+  A test file in a Bun stack MUST import its harness from `bun:test` and MUST NOT import `vitest`,
+  `jest`, `@jest/globals`, `mocha` or `chai`. The workspace provider's declared runner is `bun`, so a
+  test bound to a foreign harness is not executed by the runner the gate believes it ran. This is the
+  Bun-stack realization of the agnostic "the declared runner is the runner that runs" obligation,
+  enforced by the `bun_fullstack_detector` family implementation on `atdd.workspace.bun`.
+terms:
+- term_id: declared_runner
+  text: >-
+    the `runtime.runner` of the capability `atdd.workspace.bun` provides — `bun`. It is what the
+    binding plan resolves and what the phase gate reports as having executed.
+- term_id: foreign_harness
+  text: >-
+    `vitest`, `jest`, `@jest/globals`, `mocha`, `chai` — a test framework that drags its own runner and
+    transform pipeline back into a toolchain whose premise is that Bun runs TypeScript directly.
+content:
+  summary: >-
+    A "tests run on the declared runner" obligation. The realization is a zero-dependency Bun detector
+    that scans TEST FILES ONLY (`*.test.*`, `*.spec.*` — the only place a harness import belongs), masks
+    line comments so a migration note naming the old runner does not trip it, and flags any import or
+    require of a foreign harness.
+  normative_text: |
+    The ordinary cost of a stray Vitest import is toolchain sprawl. The ATDD-specific cost is larger and
+    is the reason this rule is `strict`: acceptance tests are the evidence a phase gate consumes, and a
+    gate reports coverage in terms of the runner it declared. A test bound to a harness that runner does
+    not execute is coverage the gate believes exists and that never ran — the failure mode where a
+    green gate and an unexercised acceptance coexist, which is precisely what ATDD is built to prevent.
+    Note that the masker blanks COMMENTS but not string literals here, because the harness name lives
+    inside the import's own string literal — masking literals would blank the very thing being matched.
+  fix_hint: |
+    Import the harness from Bun and run with `bun test`:
+
+      import { describe, expect, it } from "vitest";     // ✗ not run by the declared runner
+      import { describe, expect, it } from "bun:test";   // ✓
+
+    `bun:test` is Jest-compatible at the assertion level, so most files need only the import line
+    changed. `strict` — a test the gate cannot actually run is worse than no test.
+  exceptions:
+  - Non-test files are never scanned; a harness import outside a test file is a different smell.
+  - A test deliberately retained on a foreign runner during a migration should be scoped out via the
+    consumer scope map, so the exemption is explicit and reviewable rather than invisible.
+metadata:
+  aliases:
+  - BUN-TEST-HARNESS-001
+  severity: 2
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.test-isolation-no-live-state.convention.yaml

@@ -0,0 +1,50 @@
+schema_version: 1.1.0
+rule_id: tester.bun.test-isolation-no-live-state
+kind: rule
+status: active
+name: Tests do not write to shared live state
+statement: >-
+  A test MUST NOT mutate `process.env` nor write to a filesystem path outside a temp directory. Stack-
+  neutral obligation, RE-REALIZED for this stack: core's sibling detects Python bare-mode-init patterns,
+  which do not exist here. Realized by `bun_tester_discipline_detector`.
+terms:
+- term_id: shared_live_state
+  text: >-
+    process.env, or a filesystem path outside a temp directory — anything a later test also
+    sees.
+- term_id: displaced_failure
+  text: >-
+    the signature of pollution: a DIFFERENT test fails, later, often only under a different
+    order, and the failure points at the victim rather than the culprit.
+content:
+  summary: >-
+    Flags `process.env.X =` assignments and write-family `fs` calls whose literal path is not scoped to
+    `tmpdir` / `/tmp` / `import.meta.dir` / `__fixtures__` / `.tmp`.
+  normative_text: |
+    A polluting test does not fail. It makes a DIFFERENT test fail, later, often only when the suite runs in a different order — and the failure points at the victim rather than the culprit. That asymmetry is why this is the family's `strict` rule, matching core: the cost of finding one of these after the fact is measured in days.
+    `process.env` mutation is called out separately because it is the most common form and the least obviously wrong: it looks local, and it is global.
+  fix_hint: |
+    Scope every write to a temp directory the test owns and cleans up, and pass configuration explicitly instead of mutating the environment:
+
+      process.env.DATABASE_URL = "postgres://live";   // leaks into every later test
+      const db = connect({ url: testUrl });             // explicit, scoped
+  exceptions:
+  - Paths containing `tmpdir`, `/tmp`, `import.meta.dir`, `__fixtures__` or `.tmp` are test-scoped and allowed.
+  - Reads are never flagged; only the write family.
+  - A non-literal path cannot be judged by this detector and is not reported.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.test-isolation.no-polluting-patterns`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-TEST-ISOLATION-NO-LIVE-STATE-001
+  severity: 4
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.test-no-self-skip.convention.yaml

@@ -0,0 +1,46 @@
+schema_version: 1.1.0
+rule_id: tester.bun.test-no-self-skip
+kind: rule
+status: active
+name: Tests do not disable themselves
+statement: >-
+  A test MUST NOT disable itself with `.skip` / `.todo` / `.failing`, nor bail out early on an environment
+  check. Stack-neutral obligation, Bun-specific detector over `bun:test` modifiers. Realized by
+  `bun_tester_discipline_detector`.
+terms:
+- term_id: self_skip
+  text: >-
+    `.skip` or `.todo` on it / test / describe. Deliberately excludes `.fails` / `.failing`,
+    which core's RED vocabulary lists as accepted markers.
+- term_id: guarded_bail
+  text: >-
+    `if (!process.env.X) return` inside a test — the same fault in disguise, and the more common
+    one, since it does nothing in exactly the environment nobody watches.
+content:
+  summary: >-
+    Flags `it.skip` / `test.skip` / `describe.skip` (and `.todo` / `.failing`), and a guarded `if
+    (…process.env…) return` bail-out inside a test.
+  normative_text: |
+    A skipped test reports GREEN. That is the entire problem: the suite passes, the gate sees no failure, and the acceptance is recorded as covered by a test that did not run.
+    The environment-guard form is included because it is the same fault in disguise and is far more common in practice — `if (!process.env.DATABASE_URL) return;` at the top of a live smoke means the test silently does nothing in exactly the environment where nobody is watching. If a test genuinely cannot run somewhere, that belongs in the runner's configuration where it is visible, not hidden inside the test body.
+  fix_hint: |
+    Remove the modifier and let the test run, or delete the test. If it must not run in some environment, exclude it at the runner level so the exclusion is visible in configuration rather than invisible in a green suite.
+  exceptions:
+  - A skip in a fixture or helper that is not itself a test case is out of scope.
+  - Runner-level exclusion (a config filter) is the supported way to not run a test.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.acceptance-violation.live-smoke-acceptance`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-NO-SELF-SKIP-001
+  severity: 3
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.test-phase-declared.convention.yaml

@@ -0,0 +1,45 @@
+schema_version: 1.1.0
+rule_id: tester.bun.test-phase-declared
+kind: rule
+status: active
+name: Every test declares its ATDD phase
+statement: >-
+  A test file carrying a URN MUST declare `// Phase:` with one of RED, UNIT, SMOKE, E2E. Stack-neutral
+  obligation, Bun-specific detector. Realized by `bun_tester_discipline_detector`.
+terms:
+- term_id: phase_field
+  text: >-
+    `// Phase:` with RED, UNIT, SMOKE or E2E.
+- term_id: phase_gated_rule
+  text: >-
+    a rule that only applies to one phase. Without a declared phase a test is exempt from the
+    whole quality surface by omission.
+content:
+  summary: >-
+    Requires a `Phase:` field from the closed vocabulary.
+  normative_text: |
+    The phase is not documentation — it is what selects which other rules apply. A RED test must fail first and must assert behaviour; a SMOKE test must assert something operator-observable and must not substitute collaborators. Without a declared phase none of those obligations can be evaluated, so an undeclared test is exempt from the entire quality surface by omission.
+    That is why this rule exists separately from the URN rule: a test can be perfectly identified and still be ungoverned.
+  fix_hint: |
+    Declare the phase the test belongs to:
+
+      // Phase: SMOKE
+  exceptions:
+  - Files with no URN are skipped.
+  - The vocabulary is fixed by core; a new phase is a core change, not an extension one.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.filename.test-carries-urn-identity`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-PHASE-DECLARED-001
+  severity: 2
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.htmx/tester.htmx.fragment-asserts-returned-markup.convention.yaml

@@ -0,0 +1,52 @@
+schema_version: 1.1.0
+rule_id: tester.htmx.fragment-asserts-returned-markup
+kind: rule
+status: active
+name: htmx endpoint tests assert on the returned fragment
+statement: >-
+  A test case that performs an HTTP request and asserts on the response status MUST also assert on the
+  response BODY. Bun/htmx-specific obligation with no counterpart in any other stack's tester extension.
+  Realized by `bun_tester_discipline_detector`.
+terms:
+- term_id: fragment_contract
+  text: >-
+    the returned markup itself — hx-attributes, the element ids later out-of-band swaps target,
+    and the structure. In htmx this IS the interface, where a JSON API has a payload.
+- term_id: status_only_test
+  text: >-
+    a case asserting on status or ok and never reaching the body. It proves the route exists and
+    nothing about what the user will see.
+content:
+  summary: >-
+    Flags a case that fetches, asserts on `status`/`ok`, and never reaches `.text()` / `.json()` / a
+    `toContain` / `toMatch` / markup assertion.
+  normative_text: |
+    In a JSON API the response contract is the payload, and 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 that later out-of-band swaps target, and the structure itself are the interface.
+    A test asserting `expect(res.status).toBe(200)` and stopping has proven the route exists and nothing about what the user will see. In particular it will not notice when a refactor drops the `id` that a sibling fragment's `hx-swap-oob` needs — which fails silently at runtime, exactly as `coder.htmx.swap-oob-carries-id` describes.
+    This rule exists because the stack moved the contract from the payload into the markup. That is the clearest case in this whole extension of an obligation that could not have been inherited from another stack.
+  fix_hint: |
+    Assert on the fragment, not just the status line:
+
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain('id="order-1"');   // the id a later oob swap targets
+  exceptions:
+  - Cases that do not perform an HTTP request are out of scope.
+  - Cases that never assert on status are out of scope.
+  - Reaching the body in any form — `.text()`, `.json()`, a markup matcher — satisfies the rule.
+metadata:
+  aliases:
+  # No core counterpart: this obligation exists because htmx moves the response
+  # contract from the payload into the markup. Stack-native, not inherited.
+  - BUN-FRAGMENT-ASSERTS-MARKUP-001
+  severity: 3
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_tester_detector

package/conventions/tester.htmx/tester.htmx.swap-oob-asserts-destination-id.convention.yaml

@@ -0,0 +1,48 @@
+schema_version: 1.1.0
+rule_id: tester.htmx.swap-oob-asserts-destination-id
+kind: rule
+status: active
+name: Out-of-band swap tests assert the destination id
+statement: >-
+  A test case that asserts an out-of-band swap is present in a response MUST also assert the destination
+  `id`. Bun/htmx realization: the tester half of `coder.htmx.swap-oob-carries-id`, and the same shape as
+  `tester.convex.interlocking-trace-binds-declared-route` — an assertion on a runtime artefact must bind
+  back to the declaration it came from.
+terms:
+- term_id: destination_id
+  text: >-
+    the `id` htmx matches an out-of-band element against. It must be present in the response AND
+    in the document, or the swap does not happen.
+- term_id: half_assertion
+  text: >-
+    a test confirming `hx-swap-oob` appears in the response and stopping there. It proves the
+    server's half and nothing about the destination — the half a template refactor breaks.
+content:
+  summary: >-
+    Flags a test case whose body mentions `hx-swap-oob` but contains no assertion reaching an id — an
+    `id=` in an expected string, a `getElementById`, a `querySelector('#…')`, or a
+    `toHaveAttribute('id'…)`.
+  normative_text: |
+    The failure this guards is silent from both sides. htmx drops an out-of-band element whose id matches nothing in the document: no error, no console warning, no swap.
+    `coder.htmx.swap-oob-carries-id` makes the server EMIT an id. Nothing else makes a test prove it is the id the page will actually match. The two rules are one defect seen from source and from suite, and neither alone closes it — which is exactly why the htmx tester surface is a package rather than a stray rule in the Bun one.
+  fix_hint: |
+    Assert the destination, not just the mechanism:
+
+      expect(html).toContain("hx-swap-oob");          // the server's half only
+      expect(html).toContain('id="cart-count"');      // the half that must match the page
+  exceptions:
+  - Cases that never mention `hx-swap-oob` are out of scope.
+  - Any id-reaching assertion satisfies the rule; no specific matcher is required.
+  - Whether the id EXISTS in the served document is a runtime fact no static check can see.
+metadata:
+  aliases:
+  # Pairs with coder.htmx.swap-oob-carries-id — the same defect, the other persona
+  # Shape mirrored from tester.convex.interlocking-trace-binds-declared-route
+  # ADDED for this stack: core has no node for out-of-band swap testing.
+  - BUN-OOB-TARGET-ASSERTED-001
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_tester_detector

package/conventions/tester.htmx/tester.htmx.verb-endpoint-coverage.convention.yaml

@@ -0,0 +1,54 @@
+schema_version: 1.1.0
+rule_id: tester.htmx.verb-endpoint-coverage
+kind: rule
+status: active
+name: Every htmx endpoint declared in markup has a test
+statement: >-
+  Every endpoint declared by an htmx verb attribute (`hx-get`, `hx-post`, `hx-put`, `hx-patch`, `hx-
+  delete`) MUST be exercised by at least one test. Bun/htmx realization mirroring
+  `tester.convex.interlocking-route-coverage`; the declaration source differs, and that difference IS the
+  adaptation — a Convex route is declared in `plan/_trains/_interlockings/**/*.yaml`, an htmx endpoint is
+  declared in the MARKUP, so the markup is this stack's route space.
+terms:
+- term_id: route_space
+  text: >-
+    the set of endpoints the application actually exposes. For Convex it is the interlocking
+    YAML; for htmx it is every hx- verb attribute in the templates, because that attribute IS
+    the request.
+- term_id: coverage_no_op
+  text: >-
+    the behaviour when a scan mount holds markup but no test files: emit nothing rather than
+    report every endpoint uncovered. A coverage rule needs both sides, and a source-only scan is
+    not evidence of a missing test.
+content:
+  summary: >-
+    Collects every hx- verb endpoint from templates and source, collects the text of every test file in
+    the same mount, and reports an endpoint no test mentions. A literal match counts, as does a match up
+    to a dynamic segment, so `/orders/1` covers `/orders/:id`.
+  normative_text: |
+    An htmx endpoint is not reached through a router table a tool can enumerate; it is an attribute on an element. That makes the route space easy to grow and easy to forget — a developer adds
+    `hx-get="/invoices/overdue"` to a template and nothing anywhere records that a new server surface exists.
+    This is the rule that notices, and it is the direct counterpart of the Convex coverage rule. That it reads markup rather than a plan file is not a boundary violation but the honest location of the declaration in this stack.
+    The no-op matters as much as the check: on a source-only mount the rule stays silent, both because a coverage claim needs a suite to measure against, and because a tester-persona rule must not produce findings on a tree containing no tests.
+  fix_hint: |
+    Write a test that exercises the endpoint, or delete the attribute if the surface is not real:
+
+      <div hx-get="/invoices/overdue" hx-target="#late"></div>   <!-- declared -->
+
+      const res = await fetch("/invoices/overdue");                // exercised
+      expect(res.status).toBe(200);
+  exceptions:
+  - A mount containing no test files is skipped entirely.
+  - A dynamic segment matches on its static prefix, so a test hitting a concrete id covers the template.
+  - An absolute-URL endpoint is `coder.htmx.verb-endpoint-same-origin`'s finding, not this rule's.
+metadata:
+  aliases:
+  # Mirrored from convex.extension.tester.base :: tester.convex.interlocking-route-coverage
+  # ADDED for this stack: core has no node for hypermedia endpoint coverage.
+  - BUN-ENDPOINT-COVERAGE-001
+  severity: 2
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_tester_detector

package/conventions/traceability/traceability.plan.executable-acceptance-has-test.convention.yaml

@@ -0,0 +1,2 @@
+rule_id: traceability.plan.executable-acceptance-has-test
+statement: Every declared acceptance is bound by at least one Bun test.

package/conventions/traceability/traceability.source.tested-by-present.convention.yaml

@@ -0,0 +1,2 @@
+rule_id: traceability.source.tested-by-present
+statement: Each identified implementation component declares a testing witness.

package/conventions/traceability/traceability.source.tested-by-resolves.convention.yaml

@@ -0,0 +1,2 @@
+rule_id: traceability.source.tested-by-resolves
+statement: Each implementation testing witness resolves to an identified Bun test.

package/conventions/traceability/traceability.test.binding-resolves.convention.yaml

@@ -0,0 +1,2 @@
+rule_id: traceability.test.binding-resolves
+statement: Each identified Bun test names a plan acceptance, WMBT, or train that resolves.

package/detectors/atdd_traceability_closure/atdd.implementation.yaml

@@ -0,0 +1,8 @@
+kind: implementation
+implementation_id: atdd_traceability_closure
+emits_rule_ids:
+- traceability.plan.executable-acceptance-has-test
+- traceability.test.binding-resolves
+- traceability.source.tested-by-present
+- traceability.source.tested-by-resolves
+entrypoint: detect.mjs

package/detectors/atdd_traceability_closure/detect.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+// Bun-native closure gate for plan -> test -> implementation traceability.
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const roots = JSON.parse(process.env.ATDD_SCAN_ROOTS || "[]");
+const excludes = new Set(JSON.parse(process.env.ATDD_SCAN_EXCLUDES || "[]"));
+const report = process.env.ATDD_VIOLATIONS_REPORT;
+if (!report || !Array.isArray(roots) || !roots.length) process.exit(2);
+
+const sourceExtensions = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"]);
+const testName = /(?:^test_.*|.*(?:\.test|\.spec|_test))\.(?:[cm]?[jt]sx?)$/;
+const violations = [];
+const plans = { acc: new Set(), wmbt: new Set(), train: new Set() };
+const tests = new Map();
+const sources = [];
+
+function ignored(path) {
+  return [...excludes].some((needle) => path.includes(needle));
+}
+function walk(dir, file) {
+  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (ignored(full)) continue;
+    if (entry.isDirectory()) walk(full, file); else file(full);
+  }
+}
+function text(path) { try { return readFileSync(path, "utf8"); } catch { return ""; } }
+function add(rule_id, file, line, evidence, source_line = "") {
+  violations.push({ rule_id, file, line, col: 1, evidence, source_line });
+}
+function lineOf(content, token) { return content.slice(0, content.indexOf(token)).split("\n").length; }
+
+for (const root of roots) {
+  walk(root, (path) => {
+    const name = path.split("/").pop() || "";
+    const content = text(path);
+    if (/\.ya?ml$/i.test(name) && /(?:^|\/)plan(?:\/|$)/.test(path)) {
+      for (const [kind, re] of Object.entries({
+        acc: /\bacc:[A-Za-z0-9_.:-]+/g,
+        wmbt: /\bwmbt:[A-Za-z0-9_.:-]+/g,
+        train: /\btrain:[A-Za-z0-9_.:-]+/g,
+      })) for (const match of content.matchAll(re)) plans[kind].add(match[0]);
+      return;
+    }
+    if (!sourceExtensions.has(name.slice(name.lastIndexOf(".")))) return;
+    const head = content.split("\n").slice(0, 40).join("\n");
+    if (testName.test(name)) {
+      const urn = head.match(/^\s*\/\/\s*URN:\s*(test:[^\s]+)/m);
+      const binding = head.match(/^\s*\/\/\s*(Acceptance|WMBT|Train):\s*((?:acc|wmbt|train):[^\s]+)/m);
+      if (!urn) return;
+      tests.set(urn[1], { path, binding: binding?.[2], bindingKind: binding?.[1] });
+      if (!binding) add("traceability.test.binding-resolves", path, lineOf(head, urn[0]), "test has a URN but no Acceptance:, WMBT:, or Train: binding", urn[0]);
+      return;
+    }
+    const component = head.match(/^\s*\/\/\s*URN:\s*(component:[^\s]+)/m);
+    if (!component) return;
+    const testedBy = [...head.matchAll(/^\s*\/\/\s*-\s*(test:[^\s]+)/gm)].map((match) => match[1]);
+    sources.push({ path, head, component: component[1], testedBy });
+  });
+}
+
+for (const test of tests.values()) {
+  if (!test.binding) continue;
+  const kind = test.binding.startsWith("acc:") ? "acc" : test.binding.startsWith("wmbt:") ? "wmbt" : "train";
+  if (!plans[kind].has(test.binding)) {
+    add("traceability.test.binding-resolves", test.path, lineOf(text(test.path), test.binding), `${test.binding} is not declared in plan/`, `// ${test.bindingKind}: ${test.binding}`);
+  }
+}
+const boundAcceptances = new Set([...tests.values()].map((test) => test.binding).filter((id) => id?.startsWith("acc:")));
+for (const acceptance of plans.acc) {
+  if (!boundAcceptances.has(acceptance)) add("traceability.plan.executable-acceptance-has-test", "plan/", 1, `${acceptance} has no Bun test binding`, acceptance);
+}
+for (const source of sources) {
+  if (!source.testedBy.length) {
+    add("traceability.source.tested-by-present", source.path, lineOf(source.head, source.component), `${source.component} has no Tested-By: test:... declaration`, source.component);
+    continue;
+  }
+  for (const testUrn of source.testedBy) {
+    if (!tests.has(testUrn)) add("traceability.source.tested-by-resolves", source.path, lineOf(source.head, testUrn), `${testUrn} does not resolve to a Bun test`, testUrn);
+  }
+}
+writeFileSync(report, JSON.stringify({ violations }, null, 2));

package/detectors/atdd_traceability_closure/fixtures/clean/plan/orders/E001.yaml

@@ -0,0 +1,4 @@
+urn: wmbt:orders:E001
+acceptances:
+  - identity:
+      urn: acc:orders:E001-UNIT-001-create-order

package/detectors/atdd_traceability_closure/fixtures/clean/src/order.ts

@@ -0,0 +1,4 @@
+// URN: component:orders:create:Order:backend:application
+// Tested-By:
+// - test:orders:E001-UNIT-001-create-order
+export const createOrder = () => "created";

package/detectors/atdd_traceability_closure/fixtures/clean/test/order.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:E001-UNIT-001-create-order
+// Acceptance: acc:orders:E001-UNIT-001-create-order
+import { test, expect } from "bun:test";
+test("creates an order", () => expect(true).toBeTrue());

package/detectors/atdd_traceability_closure/fixtures/dirty/plan/orders/E001.yaml

@@ -0,0 +1,6 @@
+urn: wmbt:orders:E001
+acceptances:
+  - identity:
+      urn: acc:orders:E001-UNIT-001-covered
+  - identity:
+      urn: acc:orders:E001-UNIT-002-uncovered

package/detectors/atdd_traceability_closure/fixtures/dirty/src/missing-test.ts

@@ -0,0 +1,2 @@
+// URN: component:orders:create:MissingTest:backend:application
+export const missingTest = () => "no witness";

package/detectors/atdd_traceability_closure/fixtures/dirty/src/unknown-test.ts

@@ -0,0 +1,4 @@
+// URN: component:orders:create:UnknownTest:backend:application
+// Tested-By:
+// - test:orders:E001-UNIT-999-missing
+export const unknownTest = () => "bad witness";

package/detectors/atdd_traceability_closure/fixtures/dirty/test/bad-binding.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:E001-UNIT-001-bad-binding
+// Acceptance: acc:orders:E001-UNIT-404-unknown
+import { test } from "bun:test";
+test("names an absent acceptance", () => {});

package/detectors/atdd_traceability_closure/fixtures/dirty/test/no-binding.test.ts

@@ -0,0 +1,3 @@
+// URN: test:orders:E001-UNIT-002-no-binding
+import { test } from "bun:test";
+test("has no plan binding", () => {});