arkgate 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here.
 
+## 2.2.0 — 2026-07-08
+
+### Added — co-pilot P0 depth (mechanical-safe expansion)
+
+- **Second `mechanical-safe` class:** static value-syntax imports of **pure type-only modules**
+  (only `export type` / `interface` + type-only imports; **no** top-level runtime statements).
+  Flagged `targetTypeOnlyExports` → convert to `import type`. Mixed modules, side-effecting
+  type files, `require()` / dynamic `import()` stay **judgment** (zero false-safe).
+- **Scan cache v3** carries per-file `exportsOnlyTypes` (two-pass scan so targets resolve).
+- **Classifier corpus** extended: type-only + pure-type static import = 2 auto steps; value
+  import, side-effect target, require/dynamic, forbidden global, cycles remain judgment.
+
 ## 2.1.1 — 2026-07-08
 
 ### Documentation

package/bin/ark-check.mjs

@@ -2461,12 +2461,11 @@ function scanCacheKey(root, args) {
       : path.join(root, args.manifest)
     : undefined;
   // Bump this schema tag whenever the cached scan shape changes, so a warm cache from an
-  // older Ark can't feed stale entries to new logic. v2: violation/edge records gained the
-  // `typeOnly` field — a v1 cache would otherwise report every violation as a value edge
-  // after upgrade until files changed. The tag invalidates every existing cache exactly once.
+  // older Ark can't feed stale entries to new logic. v2: typeOnly on edges. v3: per-file
+  // exportsOnlyTypes (target-module type-only export detection for plan classifier).
   return crypto
     .createHash('sha1')
-    .update(`ark-check-cache-v2\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
+    .update(`ark-check-cache-v3\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
     .digest('hex');
 }
 
@@ -2588,6 +2587,58 @@ function isTypeOnlyModuleReference(ts, node) {
   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.
+ */
+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;
+}
+
 function propertyName(ts, node) {
   if (!node) return undefined;
   if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;
@@ -4275,6 +4326,7 @@ function buildRemediationPlan(root, activeViolations, governedPercent = null, to
       ...(v.line ? { line: v.line } : {}),
       ...(v.target ? { target: v.target } : {}),
       ...(v.typeOnly ? { typeOnly: true } : {}),
+      ...(v.targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
     };
   });
   // Order: auto-applicable first (quick, safe wins), then human decisions, then deferred.
@@ -4836,10 +4888,17 @@ async function main() {
       ts.forEachChild(node, visit);
     };
     visit(sourceFile);
-    return { contentViolations: violations, edges };
+    return {
+      contentViolations: violations,
+      edges,
+      exportsOnlyTypes: sourceFileExportsOnlyTypes(ts, sourceFile),
+    };
   }
 
+  // Pass 1: scan every governed file into nextCacheFiles (needs complete map before
+  // targetTypeOnlyExports can be resolved for import edges).
   const importGraph = new Map();
+  const scanned = []; // { file, sourceLayer, relFile, entry }
   for (const file of files) {
     const sourceLayer = layerForFile(root, file, config.layers);
     if (!sourceLayer) continue;
@@ -4853,7 +4912,11 @@ async function main() {
         ? cached
         : { fileKey, ...scanSourceFile(file, sourceLayer) };
     nextCacheFiles[relFile] = entry;
+    scanned.push({ file, sourceLayer, relFile, entry });
+  }
 
+  // Pass 2: content violations + layer edges (with target type-export surface).
+  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);
@@ -4864,14 +4927,24 @@ async function main() {
       }
       const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
       if (rule) {
+        const relTarget = normalize(path.relative(root, target));
+        // After pass 1 every in-scope target is in nextCacheFiles. Missing → not type-only.
+        // targetTypeOnlyExports only for static import/export declarations — never require()
+        // or dynamic import(), which always load the module at runtime (side effects matter).
+        const targetCached = nextCacheFiles[relTarget];
+        const staticEdge = edge.kind === 'import' || edge.kind === 'export';
+        const targetTypeOnlyExports =
+          staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
         violations.push({
           ruleId: 'LAYER_IMPORT_VIOLATION',
           file: relFile,
           line: edge.line,
           fromLayer: sourceLayer,
           toLayer: targetLayer,
-          target: normalize(path.relative(root, target)),
+          target: relTarget,
           ...(edge.typeOnly ? { typeOnly: true } : {}),
+          ...(targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
+          ...(edge.kind ? { edgeKind: edge.kind } : {}),
           message: rule.message ?? `${sourceLayer} must not ${edge.kind} ${targetLayer}.`,
         });
       }

package/bin/ark-shared.mjs

@@ -541,9 +541,11 @@ export function looksLikeIntent(value) {
  *   - 'deferred'        : not enough signal to place it → a human should look first.
  *
  * Deliberately biased toward 'judgment': a false 'mechanical-safe' that auto-lands a bad edit
- * is the failure mode that sinks trust, so only the provably-safe type-only move earns 'auto'.
- * Pure function of one violation object ({ ruleId, typeOnly, ... }) so the CLI, the MCP gate,
- * and (later) the apply-loop all classify identically. Returns { class, confidence, rationale }.
+ * is the failure mode that sinks trust. Only statically-provable type-surface fixes earn 'auto':
+ *   (1) import/export already marked type-only
+ *   (2) value-syntax import of a module that *only* exports types (convert to import type)
+ * Pure function of one violation object so CLI, MCP, and apply-loop classify identically.
+ * Returns { class, confidence, rationale }.
  */
 export const REMEDIATION_CLASSES = ['mechanical-safe', 'judgment', 'deferred'];
 
@@ -558,6 +560,26 @@ export function classifyRemediation(violation) {
           'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
       };
     }
+    // Target module is a pure type-surface file AND the edge is a static import/export
+    // (flag only set on those edges). Value-syntax `import { T }` → convert to import type.
+    // require()/import() never get this flag (runtime load). Mixed modules stay judgment.
+    if (violation.targetTypeOnlyExports) {
+      const kind = violation.edgeKind;
+      if (kind === 'require' || kind === 'dynamic-import') {
+        return {
+          class: 'judgment',
+          confidence: 0.75,
+          rationale:
+            'Runtime module load (require/import()) of a type-only module still executes the target file — not auto-safe; rewrite to a static import type if appropriate.',
+        };
+      }
+      return {
+        class: 'mechanical-safe',
+        confidence: 0.85,
+        rationale:
+          'Static import targets a pure type-only module: convert to `import type` (erased at runtime) and place the type in a shared/owning layer. No runtime coupling; gate verifies.',
+      };
+    }
     return {
       class: 'judgment',
       confidence: 0.7,
@@ -1306,11 +1328,12 @@ export function enrichViolationWithFixClass(violation) {
   const enriched = { ...violation };
   switch (violation.ruleId) {
     case 'LAYER_IMPORT_VIOLATION':
-      if (violation.typeOnly) {
+      if (violation.typeOnly || violation.targetTypeOnlyExports) {
         enriched.fixClass = 'file-move';
         enriched.effort = 'small';
-        enriched.enthusiastHint =
-          'This is a type-only import — move the type to a layer both sides may share, or relocate the file to match its role.';
+        enriched.enthusiastHint = violation.targetTypeOnlyExports
+          ? 'The imported module only exports types — use `import type` and place the type in a layer both sides may share.'
+          : 'This is a type-only import — move the type to a layer both sides may share, or relocate the file to match its role.';
       } else {
         enriched.fixClass = 'port-inversion';
         enriched.effort = 'medium';

package/dist/index.cjs

@@ -80,7 +80,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var version = "2.1.1";
+var version = "2.2.0";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {