arkgate 2.6.1 → 2.8.0

package/bin/lib/agent-gates.mjs

@@ -3,7 +3,6 @@
  */
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
-import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -23,6 +22,40 @@ import {
   createElevenLayerConfig,
   applyFrameworkLayoutOverlays
 } from '../ark-shared.mjs';
+import {
+  assessCodexHomeMcp,
+  codexArkBlockHasPreferredBin,
+  codexArkBlockNeedsRewrite,
+  codexConfigPath,
+  codexPrimaryTable,
+  codexProjectSlug,
+  codexPromptsDir,
+  codexScopedTableForRoot,
+  extractCodexArkRootFromToml,
+  extractCodexRootFromBlock,
+  isTempOrUpgradeRoot,
+  listCodexArkServerTables,
+  upsertCodexMcpTable,
+  wireCodexMcp,
+} from './codex-home.mjs';
+
+// Re-export Codex home API for existing consumers (ark-check, tests).
+export {
+  assessCodexHomeMcp,
+  codexArkBlockHasPreferredBin,
+  codexArkBlockNeedsRewrite,
+  codexConfigPath,
+  codexPrimaryTable,
+  codexProjectSlug,
+  codexPromptsDir,
+  codexScopedTableForRoot,
+  extractCodexArkRootFromToml,
+  extractCodexRootFromBlock,
+  isTempOrUpgradeRoot,
+  listCodexArkServerTables,
+  upsertCodexMcpTable,
+  wireCodexMcp,
+};
 
 /** Package root (parent of bin/). All modules live under bin/lib/. */
 const __packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -762,136 +795,6 @@ export function skillTemplateNames() {
 // skills this version ships, surface it here so agents and CI actually notice.
 // Advisory only — never affects the exit code. Copilot has no reliable directory
 // signal, so it is not auto-detected (explicit --tools only), matching resolveTools.
-// Where Codex loads slash-command prompts from. Codex reads $CODEX_HOME/prompts
-// (defaulting to ~/.codex/prompts), NOT the repo — so home copies of the /ark-*
-// skills drift out of date when a repo refresh only touches in-repo tool dirs.
-export function codexPromptsDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'prompts');
-}
-
-// Where Codex reads its MCP server registrations. Unlike Claude (.claude/settings.json)
-// and Cursor (.cursor/mcp.json), Codex loads MCP servers only from $CODEX_HOME/config.toml
-// (~/.codex/config.toml) — never from .mcp.json — so wiring Codex means editing the user's
-// home config, not a repo file.
-export function codexConfigPath() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'config.toml');
-}
-
-// Merge the [mcp_servers.ark] table into Codex's config.toml so `ark://manifest` and the
-// AI write gate are live from the first edit — the piece that was previously only shipped as
-// a copy-me sample in docs/ark-codex-config.toml. Idempotent: an existing ark table is left
-// untouched unless `force` replaces it; other content in the file is preserved. Returns a
-// status for the install summary. The table match runs from the [mcp_servers.ark] header to
-// the line before the next top-level table header (a line starting with `[`) or EOF.
-//
-// Unlike .mcp.json / .cursor/mcp.json (loaded relative to the project), config.toml is a
-// GLOBAL file — Codex launches it without the project as cwd — so `--root .` would resolve
-// against the wrong directory. The paths must be absolute, and TOML string values need the
-// backslashes/quotes escaped (matters on Windows and for repo paths containing quotes).
-export function wireCodexMcp(root, force) {
-  const file = codexConfigPath();
-  const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  const absRoot = path.resolve(root);
-  const absConfig = path.join(absRoot, 'ark.config.json');
-  // Preferred product bin; absolute --root so Codex (cwd ≠ project) resolves correctly.
-  const preferredBin = 'arkgate-mcp';
-  const { command, args } = execCommandParts(root, preferredBin, [
-    '--root',
-    esc(absRoot),
-    '--config',
-    esc(absConfig),
-  ]);
-  const argsToml = args.map((value) => `"${value}"`).join(', ');
-  const makeBlock = (table) =>
-    `[mcp_servers.${table}]
-command = "${command}"
-args = [${argsToml}]`;
-  let existing = '';
-  try {
-    if (fs.existsSync(file)) existing = fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    return { status: 'failed', file, message: error.message };
-  }
-  const tableRe = /(^|\n)\[mcp_servers\.ark\][^\n]*\n(?:(?!\[)[^\n]*\n?)*/;
-  const hasTable = tableRe.test(existing);
-  const existingRoot = hasTable ? extractCodexArkRootFromToml(existing) : null;
-  let differentProject = false;
-  try {
-    differentProject = Boolean(
-      existingRoot && path.resolve(existingRoot) !== absRoot
-    );
-  } catch {
-    differentProject = Boolean(existingRoot);
-  }
-  // Fail-closed: rewrite temp/upgrade roots and dual/wrong bins even without --force.
-  const mustRewrite = hasTable && codexArkBlockNeedsRewrite(existing, absRoot);
-
-  // Multi-project: another project's [mcp_servers.ark] is present. Without --force,
-  // add a project-scoped table so we do not steal the primary binding.
-  if (hasTable && differentProject && !force && !mustRewrite) {
-    const slug =
-      path
-        .basename(absRoot)
-        .replace(/[^a-zA-Z0-9_-]/g, '_')
-        .slice(0, 48) || 'project';
-    const table = `ark_${slug}`;
-    const multiRe = new RegExp(
-      `(^|\\n)\\[mcp_servers\\.${table.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\][^\\n]*\\n(?:(?!\\[)[^\\n]*\\n?)*`
-    );
-    const block = makeBlock(table);
-    let next;
-    if (multiRe.test(existing)) {
-      next = existing.replace(multiRe, (match) => `${match.startsWith('\n') ? '\n' : ''}${block}\n`);
-    } else {
-      const sep =
-        existing.length === 0
-          ? ''
-          : existing.endsWith('\n\n')
-            ? ''
-            : existing.endsWith('\n')
-              ? '\n'
-              : '\n\n';
-      next = `${existing}${sep}${block}\n`;
-    }
-    try {
-      fs.mkdirSync(path.dirname(file), { recursive: true });
-      fs.writeFileSync(file, next);
-    } catch (error) {
-      return { status: 'failed', file, message: error.message };
-    }
-    return { status: 'written-multi', file, table, primaryUnchanged: true };
-  }
-
-  if (hasTable && !force && !mustRewrite) {
-    return { status: 'skipped', file };
-  }
-  const block = makeBlock('ark');
-  let next;
-  if (hasTable) {
-    next = existing.replace(tableRe, (match) => `${match.startsWith('\n') ? '\n' : ''}${block}\n`);
-  } else {
-    const sep = existing.length === 0 ? '' : existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
-    next = `${existing}${sep}${block}\n`;
-  }
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, next);
-  } catch (error) {
-    return { status: 'failed', file, message: error.message };
-  }
-  return {
-    status: hasTable ? 'updated' : 'written',
-    file,
-    ...(mustRewrite && !force ? { reason: 'temp-or-stale-root' } : {}),
-  };
-}
-
-// Detects stale/missing /ark-* skills in the Codex home prompts dir. Only nags
-// when at least one ark-* prompt already lives there (evidence Codex was set up
-// for this user) — never introduces Codex to someone who doesn't use it. Same
-// guards as detectSkillGaps (adopted repo, not the Ark source tree).
 export function detectCodexHomeGap(root) {
   if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
   if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
@@ -1027,73 +930,6 @@ const CORE_LAYER_NAMES = new Set([
   'PersistenceAdapters',
 ]);
 
-/** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
-export function isTempOrUpgradeRoot(p) {
-  if (!p || typeof p !== 'string') return false;
-  const n = p.replace(/\\/g, '/');
-  return (
-    /\/var\/folders\//i.test(n) ||
-    /\/tmp\//i.test(n) ||
-    /\/Temp\//i.test(n) ||
-    /ark-upgrade/i.test(n) ||
-    /\/T\/(?:ark-|grok-)/i.test(n) ||
-    /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
-  );
-}
-
-/** Extract --root value from Codex [mcp_servers.ark] args array text. */
-export function extractCodexArkRootFromToml(tomlText) {
-  if (!tomlText || typeof tomlText !== 'string') return null;
-  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
-  if (start < 0) return null;
-  const rest = tomlText.slice(start);
-  const endMatch = rest.slice(1).search(/\n\[/);
-  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
-  // args = ["arkgate-mcp", "--root", "/abs/path", ...]
-  const rootIdx = block.search(/"--root"\s*,\s*"/);
-  if (rootIdx < 0) {
-    // alternate: --root as adjacent string after any bin
-    const m = block.match(/"--root"\s*,\s*"([^"]+)"/);
-    return m ? m[1] : null;
-  }
-  const m = block.slice(rootIdx).match(/"--root"\s*,\s*"([^"]+)"/);
-  return m ? m[1] : null;
-}
-
-export function codexArkBlockHasPreferredBin(tomlText) {
-  if (!tomlText) return false;
-  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
-  if (start < 0) return false;
-  const rest = tomlText.slice(start);
-  const endMatch = rest.slice(1).search(/\n\[/);
-  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
-  const bins = [...block.matchAll(/"(arkgate-mcp|ark-mcp)"/g)].map((m) => m[1]);
-  if (bins.length > 1) return false;
-  return bins.length === 1 && bins[0] === PREFERRED_MCP_BIN;
-}
-
-/**
- * True when the primary [mcp_servers.ark] block is broken (temp root / dual bin)
- * and should be rewritten fail-closed. Different permanent project roots are NOT
- * "broken" — multi-project wiring uses a secondary table instead.
- */
-export function codexArkBlockNeedsRewrite(tomlText, absRoot) {
-  if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) return true;
-  const rootArg = extractCodexArkRootFromToml(tomlText);
-  if (!rootArg || isTempOrUpgradeRoot(rootArg)) return true;
-  // Permanent different project: multi-project path handles this (do not steal primary).
-  try {
-    if (path.resolve(rootArg) !== path.resolve(absRoot)) {
-      if (!isTempOrUpgradeRoot(rootArg)) return false;
-      return true;
-    }
-  } catch {
-    return true;
-  }
-  if (!codexArkBlockHasPreferredBin(tomlText)) return true;
-  return false;
-}
-
 /**
  * Production deploy path quality (universal — any consumer repo).
  * Detects when the production build host runs ESLint / typecheck as part of
@@ -1383,7 +1219,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     }
   }
 
-  // --- Codex home MCP (temp path / wrong root / dual bin) ---
+  // --- Codex home MCP (temp path / wrong root / multi-project) ---
   let codexHome = null;
   if (adopted && !isProducer) {
     const codexFile = codexConfigPath();
@@ -1394,39 +1230,23 @@ export function collectAdoptionGaps(root, config, coverage) {
       toml = '';
     }
     if (toml.includes('[mcp_servers.ark]')) {
-      const rootArg = extractCodexArkRootFromToml(toml);
-      const absRoot = path.resolve(root);
-      const temp = isTempOrUpgradeRoot(rootArg);
-      let wrongRoot = false;
-      try {
-        wrongRoot = rootArg ? path.resolve(rootArg) !== absRoot : true;
-      } catch {
-        wrongRoot = true;
-      }
-      const preferredBin = codexArkBlockHasPreferredBin(toml);
-      const needsRewrite = codexArkBlockNeedsRewrite(toml, absRoot);
+      const assessed = assessCodexHomeMcp(toml, root);
       codexHome = {
         file: codexFile,
-        root: rootArg,
-        tempPath: temp,
-        wrongRoot,
-        preferredBin,
-        needsRewrite,
+        root: assessed.root,
+        tempPath: assessed.tempPath,
+        wrongRoot: assessed.wrongRoot,
+        preferredBin: assessed.preferredBin,
+        needsRewrite: assessed.needsRewrite,
+        multiProject: assessed.multiProject,
+        scopedTable: assessed.scopedTable,
       };
-      if (needsRewrite) {
+      if (assessed.gap) {
         gaps.push({
-          id: 'codex-home-mcp',
-          severity: temp || wrongRoot ? 'warn' : 'info',
-          message: temp
-            ? `Codex home MCP --root points at a temp/upgrade path (${rootArg})`
-            : wrongRoot
-              ? `Codex home MCP --root is not this project (${rootArg || 'missing'} ≠ ${absRoot})`
-              : `Codex home MCP should use a single ${PREFERRED_MCP_BIN} bin with absolute project paths`,
-          fix: arkCommand(
-            root,
-            'ark-check',
-            '--install-agent-gates --codex-home --force'
-          ),
+          id: assessed.gap.id,
+          severity: assessed.gap.severity,
+          message: assessed.gap.message,
+          fix: arkCommand(root, 'ark-check', assessed.gap.fixArgs),
         });
       }
     }

package/bin/lib/architecture-scan.mjs

@@ -0,0 +1,299 @@
+/**
+ * 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,
+  namedModuleBindings,
+  objectHasProperty,
+  publishHasSource,
+  publishSourceLiteral,
+  sourceFileExportsOnlyTypes,
+  sourceFileHasTopLevelSideEffects,
+  stringLiteralText,
+  textOfModuleSpecifier,
+  typeOnlyExportNames,
+} 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) => {
+    const namedBindings = namedModuleBindings(ts, node);
+    edges.push({
+      specifier,
+      line: lineOf(sourceFile, node.getStart(sourceFile)),
+      kind,
+      typeOnly,
+      ...(namedBindings ? { namedBindings } : {}),
+    });
+  };
+
+  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),
+    typeOnlyExportNames: typeOnlyExportNames(ts, sourceFile),
+    hasTopLevelSideEffects: sourceFileHasTopLevelSideEffects(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);
+        // 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));
+        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 } : {}),
+          ...(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 };
+}