arkgate 2.13.0 → 3.0.0

package/bin/lib/architecture-scan.mjs

@@ -5,16 +5,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  collectForbiddenGlobalUses,
   layerForFile,
   looksLikeIntent,
 } from '../ark-shared.mjs';
 import {
-  isTypeOnlyModuleReference,
   isArkPublishCandidate,
   isPublishCall,
   lineOf,
-  moduleSpecifierFromCall,
   namedModuleBindings,
   objectHasProperty,
   publishHasSource,
@@ -22,7 +19,6 @@ import {
   sourceFileExportsOnlyTypes,
   sourceFileHasTopLevelSideEffects,
   stringLiteralText,
-  textOfModuleSpecifier,
   typeOnlyExportNames,
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
@@ -32,9 +28,14 @@ import {
   isBlocked,
   collectConfigWarnings,
 } from './config-warnings.mjs';
-import { detectCycles } from './graph-cycles.mjs';
+import {
+  collectForbiddenCapabilityUses,
+  evaluateArchitectureGraph,
+  extractSemanticDependencies,
+} from './analysis-engine.mjs';
 import { normalize } from './scan-files.mjs';
 import { collectSafetyDiagnostics } from './safety-diagnostics.mjs';
+import { classifyPublishFacts } from './source-policy.mjs';
 import {
   createCompilerOptionsLookup,
   createModuleResolutionHost,
@@ -57,11 +58,11 @@ export function scanSourceFile(ts, root, config, rules, manifestIntentLayers, fi
   const forbiddenGlobals = Array.isArray(layerConfig?.forbiddenGlobals)
     ? layerConfig.forbiddenGlobals.filter((entry) => typeof entry === 'string')
     : [];
-  for (const use of collectForbiddenGlobalUses(ts, sourceFile, forbiddenGlobals)) {
+  for (const use of collectForbiddenCapabilityUses(ts, sourceFile, forbiddenGlobals)) {
     violations.push({
       ruleId: 'FORBIDDEN_GLOBAL',
       file: normalize(path.relative(root, file)),
-      line: lineOf(sourceFile, use.node.getStart(sourceFile)),
+      line: use.line,
       fromLayer: sourceLayer,
       target: use.name,
       message: `${sourceLayer} must not use the ambient global "${use.name}".`,
@@ -79,56 +80,37 @@ export function scanSourceFile(ts, root, config, rules, manifestIntentLayers, fi
     });
   };
 
-  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.isImportEqualsDeclaration(node) &&
-      ts.isExternalModuleReference(node.moduleReference)
-    ) {
-      const specifier = stringLiteralText(ts, node.moduleReference.expression);
-      if (specifier) checkModuleEdge(specifier, node, 'require');
-    }
+  for (const dependency of extractSemanticDependencies(ts, sourceFile)) {
+    if (!dependency.specifier) continue;
+    checkModuleEdge(
+      dependency.specifier,
+      dependency.node,
+      dependency.kind,
+      dependency.typeOnly
+    );
+  }
 
+  const needsPolicyWalk =
+    /\bpublish\s*\(|\bintent\b/.test(source) ||
+    /['"`]\s*[A-Z][A-Za-z0-9_]*\./.test(source);
+  const visit = (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)) {
+        for (const finding of classifyPublishFacts({
+          publishCall: true,
+          rawIntentName: rawIntent,
+          objectHasIntent: objectHasProperty(ts, firstArg, 'intent'),
+          arkPublishCandidate: isArkPublishCandidate(ts, node),
+          hasSource: publishHasSource(ts, node),
+        })) {
           violations.push({
-            ruleId: 'PUBLISH_MISSING_SOURCE',
+            ruleId: finding.ruleId,
             file: normalize(path.relative(root, file)),
             line: lineOf(sourceFile, node.getStart(sourceFile)),
-            fromLayer: sourceLayer,
-            message: 'Strict Ark publish calls must include metadata.source.',
+            ...(finding.ruleId === 'PUBLISH_MISSING_SOURCE' ? { fromLayer: sourceLayer } : {}),
+            message: finding.message,
           });
         }
 
@@ -175,7 +157,7 @@ export function scanSourceFile(ts, root, config, rules, manifestIntentLayers, fi
 
     ts.forEachChild(node, visit);
   };
-  visit(sourceFile);
+  if (needsPolicyWalk) visit(sourceFile);
   return {
     contentViolations: violations,
     edges,
@@ -194,7 +176,6 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
   const compilerOptionsFor = createCompilerOptionsLookup(ts, root, args.tsconfig);
   const moduleHost = createModuleResolutionHost(ts);
 
-  const violations = [];
   const warnings = collectConfigWarnings(root, config, files, rules, manifest);
   const safety = collectSafetyDiagnostics(ts, root, config, files);
   warnings.push(...safety.warnings);
@@ -202,13 +183,11 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
   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];
@@ -231,8 +210,8 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
     scanned.push({ file, sourceLayer, relFile, entry });
   }
 
+  const engineEdges = [];
   for (const { file, sourceLayer, relFile, entry } of scanned) {
-    violations.push(...entry.contentViolations);
     for (const edge of entry.edges) {
       const target = resolveImport(
         ts,
@@ -243,99 +222,69 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
         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 relTarget = target ? normalize(path.relative(root, target)) : undefined;
-      const rule = targetLayer
+      const targetCached = relTarget ? nextCacheFiles[relTarget] : undefined;
+      const staticEdge = edge.kind === 'import' || edge.kind === 'export';
+      const targetTypeOnlyExports =
+        staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
+      const sourcePureTypeModule = Boolean(entry.exportsOnlyTypes);
+      const targetTypeNames = new Set(targetCached?.typeOnlyExportNames || []);
+      const named = edge.namedBindings;
+      const namedBindingsTypeOnly =
+        staticEdge &&
+        Array.isArray(named) &&
+        named.length > 0 &&
+        targetTypeNames.size > 0 &&
+        !targetCached?.hasTopLevelSideEffects &&
+        named.every((name) => targetTypeNames.has(name));
+      const deniedRule = targetLayer
         ? isBlocked(rules, sourceLayer, targetLayer, {
             fromPath: relFile,
             toPath: relTarget,
             layers: config.layers,
           })
         : undefined;
-      if (rule) {
-        const targetCached = relTarget ? nextCacheFiles[relTarget] : undefined;
-        const staticEdge = edge.kind === 'import' || edge.kind === 'export';
-        const targetTypeOnlyExports =
-          staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
-        const sourcePureTypeModule = Boolean(entry.exportsOnlyTypes);
-        // R6: every named binding is a type-only export of the target (mixed modules OK).
-        // Conservative: no dual-space value names, no top-level side effects on target
-        // (import type would skip evaluation), no default/namespace/side-effect/export*.
-        const targetTypeNames = new Set(targetCached?.typeOnlyExportNames || []);
-        const named = edge.namedBindings;
-        const namedBindingsTypeOnly =
-          staticEdge &&
-          Array.isArray(named) &&
-          named.length > 0 &&
-          targetTypeNames.size > 0 &&
-          !targetCached?.hasTopLevelSideEffects &&
-          named.every((n) => targetTypeNames.has(n));
-        const peerIsolation = Boolean(rule.peerIsolation);
-        // W6: port-proof eligibility (value import only; fail-closed static proof).
-        let portProofEligible = false;
-        if (
-          !edge.typeOnly &&
-          !peerIsolation &&
-          edge.kind === 'import' &&
-          !targetTypeOnlyExports &&
-          !namedBindingsTypeOnly
-        ) {
-          try {
-            const srcText = fs.readFileSync(file, 'utf8');
-            const proof = provePortProofInject(ts, srcText, { filePath: file });
-            portProofEligible = Boolean(proof.eligible);
-          } catch {
-            portProofEligible = false;
-          }
+      let portProofEligible = false;
+      if (
+        deniedRule &&
+        !deniedRule.peerIsolation &&
+        !edge.typeOnly &&
+        edge.kind === 'import' &&
+        !targetTypeOnlyExports &&
+        !namedBindingsTypeOnly
+      ) {
+        try {
+          const source = fs.readFileSync(file, 'utf8');
+          portProofEligible = Boolean(provePortProofInject(ts, source, { filePath: file }).eligible);
+        } catch {
+          portProofEligible = false;
         }
-        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 } : {}),
-          ...(namedBindingsTypeOnly ? { namedBindingsTypeOnly: true } : {}),
-          ...(portProofEligible ? { portProofEligible: true } : {}),
-          ...(edge.kind ? { edgeKind: edge.kind } : {}),
-          ...(peerIsolation ? { peerIsolation: true } : {}),
-          message:
-            rule.message ??
-            (peerIsolation
-              ? `${sourceLayer} must not ${edge.kind} another slice of ${targetLayer} (${relFile} → ${relTarget}). Extract shared code or use events/ports across slices.`
-              : `${sourceLayer} must not ${edge.kind} ${targetLayer}.`),
-        });
       }
+      engineEdges.push({
+        from: relFile,
+        fromLayer: sourceLayer,
+        to: relTarget,
+        toLayer: targetLayer,
+        line: edge.line,
+        kind: edge.kind,
+        typeOnly: edge.typeOnly,
+        targetTypeOnlyExports,
+        sourcePureTypeModule,
+        namedBindingsTypeOnly,
+        portProofEligible,
+      });
     }
   }
 
   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, safety: safety.report };
+  return evaluateArchitectureGraph({
+    config,
+    rules,
+    files: scanned.map(({ relFile }) => relFile),
+    contentViolations: scanned.flatMap(({ entry }) => entry.contentViolations),
+    edges: engineEdges,
+    warnings,
+    safety: safety.report,
+  });
 }

package/bin/lib/ci-and-commands.mjs

@@ -188,6 +188,37 @@ advisory MCP plus CI. The experimental runtime is not required.
 `;
 }
 
+/**
+ * Compact onboarding uses one project router instead of copied slash-command
+ * skills. The package and ark MCP resources remain the canonical capability
+ * source; the marker makes the selected host verifiable by the strict gate.
+ */
+export function compactAgentInstructions(root, host = null) {
+  const selectedHost = host || 'none';
+  const checkCmd = arkCheckCommand(root);
+  const doctorCmd = arkCommand(root, 'ark-check', '--doctor');
+  const installSkills = arkCommand(
+    root,
+    'ark-check',
+    `--install-agent-gates --skills-only --tools ${selectedHost === 'none' ? '<host>' : selectedHost}`
+  );
+  return `# Ark Enforcement
+
+<!-- arkgate:compact-router host=${selectedHost} -->
+## Compact router
+
+This project uses the ArkGate package and its \`ark\` MCP resources as its one
+agent router. Before editing TypeScript or JavaScript, read \`ark://manifest\`
+when available; use \`ark_place\` for new files and \`validate_code\` after edits.
+If MCP is unavailable, inspect \`ark.config.json\` and run \`${checkCmd}\`.
+
+For architecture status, run \`${doctorCmd}\`. The selected host is
+\`${selectedHost}\`; its host registration and CI gate are installed alongside
+this file. Full \`/ark-*\` guided workflows are optional and can be added later
+with \`${installSkills}\`.
+`;
+}
+
 export function mcpJson(root) {
   return `${JSON.stringify({
     mcpServers: {

package/bin/lib/config-warnings.mjs

@@ -5,12 +5,10 @@
 import path from 'node:path';
 import {
   DEFAULT_INTENT_PREFIXES,
-  globToRegExp,
-  layerForFile,
-  patternSpecificity,
   resolveIntentLayer,
 } from '../ark-shared.mjs';
 import { findDeniedEdgeRule } from '../ark-layer-match.mjs';
+import { collectAnalysisConfigWarnings } from './analysis-engine.mjs';
 import { normalize } from './scan-files.mjs';
 
 export function intentLayersFromManifest(manifest) {
@@ -54,206 +52,10 @@ export function configWarning(ruleId, message, extra = {}) {
 }
 
 export function collectConfigWarnings(root, config, files, rules, manifest) {
-  const warnings = [];
-  if (
-    config.dynamicImportAllowlist !== undefined &&
-    (!Array.isArray(config.dynamicImportAllowlist) ||
-      config.dynamicImportAllowlist.some((entry) => typeof entry !== 'string'))
-  ) {
-    warnings.push(
-      configWarning(
-        'CONFIG_INVALID_DYNAMIC_IMPORT_ALLOWLIST',
-        'dynamicImportAllowlist must be an array of file globs.'
-      )
-    );
-  }
-  if (config.safety !== undefined && (config.safety === null || typeof config.safety !== 'object' || Array.isArray(config.safety))) {
-    warnings.push(configWarning('CONFIG_INVALID_SAFETY', 'safety must be an object.'));
-  } else if (config.safety) {
-    for (const key of ['maxTsSuppressions', 'maxAnyCasts']) {
-      const value = config.safety[key];
-      if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
-        warnings.push(configWarning('CONFIG_INVALID_SAFETY_THRESHOLD', `safety.${key} must be a non-negative integer.`));
-      }
-    }
-  }
-  const layers = Array.isArray(config.layers) ? config.layers : [];
-  const manifestLayers = Array.isArray(manifest?.architecture?.layers)
-    ? manifest.architecture.layers
-    : [];
-  const knownLayers = new Set([
-    ...layers.map((layer) => layer.name).filter(Boolean),
-    ...manifestLayers.map((layer) => layer.name).filter(Boolean),
-  ]);
-
-  if (layers.length === 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_NO_LAYERS',
-        'No file layers are configured; ark-check cannot classify files for import-boundary enforcement.'
-      )
-    );
-  }
-
-  const seenLayers = new Set();
-  const duplicateLayers = new Set();
-  for (const layer of layers) {
-    if (!layer.name) {
-      warnings.push(
-        configWarning('CONFIG_LAYER_WITHOUT_NAME', 'A configured layer is missing a name.')
-      );
-      continue;
-    }
-    if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
-    seenLayers.add(layer.name);
-
-    if (
-      layer.forbiddenGlobals !== undefined &&
-      (!Array.isArray(layer.forbiddenGlobals) ||
-        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
-    ) {
-      warnings.push(
-        configWarning(
-          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
-          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
-          { layer: layer.name }
-        )
-      );
-    }
-
-    const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
-    if (patterns.length === 0) {
-      warnings.push(
-        configWarning(
-          'CONFIG_LAYER_WITHOUT_PATTERNS',
-          `Layer "${layer.name}" has no file patterns and will never classify files.`,
-          { layer: layer.name }
-        )
-      );
-      continue;
-    }
-
-    for (const pattern of patterns) {
-      let re;
-      try {
-        re = globToRegExp(pattern);
-      } catch (err) {
-        warnings.push(
-          configWarning(
-            'CONFIG_INVALID_LAYER_PATTERN',
-            `Layer "${layer.name}" has an invalid pattern "${pattern}": ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-            { layer: layer.name, pattern }
-          )
-        );
-        continue;
-      }
-
-      const matched = files.some((file) => {
-        const rel = normalize(path.relative(root, file));
-        return re.test(rel);
-      });
-      if (!matched && !layer.optional) {
-        // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
-        // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
-        // Failing the release gate on dead preset globs caused false CI red while architecture
-        // edges were clean on multi-package hosts. Real safety is import violations +
-        // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
-        warnings.push(
-          configWarning(
-            'CONFIG_LAYER_PATTERN_NO_MATCHES',
-            `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
-            { layer: layer.name, pattern, failsStrict: false }
-          )
-        );
-      }
-    }
-  }
-
-  for (const name of duplicateLayers) {
-    warnings.push(
-      configWarning(
-        'CONFIG_DUPLICATE_LAYER',
-        `Layer "${name}" is configured more than once.`,
-        { layer: name }
-      )
-    );
-  }
-
-  if (knownLayers.size > 0) {
-    for (const rule of rules ?? []) {
-      if (rule.from && !knownLayers.has(rule.from)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_FROM_LAYER',
-            `Rule references unknown source layer "${rule.from}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-      if (rule.to && !knownLayers.has(rule.to)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_TO_LAYER',
-            `Rule references unknown target layer "${rule.to}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-    }
-  }
-
-  // Ambiguous overlap: a file matched by two different layers at the SAME top specificity.
-  // layerForFile breaks the tie by declaration order, but the config is genuinely undecided
-  // (unlike a facade split, where the surface pattern is strictly more specific and wins
-  // cleanly). Surface the layer pairs so the author disambiguates instead of relying on order.
-  const ambiguousPairs = new Set();
-  if (layers.length > 1) {
-    for (const file of files) {
-      const rel = normalize(path.relative(root, file));
-      let topScore = -1;
-      let topLayers = [];
-      for (const layer of layers) {
-        for (const pattern of layer.patterns ?? []) {
-          if (!globToRegExp(pattern).test(rel)) continue;
-          const score = patternSpecificity(pattern);
-          if (score > topScore) {
-            topScore = score;
-            topLayers = [layer.name];
-          } else if (score === topScore && !topLayers.includes(layer.name)) {
-            topLayers.push(layer.name);
-          }
-        }
-      }
-      if (topLayers.length > 1) {
-        ambiguousPairs.add([...topLayers].sort().join(' + '));
-      }
-    }
-  }
-  if (ambiguousPairs.size > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_AMBIGUOUS_LAYERS',
-        `Some files match multiple layers at equal specificity; classification falls back to declaration order. Disambiguate the overlapping patterns: ${[...ambiguousPairs].join(', ')}.`,
-        { pairs: [...ambiguousPairs] }
-      )
-    );
-  }
-
-  const unclassified = files.filter((file) => !layerForFile(root, file, layers));
-  if (unclassified.length > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_UNCLASSIFIED_FILES',
-        `${unclassified.length} included source file(s) are not matched by any configured layer; ark-check will not enforce import rules for those source files.`,
-        {
-          count: unclassified.length,
-          samples: unclassified.slice(0, 5).map((file) => normalize(path.relative(root, file))),
-        }
-      )
-    );
-  }
-
-  return warnings;
+  return collectAnalysisConfigWarnings({
+    config,
+    rules,
+    manifest,
+    files: files.map((file) => normalize(path.relative(root, file))),
+  });
 }