arkgate 2.6.1 → 2.8.0

package/bin/lib/remediation.mjs

@@ -0,0 +1,182 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/remediation.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/remediation.mjs). Zero Node I/O.
+ */
+
+export const REMEDIATION_CLASSES = [
+    'mechanical-safe',
+    'judgment',
+    'deferred',
+];
+/** All remediationKinds that may return class: mechanical-safe (ordered for docs/tests). */
+export const MECHANICAL_SAFE_KINDS = [
+    'pure-type-file-relocate',
+    'type-only-import-move',
+    'import-type-from-pure-type-module',
+    'import-type-of-type-exports',
+];
+/** fixClass values from enrichViolationWithFixClass (eval corpus / reports). */
+export const KNOWN_FIX_CLASSES = [
+    'file-move',
+    'port-inversion',
+    'inject-port',
+    'registered-intent',
+    'add-source-metadata',
+    'fix-source-layer',
+    'intent-relocation',
+    'break-cycle',
+    'review-contract',
+];
+/**
+ * Co-pilot work classifier — the TRUST BOUNDARY for auto-apply.
+ * Biased toward 'judgment': false mechanical-safe is worse than an extra human approval.
+ */
+export function classifyRemediation(violation) {
+    const ruleId = violation?.ruleId;
+    if (ruleId === 'LAYER_IMPORT_VIOLATION') {
+        // Single invariant: runtime module loads are never mechanical-safe.
+        const edgeKind = violation?.edgeKind;
+        if (edgeKind === 'require' || edgeKind === 'dynamic-import') {
+            return {
+                class: 'judgment',
+                confidence: 0.75,
+                rationale: 'Runtime module load (require/import()) still executes the target file — not auto-safe; rewrite to a static import type if appropriate.',
+            };
+        }
+        if (violation?.typeOnly && violation?.sourcePureTypeModule) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.88,
+                remediationKind: 'pure-type-file-relocate',
+                rationale: 'Whole source file is type-only surface (no runtime statements) with a type-only cross-layer edge: relocate the file to the owning layer (or extract the type there). Behavior-preserving; gate verifies.',
+            };
+        }
+        if (violation?.typeOnly) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.9,
+                remediationKind: 'type-only-import-move',
+                rationale: '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.',
+            };
+        }
+        if (violation?.targetTypeOnlyExports) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.85,
+                remediationKind: 'import-type-from-pure-type-module',
+                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.',
+            };
+        }
+        // R6: value-syntax named import/export of type-only exports from a mixed module.
+        // Only set when scan proves no dual-space value export and no top-level side effects.
+        if (violation?.namedBindingsTypeOnly) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.86,
+                remediationKind: 'import-type-of-type-exports',
+                rationale: 'Named bindings are type-only exports of the target module (even if the file also exports values): convert to `import type` / `export type` (erased at runtime). Gate verifies.',
+            };
+        }
+        return {
+            class: 'judgment',
+            confidence: 0.7,
+            rationale: 'Value import — real runtime coupling. Relocating it (e.g. a route reaching the DB → a repository) is a refactor whose organization is a human choice.',
+        };
+    }
+    if (ruleId === 'FORBIDDEN_GLOBAL') {
+        return {
+            class: 'judgment',
+            confidence: 0.8,
+            rationale: 'Ambient global in a pure layer: inject the capability through a port (Clock, Config, Http). Introducing the port is a design decision.',
+        };
+    }
+    if (ruleId === 'CIRCULAR_DEPENDENCY') {
+        return {
+            class: 'judgment',
+            confidence: 0.7,
+            rationale: 'Dependency cycle: breaking it means deciding which side owns the shared abstraction.',
+        };
+    }
+    if (typeof ruleId === 'string' && ruleId.length > 0) {
+        return {
+            class: 'judgment',
+            confidence: 0.6,
+            rationale: 'Needs a human decision on how to satisfy the contract without weakening the gate.',
+        };
+    }
+    return {
+        class: 'deferred',
+        confidence: 0.3,
+        rationale: 'Unrecognized violation shape — a human should look before anything is changed.',
+    };
+}
+/**
+ * Deterministic fix-class labels for JSON output (English, shared with skills/reports).
+ */
+export function enrichViolationWithFixClass(violation) {
+    const enriched = { ...violation };
+    switch (violation.ruleId) {
+        case 'LAYER_IMPORT_VIOLATION':
+            if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
+                enriched.fixClass = 'file-move';
+                enriched.effort = 'small';
+                enriched.enthusiastHint = violation.namedBindingsTypeOnly
+                    ? 'Those named imports are type-only exports of the target — use `import type { … }` (or `export type { … }`) so the edge is erased at runtime.'
+                    : 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';
+                enriched.enthusiastHint = `${violation.fromLayer ?? 'This layer'} must not import ${violation.toLayer ?? 'that layer'} directly. Define an interface (port) where you need the capability and inject the implementation from the outer layer.`;
+            }
+            break;
+        case 'FORBIDDEN_GLOBAL':
+            enriched.fixClass = 'inject-port';
+            enriched.effort = 'small';
+            enriched.enthusiastHint = `Do not call "${violation.target ?? 'that global'}" here. Pass the capability in through a small interface (for example a Clock, HttpPort, or Config provider).`;
+            break;
+        case 'RAW_EVENT_PUBLISH':
+            enriched.fixClass = 'registered-intent';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'Register the event intent first, then publish through the creator returned by the registry — not a raw string or object.';
+            break;
+        case 'PUBLISH_MISSING_SOURCE':
+            enriched.fixClass = 'add-source-metadata';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'Add metadata.source to the publish call so Ark knows which layer is publishing the event.';
+            break;
+        case 'PUBLISH_SOURCE_LAYER_MISMATCH':
+            enriched.fixClass = 'fix-source-layer';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'Use a source intent that belongs to the same layer as this file, or move the publish call to the layer that owns the source.';
+            break;
+        case 'LAYER_INTENT_REFERENCE_VIOLATION':
+            enriched.fixClass = 'intent-relocation';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'Reference that intent from a layer allowed to know about it — usually an adapter or application layer, not the domain core.';
+            break;
+        case 'CIRCULAR_DEPENDENCY':
+            enriched.fixClass = 'break-cycle';
+            enriched.effort = 'medium';
+            enriched.enthusiastHint =
+                'Two modules import each other in a loop. Extract shared code, invert one dependency behind a port, or merge them if they are really one unit.';
+            break;
+        default:
+            enriched.fixClass = 'review-contract';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'Read the violation message and the layer rules in ark.config.json, then adjust imports or move code to the correct layer.';
+    }
+    return enriched;
+}

package/bin/lib/scan-files.mjs

@@ -0,0 +1,69 @@
+/**
+ * Governed source file walk / collection for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isScanExcludedRelative } from '../ark-shared.mjs';
+
+export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
+
+/** Unit/e2e test files are not architecture surface — agents and Nest put them next
+ *  to production code (*.spec.ts). Counting them as ungoverned forces false
+ *  CONFIG_UNCLASSIFIED_FILES under --strict-config on every starter. */
+export const TEST_FILE_NAME =
+  /\.(spec|test)\.(tsx?|jsx?|mts|cts)$/i;
+
+export function isGovernableSourceFile(name) {
+  return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
+}
+
+export function isSkippedSourceDir(name) {
+  return (
+    name === 'node_modules' ||
+    name === 'dist' ||
+    name === 'coverage' ||
+    name === '__tests__' ||
+    name === '__mocks__' ||
+    name === 'e2e' ||
+    // Top-level style Nest/Jest folders (not "testing" helpers inside src)
+    name === 'test' ||
+    name === 'tests'
+  );
+}
+
+export function walk(dir, files = []) {
+  const stat = fs.statSync(dir, { throwIfNoEntry: false });
+  if (!stat) return files;
+  // An `include` entry may be a single file (e.g. a root-level "middleware.ts"),
+  // not just a directory — govern it directly instead of trying to scandir it
+  // (which threw ENOTDIR). The extension filter still applies.
+  if (stat.isFile()) {
+    if (isGovernableSourceFile(path.basename(dir))) files.push(dir);
+    return files;
+  }
+  if (!stat.isDirectory()) return files;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkippedSourceDir(entry.name)) continue;
+      walk(full, files);
+    } else if (isGovernableSourceFile(entry.name)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/** Walk include roots then drop codegen / config.exclude (universal scan filter). */
+export function collectGovernedFiles(root, config) {
+  const raw = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+  return raw.filter((abs) => {
+    const rel = normalize(path.relative(root, abs));
+    return !isScanExcludedRelative(rel, config);
+  });
+}
+
+export function normalize(value) {
+  return value.split(path.sep).join('/');
+}

package/bin/lib/ts-resolve.mjs

@@ -0,0 +1,216 @@
+/**
+ * TypeScript module resolution + per-file scan cache for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function createModuleResolutionHost(ts) {
+  const sys = ts?.sys;
+  const fileExists = (f) => {
+    if (sys?.fileExists) return sys.fileExists(f);
+    return fs.existsSync(f);
+  };
+  const readFile = (f) => {
+    if (sys?.readFile) return sys.readFile(f);
+    try {
+      return fs.readFileSync(f, 'utf8');
+    } catch {
+      return undefined;
+    }
+  };
+  const directoryExists = (d) => {
+    if (sys?.directoryExists) return sys.directoryExists(d);
+    try {
+      return fs.statSync(d).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+  return {
+    fileExists,
+    readFile,
+    directoryExists,
+    getCurrentDirectory: () =>
+      sys?.getCurrentDirectory ? sys.getCurrentDirectory() : process.cwd(),
+    getDirectories: (d) => {
+      if (sys?.getDirectories) return sys.getDirectories(d);
+      try {
+        return fs
+          .readdirSync(d, { withFileTypes: true })
+          .filter((e) => e.isDirectory())
+          .map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
+    realpath: sys?.realpath ? (p) => sys.realpath(p) : undefined,
+    useCaseSensitiveFileNames: sys?.useCaseSensitiveFileNames ?? true,
+  };
+}
+
+export function parseTsconfig(ts, configPath) {
+  const host = createModuleResolutionHost(ts);
+  const read = ts.readConfigFile(configPath, host.readFile);
+  if (read.error) return {};
+  // parseJsonConfigFileContent wants a ParseConfigHost-like object; our resolution host
+  // is enough for option extraction.
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    {
+      useCaseSensitiveFileNames: host.useCaseSensitiveFileNames,
+      readDirectory: ts.sys?.readDirectory
+        ? (...args) => ts.sys.readDirectory(...args)
+        : () => [],
+      fileExists: host.fileExists,
+      readFile: host.readFile,
+    },
+    path.dirname(configPath)
+  );
+  return parsed.options;
+}
+
+/**
+ * Compiler options for a given source file. With --tsconfig every file uses that one
+ * config; otherwise each file uses the NEAREST tsconfig.json above it (like tsc does),
+ * so monorepo packages with per-package path aliases resolve correctly under one --root.
+ */
+export function createCompilerOptionsLookup(ts, root, tsconfigArg) {
+  if (tsconfigArg) {
+    const configPath = path.isAbsolute(tsconfigArg) ? tsconfigArg : path.join(root, tsconfigArg);
+    const options = fs.existsSync(configPath) ? parseTsconfig(ts, configPath) : {};
+    return () => options;
+  }
+  const byDir = new Map();
+  const byConfig = new Map();
+  return (file) => {
+    const dir = path.dirname(file);
+    if (byDir.has(dir)) return byDir.get(dir);
+    const configPath = ts.findConfigFile(dir, ts.sys.fileExists, 'tsconfig.json');
+    let options = {};
+    if (configPath) {
+      if (!byConfig.has(configPath)) byConfig.set(configPath, parseTsconfig(ts, configPath));
+      options = byConfig.get(configPath);
+    }
+    byDir.set(dir, options);
+    return options;
+  };
+}
+
+/**
+ * Per-file scan cache. A cache entry stores the parsed file's content-derived results:
+ * content violations (forbidden globals, publish checks, intent references) and the list
+ * of module-edge specifiers. Edges are NEVER cached as violations — they are re-resolved
+ * against the live filesystem every run, because resolution depends on files and tsconfigs
+ * outside the cached file. The whole cache is keyed by the config+manifest contents, so
+ * any rule change invalidates everything.
+ */
+export function scanCachePath(root) {
+  return path.join(root, 'node_modules', '.cache', 'ark-check.json');
+}
+
+export function scanCacheKey(root, args) {
+  const read = (p) => {
+    try {
+      return fs.readFileSync(p, 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  const configPath = path.isAbsolute(args.config) ? args.config : path.join(root, args.config);
+  const manifestPath = args.manifest
+    ? path.isAbsolute(args.manifest)
+      ? args.manifest
+      : path.join(root, args.manifest)
+    : undefined;
+  // Bump this schema tag whenever the cached scan shape or detection semantics change, so a
+  // warm cache from an older Ark can't feed stale entries to new logic. v2: typeOnly on edges.
+  // v3: per-file exportsOnlyTypes. v4: typeOnlyExportNames + namedBindings.
+  // v5: hasTopLevelSideEffects. v6: non-exported impure inits + non-export class statics.
+  return crypto
+    .createHash('sha1')
+    .update(`ark-check-cache-v6\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
+    .digest('hex');
+}
+
+export function loadScanCache(root, key) {
+  try {
+    const data = JSON.parse(fs.readFileSync(scanCachePath(root), 'utf8'));
+    return data.key === key && data.files && typeof data.files === 'object' ? data.files : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveScanCache(root, key, files) {
+  try {
+    const target = scanCachePath(root);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify({ key, files }));
+  } catch {
+    // cache is best-effort: read-only filesystems just re-parse every run
+  }
+}
+
+/**
+ * Fallback resolver for extensionless relative imports whose on-disk target uses an
+ * extension `ts.resolveModuleName` won't resolve without a matching tsconfig
+ * (notably `.mts`/`.cts`). Mirrors the classic candidate list.
+ */
+export function isFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveRelativeFallback(fromFile, specifier) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base, // only used when the specifier already carries an extension (isFile filters dirs)
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.mts`,
+    `${base}.cts`,
+    `${base}.js`,
+    `${base}.jsx`,
+    `${base}.mjs`,
+    `${base}.cjs`,
+    path.join(base, 'index.ts'),
+    path.join(base, 'index.tsx'),
+    path.join(base, 'index.mts'),
+    path.join(base, 'index.cts'),
+  ];
+  // isFile (not existsSync) so a directory named like the specifier never shadows the
+  // real module file — e.g. `./foo` must not resolve to a `foo/` directory before `foo.mts`.
+  return candidates.find(isFile);
+}
+
+/**
+ * Resolve any import specifier (relative, tsconfig path-alias, or package) to a source
+ * file using TypeScript's module resolver, returning the resolved file (or undefined for
+ * unresolved / declaration-only targets).
+ *
+ * ark-check governs one project rooted at --root. A resolved target is skipped when its
+ * path RELATIVE TO ROOT either escapes the root (leading `..`) or contains a `node_modules`
+ * segment. Using the root-relative path (not an absolute substring) means a project that
+ * itself lives under a node_modules segment is still governed, while a broad catch-all
+ * pattern (`**`) can't false-flag vendored deps or files outside the project. Monorepos can
+ * run under a single --root (per-package tsconfigs are honored via the nearest-tsconfig
+ * lookup); edges that resolve outside the root are still skipped.
+ */
+export function resolveImport(ts, specifier, containingFile, options, host, root) {
+  const res = ts.resolveModuleName(specifier, containingFile, options, host);
+  let file = res.resolvedModule?.resolvedFileName;
+  if (!file && specifier.startsWith('.')) {
+    file = resolveRelativeFallback(containingFile, specifier);
+  }
+  if (!file) return undefined;
+  if (file.endsWith('.d.ts')) return undefined;
+  const abs = path.resolve(file);
+  const segments = path.relative(root, abs).split(path.sep);
+  if (segments[0] === '..' || segments.includes('node_modules')) return undefined;
+  return abs;
+}

package/bin/lib/violations.mjs

@@ -10,15 +10,9 @@ const color = {
   bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
 };
 
-export function baselineKey(violation) {
-  return [
-    violation.ruleId,
-    violation.file,
-    violation.fromLayer ?? '',
-    violation.toLayer ?? '',
-    violation.target ?? '',
-  ].join('|');
-}
+/** Canonical: src/domain/baselineKey.ts → bin/lib/baseline-key.mjs (R4). */
+import { baselineKey } from './baseline-key.mjs';
+export { baselineKey };
 
 export function readBaseline(root, baselinePath) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);

package/dist/eslint/index.cjs

@@ -53,6 +53,24 @@ var regexpCache = /* @__PURE__ */ new Map();
 function escapeLiteral(ch) {
   return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
 }
+function normalizeGlobSeparators(pattern) {
+  let out = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === "\\" && i + 1 < pattern.length) {
+      const next = pattern[i + 1];
+      if ("*?{}[],".includes(next) || next === "\\") {
+        out += "\\" + next;
+        i += 1;
+        continue;
+      }
+      out += "/";
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
 function bracesBalanced(glob) {
   let depth = 0;
   for (let i = 0; i < glob.length; i += 1) {
@@ -72,7 +90,7 @@ function bracesBalanced(glob) {
 function globToRegExp(pattern) {
   const cached = regexpCache.get(pattern);
   if (cached) return cached;
-  const glob = pattern.split("\\").join("/");
+  const glob = normalizeGlobSeparators(pattern);
   const useBraces = bracesBalanced(glob);
   let out = "";
   let braceDepth = 0;
@@ -112,14 +130,14 @@ function globToRegExp(pattern) {
   return re;
 }
 function patternSpecificity(pattern) {
-  const glob = String(pattern).split("\\").join("/");
+  const glob = normalizeGlobSeparators(String(pattern));
   const beforeWildcard = glob.split("*")[0];
   const literalSegments = beforeWildcard.split("/").filter(Boolean).length;
   const literalLength = glob.replace(/\*/g, "").length;
   return literalSegments * 1e4 + literalLength;
 }
 function layerForRelativePath(relPath, layers) {
-  const rel = String(relPath).split("\\").join("/");
+  const rel = String(relPath).split(/[/\\]/).join("/");
   let bestName;
   let bestScore = -1;
   for (const layer of layers ?? []) {