arkgate 2.6.0 → 2.7.0

package/bin/lib/architecture-scan.mjs

@@ -0,0 +1,279 @@
+/**
+ * Architecture check pipeline: content scan → import graph → layer edges → cycles.
+ * Extracted from ark-check entry (R3). Entry remains orchestration + presentation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  collectForbiddenGlobalUses,
+  layerForFile,
+  looksLikeIntent,
+} from '../ark-shared.mjs';
+import {
+  isTypeOnlyModuleReference,
+  isArkPublishCandidate,
+  isPublishCall,
+  lineOf,
+  moduleSpecifierFromCall,
+  objectHasProperty,
+  publishHasSource,
+  publishSourceLiteral,
+  sourceFileExportsOnlyTypes,
+  stringLiteralText,
+  textOfModuleSpecifier,
+} from './ast-scan.mjs';
+import {
+  intentLayersFromManifest,
+  layerForIntent,
+  isBlocked,
+  collectConfigWarnings,
+} from './config-warnings.mjs';
+import { detectCycles } from './graph-cycles.mjs';
+import { normalize } from './scan-files.mjs';
+import {
+  createCompilerOptionsLookup,
+  createModuleResolutionHost,
+  loadScanCache,
+  resolveImport,
+  saveScanCache,
+  scanCacheKey,
+} from './ts-resolve.mjs';
+
+/**
+ * Parse one governed source file into content violations + module edges.
+ */
+export function scanSourceFile(ts, root, config, rules, manifestIntentLayers, file, sourceLayer) {
+  const source = fs.readFileSync(file, 'utf8');
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+  const violations = [];
+  const edges = [];
+
+  const layerConfig = config.layers.find((layer) => layer.name === sourceLayer);
+  const forbiddenGlobals = Array.isArray(layerConfig?.forbiddenGlobals)
+    ? layerConfig.forbiddenGlobals.filter((entry) => typeof entry === 'string')
+    : [];
+  for (const use of collectForbiddenGlobalUses(ts, sourceFile, forbiddenGlobals)) {
+    violations.push({
+      ruleId: 'FORBIDDEN_GLOBAL',
+      file: normalize(path.relative(root, file)),
+      line: lineOf(sourceFile, use.node.getStart(sourceFile)),
+      fromLayer: sourceLayer,
+      target: use.name,
+      message: `${sourceLayer} must not use the ambient global "${use.name}".`,
+    });
+  }
+
+  const checkModuleEdge = (specifier, node, kind, typeOnly = false) => {
+    edges.push({
+      specifier,
+      line: lineOf(sourceFile, node.getStart(sourceFile)),
+      kind,
+      typeOnly,
+    });
+  };
+
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      const specifier = textOfModuleSpecifier(node);
+      if (specifier) {
+        checkModuleEdge(
+          specifier,
+          node,
+          ts.isImportDeclaration(node) ? 'import' : 'export',
+          isTypeOnlyModuleReference(ts, node)
+        );
+      }
+    }
+
+    if (ts.isCallExpression(node)) {
+      const moduleCall = moduleSpecifierFromCall(ts, node);
+      if (moduleCall) {
+        checkModuleEdge(moduleCall.value, node, moduleCall.kind);
+      }
+
+      if (isPublishCall(ts, node)) {
+        const firstArg = node.arguments[0];
+        const rawIntent = stringLiteralText(ts, firstArg);
+        if (
+          (rawIntent && looksLikeIntent(rawIntent)) ||
+          objectHasProperty(ts, firstArg, 'intent')
+        ) {
+          violations.push({
+            ruleId: 'RAW_EVENT_PUBLISH',
+            file: normalize(path.relative(root, file)),
+            line: lineOf(sourceFile, node.getStart(sourceFile)),
+            message:
+              'Publish through a registered intent creator; raw event objects or intent strings bypass Ark contracts and tooling.',
+          });
+        }
+
+        if (isArkPublishCandidate(ts, node) && !publishHasSource(ts, node)) {
+          violations.push({
+            ruleId: 'PUBLISH_MISSING_SOURCE',
+            file: normalize(path.relative(root, file)),
+            line: lineOf(sourceFile, node.getStart(sourceFile)),
+            fromLayer: sourceLayer,
+            message: 'Strict Ark publish calls must include metadata.source.',
+          });
+        }
+
+        const sourceIntent = publishSourceLiteral(ts, node);
+        if (sourceIntent && looksLikeIntent(sourceIntent)) {
+          const sourceIntentLayer = layerForIntent(
+            sourceIntent,
+            config.layers,
+            manifestIntentLayers
+          );
+          if (sourceIntentLayer && sourceIntentLayer !== sourceLayer) {
+            violations.push({
+              ruleId: 'PUBLISH_SOURCE_LAYER_MISMATCH',
+              file: normalize(path.relative(root, file)),
+              line: lineOf(sourceFile, node.getStart(sourceFile)),
+              fromLayer: sourceLayer,
+              toLayer: sourceIntentLayer,
+              target: sourceIntent,
+              message:
+                `Publish source "${sourceIntent}" resolves to ${sourceIntentLayer}, but the publishing file is classified as ${sourceLayer}.`,
+            });
+          }
+        }
+      }
+    }
+
+    if (ts.isStringLiteralLike(node) && looksLikeIntent(node.text)) {
+      const targetLayer = layerForIntent(node.text, config.layers, manifestIntentLayers);
+      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
+      if (rule) {
+        violations.push({
+          ruleId: 'LAYER_INTENT_REFERENCE_VIOLATION',
+          file: normalize(path.relative(root, file)),
+          line: lineOf(sourceFile, node.getStart(sourceFile)),
+          fromLayer: sourceLayer,
+          toLayer: targetLayer,
+          target: node.text,
+          message:
+            rule.message ??
+            `${sourceLayer} must not reference ${targetLayer} intent ${node.text}.`,
+        });
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return {
+    contentViolations: violations,
+    edges,
+    exportsOnlyTypes: sourceFileExportsOnlyTypes(ts, sourceFile),
+  };
+}
+
+/**
+ * Full architecture scan for governed files.
+ * @returns {{ violations: object[], warnings: object[] }}
+ */
+export function runArchitectureScan({ root, config, manifest, rules, files, ts, args }) {
+  const manifestIntentLayers = intentLayersFromManifest(manifest);
+  const compilerOptionsFor = createCompilerOptionsLookup(ts, root, args.tsconfig);
+  const moduleHost = createModuleResolutionHost(ts);
+
+  const violations = [];
+  const warnings = collectConfigWarnings(root, config, files, rules, manifest);
+  const cacheKey = args.noCache ? undefined : scanCacheKey(root, args);
+  const cachedFiles = cacheKey ? loadScanCache(root, cacheKey) : undefined;
+  const nextCacheFiles = {};
+
+  const importGraph = new Map();
+  const scanned = [];
+  for (const file of files) {
+    const sourceLayer = layerForFile(root, file, config.layers);
+    if (!sourceLayer) continue;
+    const relFile = normalize(path.relative(root, file));
+    if (!importGraph.has(relFile)) importGraph.set(relFile, new Set());
+    const stat = fs.statSync(file);
+    const fileKey = `${stat.mtimeMs}:${stat.size}`;
+    const cached = cachedFiles?.[relFile];
+    const entry =
+      cached && cached.fileKey === fileKey
+        ? cached
+        : {
+            fileKey,
+            ...scanSourceFile(
+              ts,
+              root,
+              config,
+              rules,
+              manifestIntentLayers,
+              file,
+              sourceLayer
+            ),
+          };
+    nextCacheFiles[relFile] = entry;
+    scanned.push({ file, sourceLayer, relFile, entry });
+  }
+
+  for (const { file, sourceLayer, relFile, entry } of scanned) {
+    violations.push(...entry.contentViolations);
+    for (const edge of entry.edges) {
+      const target = resolveImport(
+        ts,
+        edge.specifier,
+        file,
+        compilerOptionsFor(file),
+        moduleHost,
+        root
+      );
+      const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;
+      if (target && targetLayer) {
+        const relTarget = normalize(path.relative(root, target));
+        if (relTarget !== relFile && !edge.typeOnly) {
+          importGraph.get(relFile).add(relTarget);
+        }
+      }
+      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
+      if (rule) {
+        const relTarget = normalize(path.relative(root, target));
+        const targetCached = nextCacheFiles[relTarget];
+        const staticEdge = edge.kind === 'import' || edge.kind === 'export';
+        const targetTypeOnlyExports =
+          staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
+        const sourcePureTypeModule = Boolean(entry.exportsOnlyTypes);
+        violations.push({
+          ruleId: 'LAYER_IMPORT_VIOLATION',
+          file: relFile,
+          line: edge.line,
+          fromLayer: sourceLayer,
+          toLayer: targetLayer,
+          target: relTarget,
+          ...(edge.typeOnly ? { typeOnly: true } : {}),
+          ...(targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
+          ...(sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
+          ...(edge.kind ? { edgeKind: edge.kind } : {}),
+          message: rule.message ?? `${sourceLayer} must not ${edge.kind} ${targetLayer}.`,
+        });
+      }
+    }
+  }
+
+  if (cacheKey) saveScanCache(root, cacheKey, nextCacheFiles);
+
+  const cyclePolicy = String(config.cyclePolicy || 'strict').toLowerCase();
+  if (cyclePolicy !== 'off') {
+    const cycles = detectCycles(importGraph);
+    if (cyclePolicy === 'soft' || cyclePolicy === 'framework-soft') {
+      for (const c of cycles) {
+        warnings.push({
+          ruleId: 'CIRCULAR_DEPENDENCY',
+          message: `${c.message} (soft cycle policy — advisory only; set cyclePolicy: "strict" to fail the check)`,
+          file: c.file,
+          target: c.target,
+          failsStrict: false,
+        });
+      }
+    } else {
+      violations.push(...cycles);
+    }
+  }
+
+  return { violations, warnings };
+}

package/bin/lib/ast-scan.mjs

@@ -0,0 +1,199 @@
+/**
+ * AST helpers for publish checks, type-only edges, and module specifiers.
+ * Extracted from ark-check entry (R3).
+ */
+import { looksLikeIntent } from '../ark-shared.mjs';
+
+export function lineOf(sourceFile, pos) {
+  return sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+}
+
+export function textOfModuleSpecifier(node) {
+  return node.moduleSpecifier && typeof node.moduleSpecifier.text === 'string'
+    ? node.moduleSpecifier.text
+    : undefined;
+}
+
+// True when an import/export edge carries ONLY types (`import type …`, or a named import
+// where every binding is `type`-qualified). Type-only edges are erased at compile time —
+// they create no runtime coupling, only a design/type-placement dependency — so callers can
+// rank them below real value imports in a burn-down. A side-effect import (`import "x"`) or
+// any default/namespace/value binding is NOT type-only.
+export function isTypeOnlyModuleReference(ts, node) {
+  if (ts.isImportDeclaration(node)) {
+    const clause = node.importClause;
+    if (!clause) return false; // side-effect import — runtime edge
+    if (clause.isTypeOnly) return true; // `import type …`
+    const named = clause.namedBindings;
+    if (named && ts.isNamedImports(named) && named.elements.length > 0) {
+      return named.elements.every((element) => element.isTypeOnly);
+    }
+    return false; // default or namespace binding of a value
+  }
+  if (ts.isExportDeclaration(node)) {
+    if (node.isTypeOnly) return true;
+    const clause = node.exportClause;
+    if (clause && ts.isNamedExports(clause) && clause.elements.length > 0) {
+      return clause.elements.every((element) => element.isTypeOnly);
+    }
+    return false;
+  }
+  return false;
+}
+
+/**
+ * True when a module is a pure type-surface file: only type/interface exports and
+ * type-only imports. Conservative false (→ judgment) when:
+ * - any top-level runtime statement (value decls, expression stmts, side-effect imports)
+ * - ambiguous `export { X }` without type keyword, export *, default/export=
+ * Used so static value-syntax `import { T }` of a pure-type module can be mechanical-safe
+ * (convert to `import type`). Never trust this for require()/import() edges.
+ */
+export function sourceFileExportsOnlyTypes(ts, sourceFile) {
+  let sawTypeExport = false;
+  const hasExportModifier = (node) =>
+    Array.isArray(node.modifiers) &&
+    node.modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+
+  for (const stmt of sourceFile.statements) {
+    // Type-only imports OK; value or side-effect imports mean runtime load of deps.
+    if (ts.isImportDeclaration(stmt)) {
+      if (!isTypeOnlyModuleReference(ts, stmt)) return false;
+      continue;
+    }
+    if (typeof ts.isImportEqualsDeclaration === 'function' && ts.isImportEqualsDeclaration(stmt)) {
+      return false;
+    }
+    if (ts.isExportDeclaration(stmt)) {
+      if (stmt.isTypeOnly) {
+        sawTypeExport = true;
+        continue;
+      }
+      // export * from '…' can re-export values — not provably type-only.
+      if (!stmt.exportClause) return false;
+      if (ts.isNamespaceExport(stmt.exportClause)) return false;
+      if (ts.isNamedExports(stmt.exportClause)) {
+        if (stmt.exportClause.elements.length === 0) return false;
+        for (const el of stmt.exportClause.elements) {
+          if (!el.isTypeOnly) return false; // bare `export { X }` — ambiguous without checker
+        }
+        sawTypeExport = true;
+        continue;
+      }
+      return false;
+    }
+    if (ts.isExportAssignment(stmt)) return false; // export = / export default expr
+    if (ts.isTypeAliasDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)) {
+      if (hasExportModifier(stmt)) sawTypeExport = true;
+      continue;
+    }
+    // Any other top-level statement (const/fn/class/enum, console.log, if, …) is runtime.
+    return false;
+  }
+  return sawTypeExport;
+}
+
+export function propertyName(ts, node) {
+  if (!node) return undefined;
+  if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;
+  return undefined;
+}
+
+export function objectProperty(ts, node, name) {
+  if (!node || !ts.isObjectLiteralExpression(node)) return undefined;
+  return node.properties.find((property) => {
+    if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
+      return false;
+    }
+    return propertyName(ts, property.name) === name;
+  });
+}
+
+export function objectHasProperty(ts, node, name) {
+  return objectProperty(ts, node, name) !== undefined;
+}
+
+export function objectPropertyValue(ts, node, name) {
+  const property = objectProperty(ts, node, name);
+  return property && ts.isPropertyAssignment(property)
+    ? property.initializer
+    : undefined;
+}
+
+export function objectHasMetadataSource(ts, node) {
+  const metadata = objectPropertyValue(ts, node, 'metadata');
+  return objectHasProperty(ts, metadata, 'source');
+}
+
+export function stringLiteralText(ts, node) {
+  return node && ts.isStringLiteralLike(node) ? node.text : undefined;
+}
+
+export function isPublishCall(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  const expression = node.expression;
+  if (ts.isPropertyAccessExpression(expression)) {
+    return expression.name.text === 'publish';
+  }
+  return ts.isIdentifier(expression) && expression.text === 'publish';
+}
+
+export function looksLikeIntentCreatorExpression(ts, node) {
+  if (!node) return false;
+  if (ts.isIdentifier(node)) {
+    return /^[A-Z]/.test(node.text);
+  }
+  if (ts.isPropertyAccessExpression(node)) {
+    return looksLikeIntentCreatorExpression(ts, node.name);
+  }
+  return false;
+}
+
+export function isArkPublishCandidate(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  const firstArg = node.arguments[0];
+  const rawIntent = stringLiteralText(ts, firstArg);
+  return (
+    (rawIntent !== undefined && looksLikeIntent(rawIntent)) ||
+    objectHasProperty(ts, firstArg, 'intent') ||
+    looksLikeIntentCreatorExpression(ts, firstArg)
+  );
+}
+
+export function publishSourceLiteral(ts, node) {
+  if (!ts.isCallExpression(node)) return undefined;
+  const [firstArg, secondArg, thirdArg] = node.arguments;
+  const rawMetadata = objectPropertyValue(ts, firstArg, 'metadata');
+  return (
+    stringLiteralText(ts, objectPropertyValue(ts, rawMetadata, 'source')) ??
+    stringLiteralText(ts, objectPropertyValue(ts, secondArg, 'source')) ??
+    stringLiteralText(ts, objectPropertyValue(ts, thirdArg, 'source'))
+  );
+}
+
+export function publishHasSource(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  const [firstArg, secondArg, thirdArg] = node.arguments;
+  return (
+    objectHasMetadataSource(ts, firstArg) ||
+    objectHasProperty(ts, secondArg, 'source') ||
+    objectHasProperty(ts, thirdArg, 'source')
+  );
+}
+export function moduleSpecifierFromCall(ts, node) {
+  if (!ts.isCallExpression(node)) return undefined;
+
+  if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+    const first = node.arguments[0];
+    const value = stringLiteralText(ts, first);
+    return value ? { value, kind: 'dynamic-import' } : undefined;
+  }
+
+  if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+    const first = node.arguments[0];
+    const value = stringLiteralText(ts, first);
+    return value ? { value, kind: 'require' } : undefined;
+  }
+
+  return undefined;
+}

package/bin/lib/baseline-key.mjs

@@ -0,0 +1,23 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/baselineKey.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/baseline-key.mjs). Zero Node I/O.
+ */
+
+/**
+ * Stable key used by `--baseline` / `--update-baseline` to match frozen debt.
+ * Field order and empty-string fallbacks are part of the CLI contract.
+ */
+export function baselineKey(violation) {
+    return [
+        violation.ruleId,
+        violation.file,
+        violation.fromLayer ?? '',
+        violation.toLayer ?? '',
+        violation.target ?? '',
+    ].join('|');
+}