@afokapu/atdd-bun 0.5.0 → 0.6.1

package/src/hooks.ts

@@ -2,6 +2,7 @@ import { chmod, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:f
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { enforce } from "./enforce";
+import { topologyFor } from "./topology";
 
 export type WorktreePolicy = { enabled: boolean; root: string; primary_directory: string; primary_branch: string; require_linked_worktree: boolean };
 export type HookPolicy = { max_staged_files: number; max_staged_changed_lines: number; max_uncommitted_files: number; max_commits_per_push: number; max_registry_removed_lines: number; registry_paths: string[]; protected_branches: string[]; require_plan_reference: boolean; require_traceability: boolean; worktrees: WorktreePolicy };
@@ -18,7 +19,7 @@ const isRegistry = (cfg: HookPolicy, path: string) => cfg.registry_paths.some(pa
 const stagedStats = async (root: string) => (await git(root, ["diff", "--cached", "--numstat", "--no-renames"])).out.split("\n").filter(Boolean).map(row => { const [added, removed, ...path] = row.split("\t"); return { added: Number(added) || 0, removed: Number(removed) || 0, path: path.join("\t") }; });
 
 export async function policy(root: string): Promise<HookPolicy> { const file = join(root, "atdd-bun.yaml"); if (!existsSync(file)) return defaultHookPolicy; const data = Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown>; const configuredWorktrees = data?.worktrees && typeof data.worktrees === "object" && !Array.isArray(data.worktrees) ? data.worktrees as Record<string, unknown> : {}; return { ...defaultHookPolicy, ...Object.fromEntries(Object.entries(data ?? {}).filter(([key, value]) => key in defaultHookPolicy && key !== "worktrees" && typeof value === typeof (defaultHookPolicy as any)[key])), protected_branches: strings(data?.protected_branches) ?? defaultHookPolicy.protected_branches, registry_paths: strings(data?.registry_paths) ?? defaultHookPolicy.registry_paths, worktrees: { ...defaultWorktreePolicy, ...Object.fromEntries(Object.entries(configuredWorktrees).filter(([key, value]) => key in defaultWorktreePolicy && typeof value === typeof (defaultWorktreePolicy as any)[key])) } }; }
-async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = []; if (registryChanged || changed.some(path => path.startsWith("plan/"))) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
+async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = [], topology = await topologyFor(root); if (registryChanged || changed.some(path => path.startsWith(`${topology.planRoot}/`)) || changed.includes("atdd-bun.yaml")) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (changed.includes("atdd-bun.yaml") || changed.some(path => /\.ya?ml$/.test(path))) profiles.push("topology"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
 
 const inside = (parent: string, child: string) => { const path = relative(parent, child); return path === "" || (path !== ".." && !path.startsWith("../") && !path.startsWith("..\\")); };
 async function primaryRoot(root: string): Promise<string | null> { const result = await git(root, ["rev-parse", "--git-common-dir"]); if (result.code) return null; return dirname(resolve(root, result.out)); }

package/src/index.ts

@@ -15,3 +15,5 @@ export type { Gap, Journey, JourneyModel, JourneyPath } from "./journey-docs";
 export { checkIntegrity, checkInstalledPackage, formatIntegrity, integrityInit, loosenedPolicy, writeManifest } from "./integrity";
 export type { IntegrityFinding, IntegrityOptions } from "./integrity";
 export { releaseCheck } from "./release";
+export { defaultTopology, topologyFor } from "./topology";
+export type { Topology } from "./topology";

package/src/planner-kernel.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { topologyFor } from "./topology";
 
 export type PlanKind = "wagon" | "feature" | "wmbt" | "acceptance" | "train" | "interlocking" | "journey" | "contract";
 export type PlanFinding = { rule_id: string; file: string; evidence: string };
@@ -16,6 +17,7 @@ async function walk(root: string): Promise<string[]> {
   const entries = await readdir(root, { withFileTypes: true });
   return (await Promise.all(entries.map(async entry => {
     const path = join(root, entry.name);
+    if (entry.isDirectory() && entry.name === "_generated") return [];
     return entry.isDirectory() ? walk(path) : entry.isFile() && /\.(?:yaml|yml|json)$/.test(entry.name) ? [path] : [];
   }))).flat().sort();
 }
@@ -65,7 +67,7 @@ function structuralRefs(artifact: PlanArtifact): string[] {
 /** Load plan artifacts with Bun's native YAML parser. It is read-only and deliberately
  * excludes authoring/session/store behavior from ATDD core. */
 export async function loadPlan(root = process.cwd()): Promise<PlanGraph> {
-  const absolute = resolve(root), plan = join(absolute, "plan"), artifacts: PlanArtifact[] = [], findings: PlanFinding[] = [];
+  const absolute = resolve(root), topology = await topologyFor(absolute), plan = join(absolute, topology.planRoot), artifacts: PlanArtifact[] = [], findings: PlanFinding[] = [];
   for (const path of await walk(plan)) {
     const file = relative(absolute, path).replaceAll("\\", "/");
     try {
@@ -96,7 +98,7 @@ export async function validatePlan(root = process.cwd()): Promise<PlanGraph> {
     const references = structuralRefs(artifact);
     for (const reference of new Set(references)) if (!known.has(reference) && !reference.startsWith("contract:")) graph.findings.push(finding("planner.kernel.reference-resolves", artifact.file, `${artifact.id} references undeclared ${reference}`));
     if (artifact.kind === "train") for (const wagon of values(artifact.data.wagons)) { const reference = `wagon:${id(wagon)}`; if (id(wagon) && !known.has(reference)) graph.findings.push(finding("planner.kernel.train-wagon-resolves", artifact.file, `${artifact.id} lists undeclared ${reference}`)); }
-    if (artifact.kind === "interlocking") for (const participant of [...values(artifact.data.participants), ...values(artifact.data.lifelines).map(value => value && typeof value === "object" ? (value as Record<string, unknown>).ref : value)]) { const reference = id(participant); if (reference.startsWith("wagon:") && !known.has(reference)) graph.findings.push(finding("planner.kernel.interlocking-participant-resolves", artifact.file, `${artifact.id} lists undeclared ${reference}`)); }
+    if (artifact.kind === "interlocking") for (const participant of [...values(artifact.data.participants), ...values(artifact.data.lifelines).map(value => value && typeof value === "object" ? (value as Record<string, unknown>).ref : value)]) { const reference = id(participant); if (reference && !/^(user|system):/.test(reference) && !known.has(reference)) graph.findings.push(finding("planner.kernel.interlocking-participant-resolves", artifact.file, `${artifact.id} lists undeclared ${reference}`)); }
   }
   return graph;
 }

package/src/planner-schema-validator.ts

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { loadPlan, type PlanArtifact, type PlanFinding } from "./planner-kernel";
+import { topologyFor } from "./topology";
 
 type SchemaKind = Extract<PlanArtifact["kind"], "wagon" | "feature" | "wmbt" | "train" | "interlocking" | "journey">;
 
@@ -16,10 +17,11 @@ const schemaFiles: Record<SchemaKind, string> = {
   journey: "journey.schema.json",
 };
 const supportingSchemaFiles = ["appendix.schema.json", "acceptance.schema.json"];
-const repositorySchemas = [
-  { file: "plan/_themes.yaml", schema: "theme-registry.schema.json", rule: "planner.theme.must-be-canonical" },
+const repositorySchemas = (planRoot: string) => [
+  { file: `${planRoot}/_themes.yaml`, schema: "theme-registry.schema.json", rule: "planner.theme.must-be-canonical" },
   { file: "contracts/_contracts.yaml", schema: "contract-registry.schema.json", rule: "planner.contract.registry-coherence" },
 ] as const;
+const repositorySchemaFiles = ["theme-registry.schema.json", "contract-registry.schema.json"];
 const schemaDirectory = join(resolve(import.meta.dir, ".."), "planner-schemas");
 const ruleId = "atdd-bun.planner.schema";
 
@@ -39,23 +41,23 @@ function formatError(error: ErrorObject): string {
 async function validators(): Promise<{ artifacts: Map<SchemaKind, ValidateFunction>; repositories: Map<string, ValidateFunction> }> {
   const ajv = new Ajv({ allErrors: true, allowUnionTypes: true, strict: false });
   addFormats(ajv);
-  const files = [...supportingSchemaFiles, ...Object.values(schemaFiles), ...repositorySchemas.map(item => item.schema)];
+  const files = [...supportingSchemaFiles, ...Object.values(schemaFiles), ...repositorySchemaFiles];
   for (const file of files) ajv.addSchema(JSON.parse(await readFile(join(schemaDirectory, file), "utf8")), file);
   const artifacts = new Map(Object.entries(schemaFiles).map(([kind, file]) => {
     const validator = ajv.getSchema(file);
     if (!validator) throw new Error("could not compile planner schema " + file);
     return [kind as SchemaKind, validator];
   }));
-  const repositories = new Map(repositorySchemas.map(item => {
-    const validator = ajv.getSchema(item.schema);
-    if (!validator) throw new Error("could not compile planner schema " + item.schema);
-    return [item.schema, validator];
+  const repositories = new Map(repositorySchemaFiles.map(schema => {
+    const validator = ajv.getSchema(schema);
+    if (!validator) throw new Error("could not compile planner schema " + schema);
+    return [schema, validator];
   }));
   return { artifacts, repositories };
 }
 
 function repositoryRule(file: string, fallback: string, error: ErrorObject): string {
-  if (file === "plan/_themes.yaml" && (error.instancePath === "/themes" || error.instancePath === "/themes/0" || error.params.missingProperty === "0")) {
+  if (file.endsWith("/_themes.yaml") && (error.instancePath === "/themes" || error.instancePath === "/themes/0" || error.params.missingProperty === "0")) {
     return "planner.theme.theme-zero-mandatory";
   }
   return fallback;
@@ -64,7 +66,7 @@ function repositoryRule(file: string, fallback: string, error: ErrorObject): str
 /** Validate every recognized plan artifact against the package-shipped canonical
  * JSON Schema. Cross-artifact relationships remain planner validator concerns. */
 export async function validatePlannerSchemas(root = process.cwd()): Promise<PlanFinding[]> {
-  const absolute = resolve(root), graph = await loadPlan(absolute);
+  const absolute = resolve(root), topology = await topologyFor(absolute), graph = await loadPlan(absolute), repositories = repositorySchemas(topology.planRoot);
   const byKind = await validators();
   const findings: PlanFinding[] = [];
   for (const artifact of graph.artifacts) {
@@ -79,7 +81,7 @@ export async function validatePlannerSchemas(root = process.cwd()): Promise<Plan
       });
     }
   }
-  for (const item of repositorySchemas) {
+  for (const item of repositories) {
     const path = join(absolute, item.file);
     if (!existsSync(path)) continue;
     try {

package/src/planner-validators.ts

@@ -2,6 +2,7 @@ import { validatePlan, type PlanArtifact, type PlanFinding } from "./planner-ker
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { topologyFor } from "./topology";
 
 const finding = (rule_id: string, file: string, evidence: string): PlanFinding => ({ rule_id, file, evidence });
 const records = (value: unknown): Record<string, unknown>[] => Array.isArray(value) ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object") : [];
@@ -16,13 +17,13 @@ async function yamlFiles(root: string): Promise<string[]> {
 }
 
 async function trainRegistryFindings(root: string): Promise<PlanFinding[]> {
-  const absolute = resolve(root), registryPath = join(absolute, "plan/_trains.yaml"); if (!existsSync(registryPath)) return [];
+  const absolute = resolve(root), topology = await topologyFor(absolute), file = `${topology.planRoot}/_trains.yaml`, registryPath = join(absolute, file); if (!existsSync(registryPath)) return [];
   const registry = Bun.YAML.parse(await readFile(registryPath, "utf8")) as { trains?: Record<string, Record<string, unknown[]>> };
   const rows = Object.values(registry?.trains ?? {}).flatMap(buckets => Object.values(buckets ?? {}).flat()).filter((row): row is Record<string, unknown> => Boolean(row) && typeof row === "object");
   const registered = new Set<string>(), findings: PlanFinding[] = [];
-  for (const row of rows) { const path = text(row.path), train = text(row.train_id); if (!path || !train) continue; registered.add(path); if (!existsSync(join(absolute, path))) findings.push(finding("planner.train.registry-coherence", "plan/_trains.yaml", `registry train ${train} points to missing ${path}`)); }
-  const trainRoot = join(absolute, "plan/_trains");
-  for (const path of await yamlFiles(trainRoot)) { const rel = relative(absolute, path).replaceAll("\\", "/"), pieces = relative(trainRoot, path).split(/[\\/]/); if (pieces.some(piece => piece.startsWith("_")) || registered.has(rel)) continue; findings.push(finding("planner.train.registry-coherence", rel, `train document is not registered in plan/_trains.yaml`)); }
+  for (const row of rows) { const path = text(row.path), train = text(row.train_id); if (!path || !train) continue; registered.add(path); if (!existsSync(join(absolute, path))) findings.push(finding("planner.train.registry-coherence", file, `registry train ${train} points to missing ${path}`)); }
+  const trainRoot = join(absolute, topology.planRoot, "_trains");
+  for (const path of await yamlFiles(trainRoot)) { const rel = relative(absolute, path).replaceAll("\\", "/"), pieces = relative(trainRoot, path).split(/[\\/]/); if (pieces.some(piece => piece.startsWith("_")) || registered.has(rel)) continue; findings.push(finding("planner.train.registry-coherence", rel, `train document is not registered in ${file}`)); }
   return findings;
 }
 
@@ -44,7 +45,7 @@ async function contractRegistry(root: string): Promise<ContractRegistry | null>
 }
 
 async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typeof validatePlan>>, registry: ContractRegistry | null): Promise<PlanFinding[]> {
-  const absolute = resolve(root), file = "plan/_themes.yaml", path = join(absolute, file);
+  const absolute = resolve(root), topology = await topologyFor(absolute), file = `${topology.planRoot}/_themes.yaml`, path = join(absolute, file);
   const declared: Array<{ theme: string; file: string }> = [];
   for (const artifact of graph.artifacts) {
     if (artifact.kind === "wagon" || artifact.kind === "interlocking") {
@@ -54,7 +55,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     }
   }
   for (const row of registry?.rows ?? []) { const theme = text(row.theme); if (theme) declared.push({ theme, file: registry?.file ?? file }); }
-  if (!existsSync(path)) return declared.length ? [finding("planner.theme.must-be-canonical", file, "themes are declared but plan/_themes.yaml is absent; add themes: { '0': commons } and repository-defined entries")] : [];
+  if (!existsSync(path)) return declared.length ? [finding("planner.theme.must-be-canonical", file, `themes are declared but ${file} is absent; add themes: { '0': commons } and repository-defined entries`)] : [];
   try {
     const doc = Bun.YAML.parse(await readFile(path, "utf8")) as { themes?: unknown };
     const themes = doc?.themes && typeof doc.themes === "object" && !Array.isArray(doc.themes) ? doc.themes as Record<string, unknown> : {};
@@ -63,7 +64,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     if (themes["0"] !== "commons") findings.push(finding("planner.theme.theme-zero-mandatory", file, "theme index 0 must be the reserved token commons"));
     for (const name of duplicate(values)) findings.push(finding("planner.theme.must-be-canonical", file, `theme ${name} is declared at more than one index`));
     const known = new Set(values);
-    for (const item of declared) if (!known.has(item.theme)) findings.push(finding("planner.theme.must-be-canonical", item.file, `theme ${item.theme} is not declared in plan/_themes.yaml`));
+    for (const item of declared) if (!known.has(item.theme)) findings.push(finding("planner.theme.must-be-canonical", item.file, `theme ${item.theme} is not declared in ${file}`));
     for (const artifact of graph.artifacts.filter(item => item.kind === "wagon")) {
       const wagonTheme = text(artifact.data.theme);
       for (const produced of records(artifact.data.produce)) {
@@ -82,7 +83,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     }
     return findings;
   } catch {
-    return [finding("planner.theme.must-be-canonical", file, "could not parse plan/_themes.yaml")];
+    return [finding("planner.theme.must-be-canonical", file, `could not parse ${file}`)];
   }
 }
 
@@ -247,7 +248,7 @@ function journeyContinuationFindings(graph: Awaited<ReturnType<typeof validatePl
 }
 
 /** Every interlocking is reached by a journey: as an entrypoint or through a continuation reachable from one. */
-function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePlan>>): PlanFinding[] {
+function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePlan>>, planRoot: string): PlanFinding[] {
   const interlockings = graph.artifacts.filter(item => item.kind === "interlocking"), journeys = graph.artifacts.filter(item => item.kind === "journey");
   const reached = new Set<string>();
   for (const journey of journeys) {
@@ -270,7 +271,7 @@ function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePla
     interlocking.file,
     journeys.length
       ? `${interlocking.id} is reached by none of the ${journeys.length} journey(s): no journey enters at it and no reachable continuation leads to it`
-      : `${interlocking.id} is not composed into any journey: the plan declares ${interlockings.length} interlocking(s) and no journey under plan/_journeys/`,
+      : `${interlocking.id} is not composed into any journey: the plan declares ${interlockings.length} interlocking(s) and no journey under ${planRoot}/_journeys/`,
   ));
 }
 
@@ -280,11 +281,11 @@ export async function validateStaticPlannerConventions(root = process.cwd()): Pr
   // Plan-graph integrity is a package guard with its own implementation contract.
   // This validator emits only the canonical convention ids declared by
   // planner.static.validators.bun.
-  const graph = await validatePlan(root), findings: PlanFinding[] = [], wagons = graph.artifacts.filter(artifact => artifact.kind === "wagon");
+  const topology = await topologyFor(root), graph = await validatePlan(root), findings: PlanFinding[] = [], wagons = graph.artifacts.filter(artifact => artifact.kind === "wagon");
   const wagonSlugs = new Set(wagons.map(wagon => text(wagon.data.wagon)));
   const wagonBySlug = new Map(wagons.map(wagon => [text(wagon.data.wagon), wagon]));
   const wagonIds = wagons.map(wagon => text(wagon.data.wagon));
-  for (const slug of duplicate(wagonIds)) findings.push(finding("planner.wagon.urn", wagonBySlug.get(slug)?.file ?? "plan/", `wagon slug ${slug} is declared more than once`));
+  for (const slug of duplicate(wagonIds)) findings.push(finding("planner.wagon.urn", wagonBySlug.get(slug)?.file ?? `${topology.planRoot}/`, `wagon slug ${slug} is declared more than once`));
 
   const contractOwners = new Map<string, string[]>(), telemetryOwners = new Map<string, string[]>();
   for (const wagon of wagons) {
@@ -305,13 +306,13 @@ export async function validateStaticPlannerConventions(root = process.cwd()): Pr
     }
   }
   const registry = await contractRegistry(root);
-  for (const [contract, owners] of contractOwners) if (owners.length > 1) findings.push(finding("planner.contract.registry-coherence", wagonBySlug.get(owners[0])?.file ?? "plan/", `contract ${contract} is produced by ${owners.join(", ")}`));
-  for (const [telemetry, owners] of telemetryOwners) if (owners.length > 1) findings.push(finding("planner.wagon.telemetry-filesystem", wagonBySlug.get(owners[0])?.file ?? "plan/", `telemetry ${telemetry} is produced by ${owners.join(", ")}`));
+  for (const [contract, owners] of contractOwners) if (owners.length > 1) findings.push(finding("planner.contract.registry-coherence", wagonBySlug.get(owners[0])?.file ?? `${topology.planRoot}/`, `contract ${contract} is produced by ${owners.join(", ")}`));
+  for (const [telemetry, owners] of telemetryOwners) if (owners.length > 1) findings.push(finding("planner.wagon.telemetry-filesystem", wagonBySlug.get(owners[0])?.file ?? `${topology.planRoot}/`, `telemetry ${telemetry} is produced by ${owners.join(", ")}`));
   findings.push(...contractRegistryFindings(root, wagons, registry));
   findings.push(...await themeRegistryFindings(root, graph, registry));
   findings.push(...await trainRegistryFindings(root));
   findings.push(...journeyContinuationFindings(graph));
-  findings.push(...journeyCompositionFindings(graph));
+  findings.push(...journeyCompositionFindings(graph, topology.planRoot));
 
   return findings;
 }

package/src/topology.ts

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export type Topology = { planRoot: string; sourceRoot: string; testRoot: string; e2eRoot: string };
+
+export const defaultTopology: Topology = {
+  planRoot: "plan",
+  sourceRoot: "src/wagons",
+  testRoot: "tests/wagons",
+  e2eRoot: "e2e",
+};
+
+const configuredKeys: Array<[keyof Topology, string]> = [
+  ["planRoot", "plan_root"],
+  ["sourceRoot", "source_root"],
+  ["testRoot", "test_root"],
+  ["e2eRoot", "e2e_root"],
+];
+
+function safeRelative(value: unknown): string | null {
+  if (typeof value !== "string" || !value || value.startsWith("/")) return null;
+  const normalized = value.replaceAll("\\", "/").replace(/\/$/, "");
+  return normalized && !normalized.split("/").includes("..") ? normalized : null;
+}
+
+/** Read the one shared topology configuration used by every plan consumer. Invalid
+ * location overrides deliberately fall back to the strict defaults; the topology
+ * detector reports the bad configuration as a violation. */
+export async function topologyFor(root = process.cwd()): Promise<Topology> {
+  const absolute = resolve(root), file = join(absolute, "atdd-bun.yaml");
+  if (!existsSync(file)) return { ...defaultTopology };
+  try {
+    const data = Bun.YAML.parse(await readFile(file, "utf8")) as { topology?: Record<string, unknown> } | null;
+    const supplied = data?.topology && typeof data.topology === "object" && !Array.isArray(data.topology) ? data.topology : {};
+    const topology = { ...defaultTopology };
+    for (const [property, key] of configuredKeys) topology[property] = safeRelative(supplied[key]) ?? topology[property];
+    return topology;
+  } catch { return { ...defaultTopology }; }
+}