@afokapu/atdd-bun 0.10.53 → 0.10.55

package/detectors/bun_interlocking_infrastructure/checks/journey_station_routing.mjs

@@ -56,6 +56,28 @@ function actionMapping(text, action) {
   return { body: match[1], line: lineOfIndex(masked, match.index) };
 }
 
+function matchingBrace(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "{") depth++;
+    else if (text[i] === "}" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function dispatchInvokesMappedJourneyRunner(text) {
+  const masked = maskComments(text);
+  const dispatch = /\b(?:async\s+)?function\s+dispatch\s*\([^)]*\)\s*\{/.exec(masked);
+  if (!dispatch) return false;
+  const open = dispatch.index + dispatch[0].length - 1;
+  const close = matchingBrace(masked, open);
+  const body = masked.slice(open + 1, close < 0 ? masked.length : close);
+  const direct = /\breturn\s+(?:await\s+)?new\s+JourneyRunner\s*\(\s*[A-Za-z_$][\w$]*\s*\.\s*path\s*\)\s*\.\s*execute\s*\(/.test(body);
+  const constructed = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*new\s+JourneyRunner\s*\(\s*[A-Za-z_$][\w$]*\s*\.\s*path\s*\)/.exec(body);
+  const delegated = constructed && new RegExp("\\breturn\\s+(?:await\\s+)?" + constructed[1] + "\\s*\\.\\s*execute\\s*\\(").test(body);
+  return direct || delegated;
+}
+
 for (const scanRoot of roots) {
   for (const croot of findConsumerRoots(scanRoot)) {
     const journeys = journeyDocuments(croot).filter(item => item.data?.entrypoint?.exposed === true);
@@ -76,6 +98,14 @@ for (const scanRoot of roots) {
       "journey-station-unlinked: exposed journeys exist but Station Master never references JourneyRunner",
       lineAt(text, 1),
     ));
+    if (referencesToken(text, "JourneyRunner") && !dispatchInvokesMappedJourneyRunner(text)) violations.push(mk(
+      RULE,
+      appPath,
+      1,
+      0,
+      "journey-station-dispatch-bypasses-runner: Station Master dispatch must return a JourneyRunner execution for the mapped exposed journey",
+      lineAt(text, 1),
+    ));
 
     for (const journey of journeys) {
       const id = String(journey.data.journey_id ?? "");

package/detectors/bun_interlocking_infrastructure/checks/wagon_contract_honoured.mjs

@@ -24,7 +24,7 @@
 // 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, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 
 const RULE = "coder.bun.wagon-honours-its-contract";
 const EXCLUDES = ["node_modules", "dist", "build", ".next", ".git", "_generated"];
@@ -101,6 +101,95 @@ export function maskComments(text) {
     .replace(/(^|[^:\\])\/\/[^\n]*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
 }
 
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+function closingBrace(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "{") depth++;
+    else if (text[i] === "}" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function handlerBody(text, name) {
+  const escaped = escape(name);
+  const forms = [
+    new RegExp(`\\b(?:export\\s+)?(?:async\\s+)?function\\s+${escaped}\\s*\\([^)]*\\)\\s*(?::[^={]+)?\\{`),
+    new RegExp(`\\b(?:export\\s+)?(?:const|let)\\s+${escaped}\\s*=\\s*(?:async\\s*)?\\([^)]*\\)\\s*=>\\s*\\{`),
+  ];
+  for (const form of forms) {
+    const match = form.exec(text);
+    if (!match) continue;
+    const open = match.index + match[0].lastIndexOf("{");
+    const close = closingBrace(text, open);
+    if (close >= 0) return text.slice(open + 1, close);
+  }
+  return "";
+}
+
+function localConstants(text) {
+  const values = new Map();
+  const re = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*["']([^"']+)["']/g;
+  let match;
+  while ((match = re.exec(text)) !== null) values.set(match[1], match[2]);
+  return values;
+}
+
+function artifactArgument(argument, constants) {
+  const literal = /^\s*["']([^"']+)["']\s*$/.exec(argument);
+  if (literal) return literal[1];
+  const identifier = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(argument);
+  return identifier ? constants.get(identifier[1]) ?? null : null;
+}
+
+function cargoMoves(handler, module) {
+  const constants = localConstants(module), reads = new Set(), writes = new Set();
+  for (const [method, target] of [["get", reads], ["put", writes]]) {
+    const re = new RegExp(`\\bcargo\\s*\\.\\s*${method}\\s*\\(\\s*([^,)]*)`, "g");
+    let match;
+    while ((match = re.exec(handler)) !== null) {
+      const artifact = artifactArgument(match[1], constants);
+      if (artifact) target.add(artifact);
+    }
+  }
+  return { reads, writes };
+}
+
+function importedHandlers(runner) {
+  const handlers = [];
+  const re = /^\s*import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/gm;
+  let match;
+  while ((match = re.exec(runner.text)) !== null) {
+    if (!match[2].startsWith(".")) continue;
+    const target = resolve(dirname(runner.file), match[2]);
+    const file = [target, `${target}.ts`, `${target}.tsx`, join(target, "index.ts")]
+      .find((candidate) => runner.sources.has(candidate));
+    if (!file) continue;
+    for (const entry of match[1].split(",")) {
+      const [imported, local = imported] = entry.trim().split(/\s+as\s+/);
+      if (imported && local && imported !== "Cargo") handlers.push({ name: local.trim(), file });
+    }
+  }
+  return handlers;
+}
+
+function executedHandlers(wagon, runners, sources) {
+  const handlers = [];
+  const wagonLiteral = escape(wagon);
+  for (const runner of runners) {
+    const imports = importedHandlers({ ...runner, sources });
+    for (const handler of imports) {
+      const branch = new RegExp(
+        `\\b(?:if\\s*\\(\\s*step\\s*={2,3}\\s*["']${wagonLiteral}["']\\s*\\)|case\\s*["']${wagonLiteral}["']\\s*:)` +
+        `[\\s\\S]{0,240}?\\b${escape(handler.name)}\\s*\\(\\s*cargo\\b`,
+      );
+      if (branch.test(runner.text)) handlers.push(handler);
+    }
+  }
+  return handlers;
+}
+
 const reportPath = process.env.ATDD_VIOLATIONS_REPORT;
 if (!reportPath) {
   process.stderr.write("bun-infra: ATDD_VIOLATIONS_REPORT not set\n");
@@ -126,26 +215,37 @@ for (const root of parseJsonEnv("ATDD_SCAN_ROOTS", [])) {
     if (!contracts.length) continue;                     // no declared contract
 
     const sources = walk(croot, (p) => TS.test(p) && !TEST.test(p), excludes)
-      .map((f) => ({ file: f, text: read(f) }));
-    // A wagon implementation is one that moves artifacts through Cargo. Detected by
-    // that behaviour rather than by filename — a `wagon.ts` naming heuristic is the
-    // kind of fitted check this hub has had to unpick more than once.
-    const wagonCode = sources.filter((s) => /\bCargo\b|\bcargo\s*\.\s*(?:put|get)\s*\(/.test(s.text));
-    if (!wagonCode.length) continue;                     // nothing implemented to judge
-
-    const blob = wagonCode.map((s) => maskComments(s.text)).join("\n");
+      .map((file) => ({ file, text: maskComments(read(file)) }));
+    // Do not turn a plan-only repository into a contract failure. Once this consumer
+    // does have Cargo-shaped source, however, each carried wagon must bind its own
+    // handler into the train path; a global source blob is not evidence of that.
+    if (!sources.some((s) => /\bCargo\b|\bcargo\s*\.\s*(?:put|get)\s*\(/.test(s.text))) continue;
+    const sourceByFile = new Map(sources.map((source) => [source.file, source.text]));
+    const trainRoot = join(croot, "src", "trains") + sep;
+    const runners = sources.filter((source) => source.file.startsWith(trainRoot));
     for (const c of contracts) {
       if (c.wagon && !carried.has(c.wagon)) continue;   // no train carries this wagon yet
+      const handlers = c.wagon ? executedHandlers(c.wagon, runners, sourceByFile) : [];
+      const reads = new Set(), writes = new Set();
+      for (const handler of handlers) {
+        const module = sourceByFile.get(handler.file) ?? "";
+        const body = handlerBody(module, handler.name);
+        const moves = cargoMoves(body, module);
+        for (const artifact of moves.reads) reads.add(artifact);
+        for (const artifact of moves.writes) writes.add(artifact);
+      }
       for (const [kind, names] of [["produce", c.produce], ["consume", c.consume]]) {
         for (const name of names) {
-          if (blob.includes(name)) continue;
+          const moved = kind === "produce" ? writes : reads;
+          if (moved.has(name)) continue;
           const rel = c.file.startsWith(croot + sep) ? c.file.slice(croot.length + 1) : c.file;
           violations.push({
             rule_id: RULE, file: rel, line: 1, col: 0,
             evidence:
               `the wagon declares it ${kind === "produce" ? "produces" : "consumes"} ` +
-              `"${name}", and no wagon implementation names it; the declared contract and ` +
-              `the Cargo it actually moves are free to disagree`,
+              `"${name}", but no handler reachable from that wagon's train step ` +
+              `${kind === "produce" ? "writes" : "reads"} it through Cargo; artifact constants ` +
+              `or unrelated Cargo code do not honour the wagon contract`,
             source_line: "",
           });
         }

package/detectors/bun_interlocking_infrastructure/fixtures/clean/journey_runner_boundary/src/trains/journey.ts

@@ -6,10 +6,23 @@ export class JourneyRunner {
   async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
     const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as {
       entrypoint: { interlocking_id: string };
+      continuations: Array<{ from: { interlocking_id: string; route_id: string }; to: { interlocking_id: string } }>;
+      terminals: Array<{ from: { interlocking_id: string; route_id: string }; outcome: string }>;
     };
-    const id = declaration.entrypoint.interlocking_id.replace("interlocking:", "");
-    const path = `plan/_trains/_interlockings/${id}.yaml`;
-    const runner = new InterlockingRunner(path);
-    return runner.execute(action, inputs, state);
+    let current = declaration.entrypoint.interlocking_id;
+    for (;;) {
+      const id = current.replace("interlocking:", "");
+      const path = `plan/_trains/_interlockings/${id}.yaml`;
+      const runner = new InterlockingRunner(path);
+      const resolution = await runner.execute(action, inputs, state);
+      const continuation = declaration.continuations.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (continuation) {
+        current = continuation.to.interlocking_id;
+        continue;
+      }
+      const terminal = declaration.terminals.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (terminal) return { resolution, outcome: terminal.outcome };
+      throw new Error(`Journey topology has no outcome for ${current}`);
+    }
   }
 }

package/detectors/bun_interlocking_infrastructure/fixtures/clean/journey_station_routing/src/trains/journey.ts

@@ -6,9 +6,22 @@ export class JourneyRunner {
   async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
     const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as {
       entrypoint: { interlocking_id: string };
+      continuations: Array<{ from: { interlocking_id: string; route_id: string }; to: { interlocking_id: string } }>;
+      terminals: Array<{ from: { interlocking_id: string; route_id: string }; outcome: string }>;
     };
-    const id = declaration.entrypoint.interlocking_id.replace("interlocking:", "");
-    const path = `plan/_trains/_interlockings/${id}.yaml`;
-    return new InterlockingRunner(path).execute(action, inputs, state);
+    let current = declaration.entrypoint.interlocking_id;
+    for (;;) {
+      const id = current.replace("interlocking:", "");
+      const path = `plan/_trains/_interlockings/${id}.yaml`;
+      const resolution = await new InterlockingRunner(path).execute(action, inputs, state);
+      const continuation = declaration.continuations.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (continuation) {
+        current = continuation.to.interlocking_id;
+        continue;
+      }
+      const terminal = declaration.terminals.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (terminal) return { resolution, outcome: terminal.outcome };
+      throw new Error(`Journey topology has no outcome for ${current}`);
+    }
   }
 }

package/detectors/bun_interlocking_infrastructure/fixtures/clean/journey_topology_traversal/plan/_journeys/checkout.yaml

@@ -0,0 +1,19 @@
+schema_version: 1.0.0
+journey_id: journey:checkout
+title: Checkout
+status: checked
+entrypoint:
+  interlocking_id: interlocking:cart
+  exposed: true
+  actions: [checkout]
+  reason: null
+  surfaces: [backend]
+continuations:
+  - from: { interlocking_id: interlocking:cart, route_id: ready }
+    artifact: order:prepared
+    to: { interlocking_id: interlocking:payment }
+terminals:
+  - from: { interlocking_id: interlocking:cart, route_id: empty }
+    outcome: empty-cart
+  - from: { interlocking_id: interlocking:payment, route_id: paid }
+    outcome: completed

package/detectors/bun_interlocking_infrastructure/fixtures/clean/journey_topology_traversal/server.ts

@@ -0,0 +1,13 @@
+import { JourneyRunner } from "./src/trains/journey";
+
+export const JOURNEY_MAP = {
+  checkout: {
+    journeyId: "journey:checkout",
+    path: "plan/_journeys/checkout.yaml",
+  },
+};
+
+export function dispatch(action: string, inputs: Record<string, unknown>, state?: unknown) {
+  const mapping = JOURNEY_MAP[action as keyof typeof JOURNEY_MAP];
+  return new JourneyRunner(mapping.path).execute(action, inputs, state);
+}

package/detectors/bun_interlocking_infrastructure/fixtures/clean/journey_topology_traversal/src/trains/journey.ts

@@ -0,0 +1,36 @@
+import { InterlockingRunner } from "@app/interlocking-runtime";
+
+type Topology = {
+  entrypoint: { interlocking_id: string };
+  continuations: Array<{
+    from: { interlocking_id: string; route_id: string };
+    artifact: string;
+    to: { interlocking_id: string };
+  }>;
+  terminals: Array<{
+    from: { interlocking_id: string; route_id: string };
+    outcome: string;
+  }>;
+};
+
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
+    const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as Topology;
+    let current = declaration.entrypoint.interlocking_id;
+    for (;;) {
+      const id = current.replace("interlocking:", "");
+      const path = `plan/_trains/_interlockings/${id}.yaml`;
+      const resolution = await new InterlockingRunner(path).execute(action, inputs, state);
+      const continuation = declaration.continuations.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (continuation) {
+        current = continuation.to.interlocking_id;
+        continue;
+      }
+      const terminal = declaration.terminals.find(edge => edge.from.interlocking_id === current && edge.from.route_id === resolution.routeId);
+      if (terminal) return { resolution, outcome: terminal.outcome };
+      throw new Error(`Journey topology has no outcome for ${current}`);
+    }
+  }
+}

package/detectors/bun_interlocking_infrastructure/fixtures/clean/wagon_contract_honoured/src/trains/runner.ts

@@ -0,0 +1,5 @@
+import { Cargo, runWagon } from "../orders/wagon";
+
+export function runTrain(step: string, cargo: Cargo): void {
+  if (step === "confirm-order") runWagon(cargo);
+}

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_dead_read/plan/_journeys/checkout.yaml

@@ -0,0 +1,14 @@
+schema_version: 1.0.0
+journey_id: journey:checkout
+entrypoint:
+  interlocking_id: interlocking:cart
+  exposed: false
+  actions: []
+  surfaces: [backend]
+continuations:
+  - from: { interlocking_id: interlocking:cart, route_id: ready }
+    artifact: order:prepared
+    to: { interlocking_id: interlocking:payment }
+terminals:
+  - from: { interlocking_id: interlocking:payment, route_id: paid }
+    outcome: completed

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_dead_read/src/trains/journey.ts

@@ -0,0 +1,15 @@
+import { InterlockingRunner } from "@app/interlocking-runtime";
+
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
+    const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as any;
+    const id = declaration.entrypoint.interlocking_id.replace("interlocking:", "");
+    const path = `plan/_trains/_interlockings/${id}.yaml`;
+    const resolution = await new InterlockingRunner(path).execute(action, inputs, state);
+    declaration.continuations.find((edge: any) => edge.from.route_id === resolution.routeId);
+    declaration.terminals.find((edge: any) => edge.from.route_id === resolution.routeId);
+    return resolution;
+  }
+}

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_returns_early/plan/_journeys/checkout.yaml

@@ -0,0 +1,19 @@
+schema_version: 1.0.0
+journey_id: journey:checkout
+title: Checkout
+status: checked
+entrypoint:
+  interlocking_id: interlocking:cart
+  exposed: false
+  actions: []
+  reason: internal-transition-only
+  surfaces: [backend]
+continuations:
+  - from: { interlocking_id: interlocking:cart, route_id: ready }
+    artifact: order:prepared
+    to: { interlocking_id: interlocking:payment }
+terminals:
+  - from: { interlocking_id: interlocking:cart, route_id: empty }
+    outcome: empty-cart
+  - from: { interlocking_id: interlocking:payment, route_id: paid }
+    outcome: completed

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_returns_early/src/trains/journey.ts

@@ -0,0 +1,16 @@
+import { InterlockingRunner } from "@app/interlocking-runtime";
+
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
+    const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as {
+      entrypoint: { interlocking_id: string };
+      continuations: unknown[];
+      terminals: unknown[];
+    };
+    const id = declaration.entrypoint.interlocking_id.replace("interlocking:", "");
+    const path = `plan/_trains/_interlockings/${id}.yaml`;
+    return new InterlockingRunner(path).execute(action, inputs, state);
+  }
+}

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_self_loop/plan/_journeys/checkout.yaml

@@ -0,0 +1,14 @@
+schema_version: 1.0.0
+journey_id: journey:checkout
+entrypoint:
+  interlocking_id: interlocking:cart
+  exposed: false
+  actions: []
+  surfaces: [backend]
+continuations:
+  - from: { interlocking_id: interlocking:cart, route_id: ready }
+    artifact: order:prepared
+    to: { interlocking_id: interlocking:payment }
+terminals:
+  - from: { interlocking_id: interlocking:payment, route_id: paid }
+    outcome: completed

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_continuation_self_loop/src/trains/journey.ts

@@ -0,0 +1,18 @@
+import { InterlockingRunner } from "@app/interlocking-runtime";
+
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  async execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
+    const declaration = Bun.YAML.parse(await Bun.file(this.journeyYamlPath).text()) as any;
+    let current = declaration.entrypoint.interlocking_id;
+    for (;;) {
+      const id = current.replace("interlocking:", "");
+      const resolution = await new InterlockingRunner(`plan/_trains/_interlockings/${id}.yaml`).execute(action, inputs, state);
+      const continuation = declaration.continuations.find((edge: any) => edge.from.route_id === resolution.routeId);
+      if (continuation) { current = current; continue; }
+      const terminal = declaration.terminals.find((edge: any) => edge.from.route_id === resolution.routeId);
+      if (terminal) return resolution;
+    }
+  }
+}

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_station_inert_runner/plan/_journeys/public.yaml

@@ -0,0 +1,14 @@
+schema_version: 1.0.0
+journey_id: journey:public
+title: Public journey
+status: checked
+entrypoint:
+  interlocking_id: interlocking:first
+  exposed: true
+  actions: [start_journey]
+  reason: null
+  surfaces: [backend]
+continuations: []
+terminals:
+  - from: { interlocking_id: interlocking:first, route_id: done }
+    outcome: completed

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_station_inert_runner/server.ts

@@ -0,0 +1,16 @@
+import { JourneyRunner } from "./src/trains/journey";
+import { createOrder } from "./src/orders/create";
+
+export const JOURNEY_MAP = {
+  start_journey: {
+    journeyId: "journey:public",
+    path: "plan/_journeys/public.yaml",
+  },
+};
+
+export function dispatch(action: string, inputs: Record<string, unknown>) {
+  const mapping = JOURNEY_MAP[action as keyof typeof JOURNEY_MAP];
+  void JourneyRunner;
+  void mapping;
+  return createOrder(inputs);
+}

package/detectors/bun_interlocking_infrastructure/fixtures/dirty/journey_station_inert_runner/src/trains/journey.ts

@@ -0,0 +1,9 @@
+import { InterlockingRunner } from "@app/interlocking-runtime";
+
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  execute(action: string, inputs: Record<string, unknown>, state?: unknown) {
+    return new InterlockingRunner(this.journeyYamlPath).execute(action, inputs, state);
+  }
+}