arkgate 2.12.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,48 +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)
-        );
-      }
-    }
+  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')
-        ) {
+        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: 'RAW_EVENT_PUBLISH',
+            ruleId: finding.ruleId,
             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.',
+            ...(finding.ruleId === 'PUBLISH_MISSING_SOURCE' ? { fromLayer: sourceLayer } : {}),
+            message: finding.message,
           });
         }
 
@@ -167,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,
@@ -186,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);
@@ -194,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];
@@ -223,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,
@@ -235,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

@@ -12,6 +12,7 @@ import {
   DEFAULT_LAYER_DIRECTORIES,
 } from '../ark-shared.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
+import { renderHostSupportMatrixMarkdown } from './host-support-matrix.mjs';
 import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
 import { readPackageJson } from './gate-files.mjs';
 
@@ -30,7 +31,7 @@ export function checkArgsForRoot(root, { requireGates = false } = {}) {
   const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
     ? ' --baseline .ark-baseline.json'
     : '';
-  const profile = requireGates ? '--strict' : '--strict-config';
+  const profile = requireGates ? '--strict-merge' : '--strict-config';
   return `--root . --config ark.config.json ${profile}${baselineFlag}`;
 }
 
@@ -140,6 +141,10 @@ export function agentInstructions(root) {
 Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
 When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
 
+## Host enforcement support
+
+${renderHostSupportMatrixMarkdown()}
+
 ### Subagent fan-out
 If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
 scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
@@ -177,8 +182,40 @@ an ungoverned location:
 
 ${layerPlacementTable()}
 
-The project is only considered Ark-enforced when the write gate and CI gate pass
-(runtime path only if this project opted into the kernel).
+The project is only considered Ark-enforced when its host-appropriate write path is configured
+and the CI check passes. Only Claude/Grok provide a hard local write boundary; Cursor/Codex use
+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}\`.
 `;
 }
 

package/bin/lib/codex-home.mjs

@@ -22,6 +22,13 @@ export function codexConfigPath() {
   return path.join(base, 'config.toml');
 }
 
+/** True when CODEX_HOME is unset/empty or resolves to the real default ~/.codex. */
+export function usesDefaultCodexHome(env = process.env, homeDir = os.homedir()) {
+  const configured = env?.CODEX_HOME;
+  if (typeof configured !== 'string' || configured.trim() === '') return true;
+  return path.resolve(configured) === path.resolve(homeDir, '.codex');
+}
+
 /** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
 export function isTempOrUpgradeRoot(p) {
   if (!p || typeof p !== 'string') return false;