arkgate 2.10.0 → 2.11.0

package/bin/lib/safety-diagnostics.mjs

@@ -0,0 +1,263 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { globToRegExp } from '../ark-shared.mjs';
+import { lineOf } from './ast-scan.mjs';
+import { normalize } from './scan-files.mjs';
+
+const IN_MEMORY_STORES = new Set([
+  'InMemoryAuditStore',
+  'InMemoryOutboxStore',
+  'InMemoryReadModelStore',
+  'InMemoryWorkflowStore',
+]);
+
+const IN_MEMORY_DEFAULT_FACTORIES = new Map([
+  ['createArkKernel', ['outbox', 'auditTrail', 'projections']],
+  ['createAuditTrail', ['store']],
+  ['createProjectionRegistry', ['store']],
+  ['createWorkflowEngine', ['store']],
+]);
+
+function matchesAny(relFile, patterns) {
+  return patterns.some((pattern) => {
+    try {
+      return globToRegExp(pattern).test(relFile);
+    } catch {
+      return false;
+    }
+  });
+}
+
+function packageName(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
+  } catch {
+    return undefined;
+  }
+}
+
+function propertyName(ts, node) {
+  if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;
+  return undefined;
+}
+
+function objectHasProperty(ts, object, name) {
+  return object.properties.some((property) => {
+    if (ts.isShorthandPropertyAssignment(property)) return property.name.text === name;
+    return property.name ? propertyName(ts, property.name) === name : false;
+  });
+}
+
+function tsSuppressionPositions(sourceFile, source) {
+  const positions = new Set();
+  for (const directive of sourceFile.commentDirectives ?? []) {
+    const start = directive.range?.pos;
+    const end = directive.range?.end;
+    if (Number.isInteger(start) && Number.isInteger(end)) {
+      const text = source.slice(start, end);
+      if (/\@ts-ignore\b/.test(text)) positions.add(start);
+    }
+  }
+
+  const noCheck = sourceFile.pragmas?.get?.('ts-nocheck');
+  const entries = Array.isArray(noCheck) ? noCheck : noCheck ? [noCheck] : [];
+  for (const entry of entries) {
+    const start = entry.range?.pos;
+    if (Number.isInteger(start)) positions.add(start);
+  }
+  return [...positions];
+}
+
+export function collectSafetyDiagnostics(ts, root, config, files) {
+  const safety = config.safety ?? {};
+  const dynamicAllowlist = Array.isArray(config.dynamicImportAllowlist)
+    ? config.dynamicImportAllowlist
+    : [];
+  const maxTsSuppressions = Number.isInteger(safety.maxTsSuppressions)
+    ? safety.maxTsSuppressions
+    : 0;
+  const maxAnyCasts = Number.isInteger(safety.maxAnyCasts) ? safety.maxAnyCasts : 0;
+  const allowInMemory = safety.allowInMemory === true;
+  const isProvider = packageName(root) === 'arkgate';
+  const report = {
+    tsSuppressions: [],
+    anyCasts: [],
+    nonLiteralDynamicImports: [],
+    inMemoryProductionStores: [],
+    disabledPeerIsolationRules: [],
+    thresholds: { maxTsSuppressions, maxAnyCasts },
+  };
+
+  if (safety.allowDisabledPeerIsolation !== true) {
+    report.disabledPeerIsolationRules = (config.rules ?? [])
+      .filter(
+        (rule) =>
+          rule?.peerIsolation === false ||
+          (rule?.allowed === false &&
+            rule?.from &&
+            rule.from === rule.to &&
+            rule.peerIsolation !== true)
+      )
+      .map((rule) => ({ from: rule.from, to: rule.to }));
+  }
+
+  for (const file of files) {
+    const source = fs.readFileSync(file, 'utf8');
+    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const relFile = normalize(path.relative(root, file));
+
+    for (const position of tsSuppressionPositions(sourceFile, source)) {
+      report.tsSuppressions.push({
+        file: relFile,
+        line: lineOf(sourceFile, position),
+      });
+    }
+
+    const importedFactories = new Map();
+    const arkNamespaces = new Set();
+    if (!allowInMemory && !isProvider) {
+      for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)) {
+          continue;
+        }
+        if (!/^arkgate(?:\/runtime)?$/.test(statement.moduleSpecifier.text)) continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings)) arkNamespaces.add(bindings.name.text);
+        if (!bindings || !ts.isNamedImports(bindings)) continue;
+        for (const element of bindings.elements) {
+          const imported = element.propertyName?.text ?? element.name.text;
+          const requirements = IN_MEMORY_DEFAULT_FACTORIES.get(imported);
+          if (requirements) {
+            importedFactories.set(element.name.text, { imported, requirements });
+          }
+        }
+      }
+    }
+
+    const visit = (node) => {
+      if (
+        (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) &&
+        node.type?.kind === ts.SyntaxKind.AnyKeyword
+      ) {
+        report.anyCasts.push({
+          file: relFile,
+          line: lineOf(sourceFile, node.getStart(sourceFile)),
+        });
+      }
+
+      if (ts.isCallExpression(node) && node.expression?.kind === ts.SyntaxKind.ImportKeyword) {
+        const argument = node.arguments[0];
+        if (!argument || !ts.isStringLiteralLike(argument)) {
+          if (!matchesAny(relFile, dynamicAllowlist)) {
+            report.nonLiteralDynamicImports.push({
+              file: relFile,
+              line: lineOf(sourceFile, node.getStart(sourceFile)),
+            });
+          }
+        }
+      }
+
+      if (!allowInMemory && !isProvider && ts.isImportDeclaration(node)) {
+        const specifier = node.moduleSpecifier;
+        const fromArk = ts.isStringLiteralLike(specifier) && /^arkgate(?:\/runtime)?$/.test(specifier.text);
+        if (fromArk) {
+          const elements = node.importClause?.namedBindings &&
+            ts.isNamedImports(node.importClause.namedBindings)
+            ? node.importClause.namedBindings.elements
+            : [];
+          for (const element of elements) {
+            const imported = element.propertyName?.text ?? element.name.text;
+            if (IN_MEMORY_STORES.has(imported)) {
+              report.inMemoryProductionStores.push({
+                file: relFile,
+                line: lineOf(sourceFile, element.getStart(sourceFile)),
+                store: imported,
+              });
+            }
+          }
+        }
+      }
+
+      if (!allowInMemory && !isProvider && ts.isCallExpression(node)) {
+        let factory;
+        if (ts.isIdentifier(node.expression)) {
+          factory = importedFactories.get(node.expression.text);
+        } else if (
+          ts.isPropertyAccessExpression(node.expression) &&
+          ts.isIdentifier(node.expression.expression) &&
+          arkNamespaces.has(node.expression.expression.text)
+        ) {
+          const imported = node.expression.name.text;
+          const requirements = IN_MEMORY_DEFAULT_FACTORIES.get(imported);
+          if (requirements) factory = { imported, requirements };
+        }
+
+        if (factory) {
+          const options = node.arguments[0];
+          const definitelyDefaults =
+            !options ||
+            (ts.isIdentifier(options) && options.text === 'undefined') ||
+            (ts.isObjectLiteralExpression(options) &&
+              factory.requirements.some((name) => !objectHasProperty(ts, options, name)));
+          if (definitelyDefaults) {
+            report.inMemoryProductionStores.push({
+              file: relFile,
+              line: lineOf(sourceFile, node.getStart(sourceFile)),
+              store: `${factory.imported} defaults`,
+            });
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+  }
+
+  const warnings = [];
+  if (report.nonLiteralDynamicImports.length > 0) {
+    const first = report.nonLiteralDynamicImports[0];
+    warnings.push({
+      ruleId: 'DYNAMIC_IMPORT_NOT_ALLOWLISTED',
+      file: first.file,
+      line: first.line,
+      message: `${report.nonLiteralDynamicImports.length} non-literal dynamic import(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
+    });
+  }
+  if (report.tsSuppressions.length > maxTsSuppressions) {
+    const first = report.tsSuppressions[0];
+    warnings.push({
+      ruleId: 'TS_SUPPRESSION_THRESHOLD_EXCEEDED',
+      file: first.file,
+      line: first.line,
+      message: `${report.tsSuppressions.length} @ts-ignore/@ts-nocheck directive(s) exceed safety.maxTsSuppressions (${maxTsSuppressions}).`,
+    });
+  }
+  if (report.anyCasts.length > maxAnyCasts) {
+    const first = report.anyCasts[0];
+    warnings.push({
+      ruleId: 'ANY_CAST_THRESHOLD_EXCEEDED',
+      file: first.file,
+      line: first.line,
+      message: `${report.anyCasts.length} explicit any cast(s) exceed safety.maxAnyCasts (${maxAnyCasts}).`,
+    });
+  }
+  if (report.inMemoryProductionStores.length > 0) {
+    const first = report.inMemoryProductionStores[0];
+    warnings.push({
+      ruleId: 'IN_MEMORY_STORE_IN_PRODUCTION_SOURCE',
+      file: first.file,
+      line: first.line,
+      message: `${report.inMemoryProductionStores.length} ArkGate InMemory store risk(s) appear in governed production source. Provide durable stores or set safety.allowInMemory only for an explicitly ephemeral service.`,
+    });
+  }
+  if (report.disabledPeerIsolationRules.length > 0) {
+    warnings.push({
+      ruleId: 'PEER_ISOLATION_DISABLED',
+      message: `${report.disabledPeerIsolationRules.length} rule(s) disable or omit required peerIsolation. Restore peerIsolation: true or set safety.allowDisabledPeerIsolation only with a documented production exception.`,
+    });
+  }
+
+  return { report, warnings };
+}

package/bin/lib/scan-files.mjs

@@ -32,24 +32,62 @@ export function isSkippedSourceDir(name) {
   );
 }
 
-export function walk(dir, files = []) {
-  const stat = fs.statSync(dir, { throwIfNoEntry: false });
+function isInsideRoot(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+/**
+ * Walk source files while treating symlinks explicitly.
+ *
+ * When `root` is provided, every resolved file/directory must stay inside it.
+ * Internal symlink directories are followed once (TypeScript follows them too),
+ * while escaping links fail closed instead of reading arbitrary filesystem paths.
+ */
+export function walk(dir, files = [], options = {}) {
+  const state = options.state ?? {
+    root: options.root ? fs.realpathSync(options.root) : undefined,
+    visitedDirectories: new Set(),
+    visitedFiles: new Set(),
+  };
+  const lstat = fs.lstatSync(dir, { throwIfNoEntry: false });
+  if (!lstat) return files;
+  const resolved = fs.realpathSync(dir);
+  if (state.root && !isInsideRoot(state.root, resolved)) {
+    throw new Error(
+      `Refusing to scan symlink outside project root: ${dir} -> ${resolved}`
+    );
+  }
+  const stat = lstat.isSymbolicLink()
+    ? fs.statSync(dir, { throwIfNoEntry: false })
+    : lstat;
   if (!stat) return files;
   // An `include` entry may be a single file (e.g. a root-level "middleware.ts"),
   // not just a directory — govern it directly instead of trying to scandir it
   // (which threw ENOTDIR). The extension filter still applies.
   if (stat.isFile()) {
-    if (isGovernableSourceFile(path.basename(dir))) files.push(dir);
+    if (
+      isGovernableSourceFile(path.basename(dir)) &&
+      !state.visitedFiles.has(resolved)
+    ) {
+      state.visitedFiles.add(resolved);
+      files.push(dir);
+    }
     return files;
   }
   if (!stat.isDirectory()) return files;
+  if (state.visitedDirectories.has(resolved)) return files;
+  state.visitedDirectories.add(resolved);
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (isSkippedSourceDir(entry.name)) continue;
-      walk(full, files);
+      walk(full, files, { state });
+    } else if (entry.isSymbolicLink()) {
+      if (isSkippedSourceDir(entry.name)) continue;
+      walk(full, files, { state });
     } else if (isGovernableSourceFile(entry.name)) {
-      files.push(full);
+      walk(full, files, { state });
     }
   }
   return files;
@@ -57,7 +95,14 @@ export function walk(dir, files = []) {
 
 /** Walk include roots then drop codegen / config.exclude (universal scan filter). */
 export function collectGovernedFiles(root, config) {
-  const raw = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+  const state = {
+    root: fs.realpathSync(root),
+    visitedDirectories: new Set(),
+    visitedFiles: new Set(),
+  };
+  const raw = (config.include ?? []).flatMap((entry) =>
+    walk(path.join(root, entry), [], { state })
+  );
   return raw.filter((abs) => {
     const rel = normalize(path.relative(root, abs));
     return !isScanExcludedRelative(rel, config);

package/bin/lib/violations.mjs

@@ -11,8 +11,8 @@ const color = {
 };
 
 /** Canonical: src/domain/baselineKey.ts → bin/lib/baseline-key.mjs (R4). */
-import { baselineKey } from './baseline-key.mjs';
-export { baselineKey };
+import { baselineKey, baselineOccurrenceKeys } from './baseline-key.mjs';
+export { baselineKey, baselineOccurrenceKeys };
 
 export function readBaseline(root, baselinePath) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
@@ -23,7 +23,7 @@ export function readBaseline(root, baselinePath) {
 
 export function writeBaseline(root, baselinePath, violations) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
-  const keys = [...new Set(violations.map(baselineKey))].sort();
+  const keys = baselineOccurrenceKeys(violations).sort();
   fs.writeFileSync(
     fullPath,
     `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`

package/dist/index.cjs

@@ -80,7 +80,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var version = "2.10.0";
+var version = "2.11.0";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {
@@ -2262,6 +2262,75 @@ function extractModuleSpecifiers(source) {
   }
   return matches.sort((a, b) => a.index - b.index);
 }
+function extractModuleSpecifiersAst(ts, source) {
+  const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
+  const matches = [];
+  const push = (node, value, kind, typeOnly = false) => {
+    matches.push({
+      value,
+      index: node.getStart(sourceFile),
+      kind,
+      typeOnly
+    });
+  };
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      const clause = node.importClause;
+      const namedBindings = clause?.namedBindings;
+      const specifiersOnly = clause && !clause.name && namedBindings && ts.isNamedImports(namedBindings) && namedBindings.elements.length > 0 && namedBindings.elements.every((element) => element.isTypeOnly === true);
+      push(
+        node.moduleSpecifier,
+        node.moduleSpecifier.text,
+        "import",
+        Boolean(clause?.isTypeOnly || specifiersOnly)
+      );
+    } else if (ts.isExportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      const clause = node.exportClause;
+      const specifiersOnly = clause && ts.isNamedExports(clause) && clause.elements.length > 0 && clause.elements.every((element) => element.isTypeOnly === true);
+      push(
+        node.moduleSpecifier,
+        node.moduleSpecifier.text,
+        "export",
+        Boolean(node.isTypeOnly || specifiersOnly)
+      );
+    } else if (ts.isCallExpression(node) && node.arguments.length === 1) {
+      const argument = node.arguments[0];
+      const value = tsStringLiteralText(ts, argument);
+      if (value !== void 0 && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+        push(argument, value, "dynamic-import");
+      } else if (value !== void 0 && ts.isIdentifier(node.expression) && node.expression.text === "require") {
+        push(argument, value, "require");
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return matches.sort((a, b) => a.index - b.index);
+}
+function nonLiteralDynamicImportLines(ts, source) {
+  const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
+  const lines = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0]))) {
+      lines.push(sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return lines;
+}
+function extractQuotedStringsAst(ts, source) {
+  const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
+  const matches = [];
+  const visit = (node) => {
+    if (ts.isStringLiteralLike(node)) {
+      matches.push({ value: node.text, index: node.getStart(sourceFile) });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return matches;
+}
 function looksLikeIntentName(s) {
   return /^(Domain|Application|Adapter|Workflow|Job|Presentation|Reporting|Metadata|Security|Audit|Observability|Kernel)\.[A-Za-z0-9_.]+$/.test(s);
 }
@@ -2456,6 +2525,19 @@ function createAICodeGate(options = {}) {
       const gateContext = context;
       const filePath = gateContext?.filePath;
       const contextLayer = gateContext?.layer;
+      const moduleSpecifiers = options.typescript ? extractModuleSpecifiersAst(options.typescript, source) : extractModuleSpecifiers(source);
+      const quotedStrings = options.typescript ? extractQuotedStringsAst(options.typescript, source) : extractQuotedStrings(source);
+      if (options.typescript && !options.allowNonLiteralDynamicImport?.(filePath)) {
+        for (const line of nonLiteralDynamicImportLines(options.typescript, source)) {
+          violations.push(
+            violation(
+              "DYNAMIC_IMPORT_NOT_ALLOWLISTED",
+              "Non-literal dynamic import cannot be resolved statically; add the reviewed file to dynamicImportAllowlist.",
+              { line, filePath }
+            )
+          );
+        }
+      }
       const exemptFromInfraHeuristics = contextLayer !== void 0 && (explicitInfraLayers.has(contextLayer) || layerHasInfrastructureRole(contextLayer));
       const infraLayerEscapeHatch = contextLayer !== void 0 ? ` If "${contextLayer}" is an infrastructure layer, mark it in ark.config.json with "mayImportInfrastructure": true (or name it with an infra token like Adapters/Persistence/Repository).` : "";
       for (const pat of userForbidden) {
@@ -2481,7 +2563,7 @@ function createAICodeGate(options = {}) {
           );
         }
       }
-      for (const specifier of extractModuleSpecifiers(source)) {
+      for (const specifier of moduleSpecifiers) {
         const targetHit = options.resolveImportTarget?.(specifier.value, filePath) ?? (options.resolveImportLayer ? { layer: options.resolveImportLayer(specifier.value, filePath) } : void 0);
         const sourceHit = typeof filePath === "string" ? options.resolveImportTarget?.(filePath) ?? (options.resolveImportLayer ? { layer: contextLayer, relPath: void 0 } : void 0) : void 0;
         const targetLayer = targetHit?.layer;
@@ -2572,7 +2654,7 @@ function createAICodeGate(options = {}) {
         }
       }
       if (enforceAllowlist && intentNames.size > 0) {
-        for (const literal of extractQuotedStrings(source)) {
+        for (const literal of quotedStrings) {
           if (looksLikeIntentName(literal.value) && !intentNames.has(literal.value)) {
             violations.push(
               violation(
@@ -2590,7 +2672,7 @@ function createAICodeGate(options = {}) {
         }
       }
       if (options.architectureProfile && contextLayer) {
-        for (const literal of extractQuotedStrings(source)) {
+        for (const literal of quotedStrings) {
           if (!looksLikeIntentName(literal.value)) continue;
           const targetLayer = options.architectureProfile.resolveLayer(literal.value);
           if (!targetLayer) continue;
@@ -2866,15 +2948,18 @@ function sleep(ms) {
   });
 }
 async function withTimeout(operation, timeoutMs, stepName) {
-  if (timeoutMs === void 0) return operation;
+  const controller = new AbortController();
+  if (timeoutMs === void 0) return operation(controller.signal);
   let timeout;
   const timeoutPromise = new Promise((_, reject) => {
     timeout = setTimeout(() => {
-      reject(new Error(`Workflow step "${stepName}" timed out after ${timeoutMs}ms.`));
+      const error = new Error(`Workflow step "${stepName}" timed out after ${timeoutMs}ms.`);
+      controller.abort(error);
+      reject(error);
     }, timeoutMs);
   });
   try {
-    return await Promise.race([operation, timeoutPromise]);
+    return await Promise.race([operation(controller.signal), timeoutPromise]);
   } finally {
     if (timeout) clearTimeout(timeout);
   }
@@ -2909,6 +2994,15 @@ var WorkflowEngineImpl = class {
     if (this.definitions.has(definition.name)) {
       throw new Error(`Workflow "${definition.name}" is already registered.`);
     }
+    const names = /* @__PURE__ */ new Set();
+    for (const step of definition.steps) {
+      if (names.has(step.name)) {
+        throw new Error(
+          `Workflow "${definition.name}" has duplicate step name "${step.name}".`
+        );
+      }
+      names.add(step.name);
+    }
     this.definitions.set(definition.name, definition);
     if (definition.startOn) {
       const trigger = definition.startOn;
@@ -2949,6 +3043,7 @@ var WorkflowEngineImpl = class {
     } catch (err) {
       await this.compensate(snapshot, definition.steps, err);
       snapshot.status = "failed";
+      snapshot.currentStep = void 0;
       snapshot.error = errorMessage(err);
       snapshot.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       await this.store.save(snapshot);
@@ -2977,7 +3072,7 @@ var WorkflowEngineImpl = class {
       await this.store.save(snapshot);
       try {
         const result = await withTimeout(
-          Promise.resolve(step.execute(snapshot.context, this.bus)),
+          (signal) => Promise.resolve(step.execute(snapshot.context, this.bus, signal)),
           step.timeoutMs,
           step.name
         );