@afokapu/atdd-bun 0.5.0 → 0.6.1

package/README.md

@@ -97,6 +97,7 @@ name.
 | Profile | Use it when you need to check |
 |---|---|
 | `traceability` | plan acceptance, Bun test, and implementation closure |
+| `topology` | feature decomposition and canonical plan, source, test, and E2E locations |
 | `planner` | plan parsing/graph integrity plus the explicitly scoped planner rules |
 | `docs` | the optional documentation capability and its declared artifacts, including the generated journey view |
 | `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
@@ -123,6 +124,35 @@ carry Station Master actions; the Bun interlocking family checks those actions r
 Hooks, direct CLI use, and CI invoke this same profile and therefore share the
 same schema source.
 
+### Repository topology
+
+The topology gate makes a feature a required plan artifact instead of an
+optional label on a WMBT. Its default layout is:
+
+```text
+plan/<wagon>/{_<wagon>,<feature>,<WMBT>}.yaml
+src/wagons/<wagon>/features/<feature>/{domain,application,infrastructure,presentation}/
+tests/wagons/<wagon>/features/<feature>/{unit,contract,integration}/
+e2e/interlockings/<interlocking>/<route>.routes.test.ts
+e2e/journeys/<journey>.journey.test.ts
+```
+
+Each feature must be declared by exactly one wagon and each WMBT by exactly one
+feature. Source and test headers must name the feature in their path; tests bind
+with `Acceptance:`, while exposed journey E2E tests bind with `Train:`. The
+component-URN `integration` layer maps to the `infrastructure/` directory.
+
+Change the four roots for an existing repository in `atdd-bun.yaml`; the same
+validation then follows the configured locations:
+
+```yaml
+topology:
+  plan_root: plan
+  source_root: src/wagons
+  test_root: tests/wagons
+  e2e_root: e2e
+```
+
 ### Design system
 
 The `design` profile (also part of `coder`) is the Bun realization of the core

package/conventions/atdd-bun.planner/atdd-bun.planner.acceptance-identity.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.acceptance-identity
+kind: rule
+status: active
+name: Embedded acceptances carry an acceptance identity
+statement: Every acceptance embedded in a WMBT is an object whose `identity.urn` starts with `acc:`. Package rule,
+  strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Embedded acceptances carry an acceptance identity.
+  normative_text: Tests bind acceptances by that identity; one without it can never be proven.
+  fix_hint: 'Give the acceptance `identity: { urn: acc:<wagon>:<id> }`.'
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-ACCEPTANCE-IDENTITY
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.identity-required.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.identity-required
+kind: rule
+status: active
+name: Plan artifacts carry their identity
+statement: Every plan artifact whose kind the planner recognizes carries its canonical identity (`train_id`, `interlocking_id`,
+  `journey_id`, or `urn`). Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts carry their identity.
+  normative_text: An artifact without an identity cannot be referenced, bound, or traced; every rule that resolves
+    references silently skips it.
+  fix_hint: 'Add the identity field for the artifact kind, for example `interlocking_id: interlocking:checkout`.'
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-IDENTITY-REQUIRED
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.identity-unique.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.identity-unique
+kind: rule
+status: active
+name: Plan identities are unique
+statement: No two plan artifacts declare the same identity (`train_id`, `interlocking_id`, `journey_id`, `urn`,
+  …). Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan identities are unique.
+  normative_text: A reference to a duplicated identity resolves to whichever file was read first.
+  fix_hint: Rename one of the artifacts, or merge them.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-IDENTITY-UNIQUE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.interlocking-participant-resolves.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.interlocking-participant-resolves
+kind: rule
+status: active
+name: Interlocking participants resolve
+statement: Every participant and lifeline an interlocking lists is either an external actor (`user:…`, `system:…`)
+  or a typed reference to an artifact the plan declares. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Interlocking participants resolve.
+  normative_text: A routing decision between participants the plan does not declare cannot be traced to anything
+    that implements it.
+  fix_hint: Declare the participant, or correct the lifeline.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-INTERLOCKING-PARTICIPANT-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.parse.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.parse
+kind: rule
+status: active
+name: Plan artifacts parse
+statement: Every `.yaml`, `.yml` or `.json` file under `plan/` parses. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts parse.
+  normative_text: An artifact that does not parse is invisible to every other rule, so its defects hide behind one
+    error.
+  fix_hint: Fix the syntax the finding reports.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-PARSE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.reference-resolves.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.reference-resolves
+kind: rule
+status: active
+name: Typed plan references resolve
+statement: Every typed reference an artifact makes (`wagon:`, `feature:`, `wmbt:`, `train:`, `interlocking:`, `journey:`)
+  names an artifact the plan declares. `contract:` references are resolved by the contract registry rules instead.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Typed plan references resolve.
+  normative_text: A reference to nothing is a relationship the plan claims and cannot show.
+  fix_hint: Declare the referenced artifact, or correct the reference.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-REFERENCE-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.schema.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.schema
+kind: rule
+status: active
+name: Plan artifacts satisfy their package-shipped schema
+statement: Every recognized plan artifact (wagon, feature, WMBT and its acceptances, train, train interlocking,
+  journey topology, registries) satisfies its JSON Schema in `planner-schemas/`. A violation that belongs to a canonical
+  rule is reported under that rule (for example `planner.train.naming`); every other violation is reported here.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts satisfy their package-shipped schema.
+  normative_text: The schemas are the shape every other rule assumes. An artifact that breaks its schema breaks
+    those assumptions silently.
+  fix_hint: Correct the field the finding names, as the schema requires.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-SCHEMA
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_schema_validation

package/conventions/atdd-bun.planner/atdd-bun.planner.train-wagon-resolves.convention.yaml

@@ -0,0 +1,26 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.train-wagon-resolves
+kind: rule
+status: active
+name: Train wagons resolve
+statement: Every wagon a train lists under `wagons:` is declared as `wagon:<slug>`. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Train wagons resolve.
+  normative_text: A train ordering a wagon that does not exist cannot run.
+  fix_hint: Declare the wagon, or remove it from the train.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-TRAIN-WAGON-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.topology/atdd-bun.topology.e2e-location.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.e2e-location
+kind: rule
+status: active
+name: Every interlocking route and exposed journey has an end-to-end test at its canonical path
+statement: 'Every interlocking route has `<e2e_root>/interlockings/<interlocking>/<route>.routes.test.ts`, and every
+  exposed journey `<e2e_root>/journeys/<journey>.journey.test.ts`, each carrying a `test:{wagon}:{feature}:{acceptance}`
+  URN for a declared feature and binding `Acceptance: acc:{wagon}:{acceptance}` declared by a WMBT. On an exposed
+  journey whose surfaces include `frontend`, a Playwright spec (`*.e2e.ts`) substitutes for the Bun test when it
+  is bound to the route''s train (`// Train:`) or the journey (`// Journey:`) and carries a valid E2E or SMOKE test
+  URN for that same subject (`test:train:<id>:E2E-NNN-…`, `test:journey:<id>:SMOKE-NNN-…`). A browser spec carries
+  its identity as that URN instead of an `Acceptance:` line, which `tester.htmx.journey-no-acceptance-marker` forbids
+  on journey specs. Package rule, strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Every interlocking route and exposed journey has an end-to-end test at its canonical path.
+  normative_text: 'One behaviour, one end-to-end proof at a path derived from the plan: a missing proof is found
+    by path, not by searching.'
+  fix_hint: Add the test at the path the finding names, or, on a frontend journey, a Playwright spec bound with
+    `// Train:` or `// Journey:`.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-E2E-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.feature-source-coverage.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.feature-source-coverage
+kind: rule
+status: active
+name: A feature with WMBTs has source
+statement: A feature that owns WMBTs has at least one source component beneath `<source_root>/<wagon>/features/<feature>/`.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: A feature with WMBTs has source.
+  normative_text: A feature with behaviour to deliver and no implementation is a gap the plan already names.
+  fix_hint: Implement the feature beneath its directory, or move the WMBTs to the feature that delivers them.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-FEATURE-SOURCE-COVERAGE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.feature-test-coverage.convention.yaml

@@ -0,0 +1,29 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.feature-test-coverage
+kind: rule
+status: active
+name: A feature with WMBTs has a test bound to one of its acceptances
+statement: A feature that owns WMBTs has at least one test bound to one of its acceptances. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: A feature with WMBTs has a test bound to one of its acceptances.
+  normative_text: Behaviour declared and never tested is a silent gap.
+  fix_hint: Add a test beneath the feature bound to one of its acceptances.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-FEATURE-TEST-COVERAGE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.plan-location.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.plan-location
+kind: rule
+status: active
+name: Wagons, features and WMBTs live at their canonical plan paths
+statement: Every wagon is declared at `<plan_root>/<wagon>/_<wagon>.yaml`, every feature at `<plan_root>/<wagon>/<feature>.yaml`,
+  and every WMBT at `<plan_root>/<wagon>/<WMBT>.yaml`. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Wagons, features and WMBTs live at their canonical plan paths.
+  normative_text: The plan is navigated by path as much as by identity. A document at a non-canonical path is found
+    by nothing that walks the layout, and two layouts in one repository make every tool guess.
+  fix_hint: Move the document to the path the finding names.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-PLAN-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.source-location.convention.yaml

@@ -0,0 +1,33 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.source-location
+kind: rule
+status: active
+name: Feature source lives beneath its feature and carries a component URN
+statement: 'When the plan models at least one wagon, feature or WMBT, every source file beneath `<source_root>`
+  carries `URN: component:{wagon}:{feature}:{name}:{frontend|backend}:{domain|application|integration|presentation}`
+  and lives beneath `<source_root>/<wagon>/features/<feature>/`, for a feature the plan declares. Package rule,
+  strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Feature source lives beneath its feature and carries a component URN.
+  normative_text: Source is traced to the feature that owns it by its URN and found by its path. Either missing,
+    the feature cannot be shown to have an implementation.
+  fix_hint: Add the component URN header and move the file beneath its feature's directory.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-SOURCE-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.test-location.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.test-location
+kind: rule
+status: active
+name: Feature tests live beneath their feature and bind a declared acceptance
+statement: 'When the plan models at least one wagon, feature or WMBT, every test beneath `<test_root>` carries `URN:
+  test:{wagon}:{feature}:{acceptance}`, lives beneath `<test_root>/<wagon>/features/<feature>/{unit,contract,integration}/`,
+  and binds `Acceptance: acc:{wagon}:{acceptance}` declared by a WMBT that the test''s own feature lists. Package
+  rule, strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Feature tests live beneath their feature and bind a declared acceptance.
+  normative_text: A test proves an acceptance only when it names one that exists; its path says which feature and
+    which kind of test it is.
+  fix_hint: Add the test URN and Acceptance header, and move the test beneath its feature under unit/, contract/
+    or integration/.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-TEST-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/detectors/atdd_topology/atdd.implementation.yaml

@@ -0,0 +1,16 @@
+kind: implementation
+subtype: guard
+implementation_id: atdd_topology
+emits_rule_ids:
+- planner.wagon.features
+- planner.feature.wagon-link
+- atdd-bun.topology.plan-location
+- atdd-bun.topology.source-location
+- atdd-bun.topology.test-location
+- atdd-bun.topology.e2e-location
+- atdd-bun.topology.feature-source-coverage
+- atdd-bun.topology.feature-test-coverage
+realizes_convention:
+  - planner.wagon.features
+  - planner.feature.wagon-link
+entrypoint: detect.mjs