@afokapu/atdd-bun 0.10.106 → 0.10.108

package/detectors/bun_interlocking_coverage/_shared/interlocking.mjs

@@ -8,7 +8,7 @@
 // data (snake_case, plan/_trains/_interlockings/**); the e2e tests are Bun/TS under e2e/**.
 
 import { excludedPath } from "../../../lib/scan.mjs";
-import { directInterlockingExecutionProofs, entryDelegatedAction, provenJourneyAction } from "../../../lib/journey-chain.mjs";
+import { directInterlockingExecutionProofs, entryDelegatedAction, provenJourneyAction, transparentCallbackAliases } from "../../../lib/journey-chain.mjs";
 import { existsSync, readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 
@@ -529,7 +529,11 @@ function firstRebinding(text, name, executeArgument, returns) {
 function resolutionBinding(after, resolution, executeArgument) {
   const statement = after.slice(enclosingEnd(after) + 1);
   const scope = statement.slice(0, enclosingEnd(statement));
-  return { scope, bound: scope.slice(0, firstRebinding(scope, resolution, executeArgument, topLevelReturns(scope))) };
+  return {
+    scope,
+    offset: after.length - statement.length,
+    bound: scope.slice(0, firstRebinding(scope, resolution, executeArgument, topLevelReturns(scope))),
+  };
 }
 
 function trainExecutionForms(resolution) {
@@ -541,15 +545,20 @@ function trainExecutionForms(resolution) {
   return { legacy, constructed, declaration: `${constructed}${r}\\s*(?:,|\\))` };
 }
 
-function resolutionTrainExecution(after, resolution) {
+// `aliases` are the transparent callback-return aliases of this resolution's execution (see
+// transparentCallbackAliases); only one declared inside the resolution's binding names the execution.
+function resolutionTrainExecution(after, resolution, aliases = [], base = 0) {
   const { legacy, constructed, declaration } = trainExecutionForms(resolution);
-  const { scope, bound } = resolutionBinding(after, resolution, constructed);
+  const { scope, bound, offset } = resolutionBinding(after, resolution, constructed);
   const assignment = `\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?`;
   const assigned = new RegExp(`${assignment}${legacy}`).exec(after) ?? new RegExp(`${assignment}${declaration}`).exec(bound);
   const returns = `\\breturn\\s+(?:await\\s+)?`;
+  const first = base + offset;
+  const alias = aliases.find((candidate) => candidate.start >= first && candidate.start < first + bound.length);
   return {
     execution: assigned?.[1] ?? null,
-    found: Boolean(assigned || new RegExp(legacy).test(after) || new RegExp(declaration).test(bound)),
+    alias: alias?.alias ?? null,
+    found: Boolean(assigned || alias || new RegExp(legacy).test(after) || new RegExp(declaration).test(bound)),
     returned: new RegExp(`${returns}${legacy}`).test(after) || returnsMatch(scope, declaration, bound.length) ||
       Boolean(assigned && new RegExp(`${returns}${escaped(assigned[1])}\\s*;?`).test(after)),
   };
@@ -566,12 +575,23 @@ export function productionExecutionProofs(text, file, croot) {
     const direct = new RegExp(`new\\s+${PROD_INTERLOCKING}\\b`).test(receiver);
     const named = [...receivers].some((name) => receiver.trim().endsWith(name));
     if (!direct && !named) continue;
-    const proof = resolutionTrainExecution(text.slice((m.index ?? 0) + whole.length), resolution);
+    const base = (m.index ?? 0) + whole.length;
+    const proof = resolutionTrainExecution(text.slice(base), resolution,
+      file ? transparentCallbackAliases(text, file, resolution) : [], base);
     if (proof.found) proofs.push({ resolution, execution: proof.execution });
+    if (proof.alias && proof.alias !== proof.execution) proofs.push({ resolution, execution: proof.alias });
   }
   return proofs;
 }
 
+// A member read of a binding: `.` or the optional-chain `?.`. Calls and writes are never matched here.
+const MEMBER = "\\??\\.";
+
+// Name of the const/let/var bound to `<execution>.trace` (or `<execution>?.trace`), or undefined.
+function boundTraceName(text, execution) {
+  return new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${escaped(execution)}${MEMBER}trace\\b`).exec(text)?.[1];
+}
+
 export function assertsExpression(text, expression, expected = null) {
   const pat = new RegExp(`\\bexpect\\s*\\(\\s*(?:await\\s+)?${expression}\\s*\\)\\s*\\.(?:to(?:Be|BeDefined|Equal|StrictEqual|Contain|ContainEqual|MatchObject|Match|BeTruthy)|not\\.to(?:Be|BeDefined|Equal|StrictEqual|Contain|ContainEqual|MatchObject|Match))\\b([\\s\\S]{0,220})`);
   const m = pat.exec(text);
@@ -591,8 +611,8 @@ export function hasProductionExecutionProof(text, file, croot) {
     if (assertsExpression(text, `${escaped(resolution)}\\.(?:routeId|trainId|selectedTrainId)`) ||
       (execution && assertsExpression(text, escaped(execution)))) return true;
     if (!execution) return false;
-    const trace = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${escaped(execution)}\\.trace\\b`).exec(text)?.[1];
-    return Boolean(trace && REQUIRED_TRACE_FIELDS.some(([field]) => assertsExpression(text, `${escaped(trace)}\\.${field}`)));
+    const trace = boundTraceName(text, execution);
+    return Boolean(trace && REQUIRED_TRACE_FIELDS.some(([field]) => assertsExpression(text, `${escaped(trace)}${MEMBER}${field}`)));
   });
 }
 
@@ -617,13 +637,13 @@ export function traceHasProductionProvenance(text, file, croot) {
   return productionExecutionProofs(text, file, croot).some(({ execution, direct }) => {
     if (direct) return direct.traceBound && REQUIRED_TRACE_FIELDS.every(([field]) => direct.traceFields.includes(field));
     if (!execution) return false;
-    const trace = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${escaped(execution)}\\.trace\\b`).exec(text)?.[1];
+    const trace = boundTraceName(text, execution);
     return Boolean(trace);
   });
 }
 
 export function assertedTraceFields(text, traceName = "trace") {
-  return REQUIRED_TRACE_FIELDS.filter(([field]) => !assertsExpression(text, `${escaped(traceName)}\\.${field}`)).map(([field]) => field);
+  return REQUIRED_TRACE_FIELDS.filter(([field]) => !assertsExpression(text, `${escaped(traceName)}${MEMBER}${field}`)).map(([field]) => field);
 }
 
 // A smoke path has a real Station Master call and observes that call's returned value; separately

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.106",
+  "version": "0.10.108",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "README.md": "8aefceaa24bee498f39081b2aaf4c0d5c54bc1ed9849c20e1d98d1427df56eab",
@@ -384,7 +384,7 @@
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/server.ts": "d5bc34c5b1b2b0a511e0c4604ce6f9c77491dca9aee994be720540f3052babc1",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/interlocking.ts": "9bcfdb4ecff6efd1f658b9fd587342615179924e25468c75daa07c2626d4d8ab",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/runner.ts": "0e4b885e50f12cc2a8c8f6740bf83e7b2e7137a28e1e143586e9a8550ea5bd45",
-    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "e4de9503c31ed631e2e6a0bd5b21e78ee8ca1f1186fa93ff65106ff47695013e",
+    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "f6a716c4ef612a0f1bf7b612587c4af94d8e6aaa89ecdb8acee7cc977609bf43",
     "detectors/bun_interlocking_coverage/atdd.implementation.yaml": "f160517a8138ba3ca05e3d130e6fbfb796e643376f25743fdef4fc210196525b",
     "detectors/bun_interlocking_coverage/checks/_map.json": "0a218ea319cc6258af7bd721c2154cb9561fe67e80d80ef32d08fc77bc9403c3",
     "detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs": "97224d46f0c4c3259f15e41f90bb7f9f5a4e651d4facd41f1e037cac919be500",
@@ -1033,7 +1033,7 @@
     "lib/frontend.mjs": "d6d9b29c3d7f2d162cda03bb34b20a3224a82887b6be3db7cab375510913c9a3",
     "lib/imports.mjs": "3db4979269488fa26f6e7aefded6ece9c646be6587a10e249821a5a208109962",
     "lib/interlocking.mjs": "d0803d080ac7d7477c51be70112df1e85213d339fd3c6b71f75f26145fa8accd",
-    "lib/journey-chain.mjs": "34b1efa073b17940fa398af2970c85bb2fac35e4b2608ce635cfb6c39e3adc53",
+    "lib/journey-chain.mjs": "bede441e5d61ea950ed5b76bbb6357ef0d2057cb29053ed32df1faab33ad9ac1",
     "lib/scan.mjs": "b6973e411ecd14c548a055c871e01e948f002b772042136be8401f38d998e687",
     "planner-nodes/ENFORCEMENT_SCOPE.yaml": "47aa9c78a4bb1754c6b435f5e056038baa04a24cd48df2c205db2bc08a3a3cac",
     "planner-nodes/nodes/planner.acceptance.abstract-fields-required.convention.yaml": "bd565693f0ae861f0561ad2f7a91a8c55f9a209c3acd59c5750cfcffd96a85d8",

package/lib/journey-chain.mjs

@@ -767,6 +767,113 @@ function awaitedCall(expression) {
   return value && ts.isAwaitExpression(value) ? unwrap(value.expression) : null;
 }
 
+// Every `return` of `fn` (catch and `finally` bodies included, nested functions excluded), as expressions.
+function everyReturn(fn) {
+  if (!fn.body) return null;
+  if (!ts.isBlock(fn.body)) return [fn.body];
+  const returns = [];
+  walk(fn.body, (node) => { if (ts.isReturnStatement(node)) returns.push(node.expression ?? null); }, false);
+  return returns;
+}
+
+// True when `fn` has live returns and EVERY return (live or not, catch/finally included) satisfies `accept`.
+function alwaysReturns(fn, accept) {
+  const all = everyReturn(fn), live = liveReturns(fn);
+  return Boolean(all?.length && live?.length && all.every(accept));
+}
+
+// True when `node` assigns to or increments/decrements the binding `symbol`.
+function writesSymbol(ctx, node, symbol) {
+  const target = ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+    node.operatorToken.kind <= ts.SyntaxKind.LastAssignment ? node.left
+    : (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+      (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken) ? node.operand : null;
+  return Boolean(target && ts.isIdentifier(unwrap(target)) && symbolOf(ctx, unwrap(target)) === symbol);
+}
+
+// The function bound to `identifier`: a declaration, or a `const` arrow/function expression.
+function localFunction(ctx, identifier) {
+  const declaration = declarationOf(ctx, identifier);
+  if (!declaration) return null;
+  if (ts.isFunctionDeclaration(declaration) && declaration.body) return declaration;
+  const initializer = constInitializer(ctx, identifier);
+  const value = initializer && unwrap(initializer);
+  return value && (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) ? value : null;
+}
+
+// A wrapper whose every return, on every path, IS the unchanged result of its callback parameter:
+// `return work()` / `return await work()`. Anything that replaces, conditions, copies or discards the
+// callback's value (spread, ternary, comma, a second return value, a returning catch) is not transparent.
+function transparentWrapper(ctx, fn) {
+  const param = fn.parameters[0];
+  if (!param || !ts.isIdentifier(param.name) || param.dotDotDotToken || fn.asteriskToken) return false;
+  const symbol = symbolOf(ctx, param.name);
+  if (!symbol) return false;
+  const isWork = (expression) => {
+    const call = expression && unwrap(expression);
+    return Boolean(call && ts.isCallExpression(call) && call.arguments.length === 0 &&
+      ts.isIdentifier(unwrap(call.expression)) && symbolOf(ctx, unwrap(call.expression)) === symbol);
+  };
+  if (!alwaysReturns(fn, isWork)) return false;
+  let rebound = false;
+  walk(fn.body, (node) => { rebound ||= writesSymbol(ctx, node, symbol); });
+  return !rebound;
+}
+
+// `const <alias> = await <wrapper>(<callback>)` where the local wrapper is transparent and every return of
+// the zero-parameter callback IS the production execution of `resolution` (the call itself, or a `const`
+// bound to it), so `<alias>` IS that execution. Returns [{ alias, start }] in source order.
+// Production forms: `new TrainRunner(<resolution>.trainId|selectedTrainId).execute(...)` and
+// `new TrainRunner(<resolution>.trainPath, ...).execute(<resolution>, ...)`.
+export function transparentCallbackAliases(text, file, resolution) {
+  if (!text || !file || !resolution) return [];
+  const ctx = analyze(file, text);
+  const aliases = [];
+  const isResolutionMember = (node, names) => {
+    node = node && unwrap(node);
+    return Boolean(node && ts.isPropertyAccessExpression(node) && names.includes(node.name.text) &&
+      ts.isIdentifier(node.expression) && node.expression.text === resolution && declarationOf(ctx, node.expression));
+  };
+  const isExecution = (node) => {
+    const call = unwrap(node);
+    if (!call || !ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression) ||
+      call.expression.name.text !== "execute") return false;
+    const construction = unwrap(call.expression.expression);
+    if (!construction || !ts.isNewExpression(construction) || !ts.isIdentifier(construction.expression) ||
+      construction.expression.text !== "TrainRunner" || !construction.arguments?.length) return false;
+    const [first] = construction.arguments;
+    if (isResolutionMember(first, ["trainId", "selectedTrainId"])) return construction.arguments.length === 1;
+    const executed = call.arguments[0] && unwrap(call.arguments[0]);
+    return isResolutionMember(first, ["trainPath"]) && Boolean(executed && ts.isIdentifier(executed) &&
+      executed.text === resolution && declarationOf(ctx, executed));
+  };
+  const isIdentity = (expression, seen = new Set()) => {
+    const node = expression && unwrap(expression);
+    if (!node) return false;
+    if (ts.isCallExpression(node)) return isExecution(node);
+    if (!ts.isIdentifier(node)) return false;
+    const initializer = constInitializer(ctx, node);
+    if (!initializer || seen.has(initializer)) return false;
+    seen.add(initializer);
+    return isIdentity(initializer, seen);
+  };
+  walk(ctx.source, (node) => {
+    if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer ||
+      !(ts.isVariableDeclarationList(node.parent) && node.parent.flags & ts.NodeFlags.Const) ||
+      dead(node, ctx.source) || insideCatch(node, ctx.source)) return;
+    const awaited = awaitedCall(node.initializer);
+    if (!awaited || !ts.isCallExpression(awaited) || !ts.isIdentifier(awaited.expression) || awaited.arguments.length !== 1) return;
+    const callback = unwrap(awaited.arguments[0]);
+    if (!callback || !(ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) ||
+      callback.parameters.length > 0 || callback.asteriskToken) return;
+    const wrapper = localFunction(ctx, awaited.expression);
+    if (!wrapper || !transparentWrapper(ctx, wrapper)) return;
+    if (!alwaysReturns(callback, (expression) => isIdentity(expression))) return;
+    aliases.push({ alias: node.name.text, start: node.getStart(ctx.source) });
+  });
+  return aliases;
+}
+
 function expectIdentifier(ctx, node) {
   if (!ts.isIdentifier(node) || node.text !== "expect") return false;
   const declaration = declarationOf(ctx, node);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.106",
+  "version": "0.10.108",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"
@@ -35,7 +35,7 @@
     "bun": ">=1.3.0"
   },
   "dependencies": {
-    "@afokapu/atdd-flow": "0.3.50",
+    "@afokapu/atdd-flow": "0.3.82",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "typescript": "6.0.3"