arkgate 2.6.1 → 2.7.0

package/bin/lib/config-warnings.mjs

@@ -0,0 +1,228 @@
+/**
+ * Config validation warnings + intent layer helpers for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import path from 'node:path';
+import {
+  DEFAULT_INTENT_PREFIXES,
+  globToRegExp,
+  layerForFile,
+  patternSpecificity,
+  resolveIntentLayer,
+} from '../ark-shared.mjs';
+import { normalize } from './scan-files.mjs';
+
+export function intentLayersFromManifest(manifest) {
+  const layers = manifest?.architecture?.layers;
+  if (!Array.isArray(layers)) return undefined;
+  return layers
+    .filter((layer) => Array.isArray(layer.prefixes) && layer.prefixes.length > 0)
+    .map((layer) => ({ name: layer.name, prefixes: layer.prefixes }));
+}
+
+export function layerForIntent(intent, layers, manifestIntentLayers) {
+  // Use only layers that declare intent prefixes; fall back to the built-in defaults when
+  // none do (mirrors the write-gate). resolveIntentLayer applies the library's exact
+  // longest-prefix + trailing-dot semantics so CI and the MCP gate classify identically.
+  const configured =
+    manifestIntentLayers ??
+    layers
+      .filter((layer) => (layer.intentPrefixes ?? []).length > 0)
+      .map((layer) => ({ name: layer.name, prefixes: layer.intentPrefixes }));
+  const source =
+    configured.length > 0
+      ? configured
+      : DEFAULT_INTENT_PREFIXES.map((entry) => ({ name: entry.layer, prefixes: entry.prefixes }));
+  return resolveIntentLayer(intent, source);
+}
+
+export function isBlocked(rules, from, to) {
+  return rules.find((rule) => !rule.allowed && rule.from === from && rule.to === to);
+}
+
+export function configWarning(ruleId, message, extra = {}) {
+  return { ruleId, message, ...extra };
+}
+
+export function collectConfigWarnings(root, config, files, rules, manifest) {
+  const warnings = [];
+  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 (deer-flow host validation). 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;
+}

package/bin/lib/graph-cycles.mjs

@@ -0,0 +1,56 @@
+/**
+ * Import-graph cycle detection (Tarjan) for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+export function detectCycles(graph) {
+  let index = 0;
+  const indices = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const components = [];
+
+  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
+  const strongconnect = (v) => {
+    indices.set(v, index);
+    low.set(v, index);
+    index += 1;
+    stack.push(v);
+    onStack.add(v);
+    for (const w of [...(graph.get(v) ?? [])].sort()) {
+      if (!graph.has(w)) continue;
+      if (!indices.has(w)) {
+        strongconnect(w);
+        low.set(v, Math.min(low.get(v), low.get(w)));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v), indices.get(w)));
+      }
+    }
+    if (low.get(v) === indices.get(v)) {
+      const comp = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        comp.push(w);
+      } while (w !== v);
+      if (comp.length > 1) components.push(comp.sort());
+    }
+  };
+
+  for (const v of [...graph.keys()].sort()) {
+    if (!indices.has(v)) strongconnect(v);
+  }
+
+  return components
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map((members) => ({
+      ruleId: 'CIRCULAR_DEPENDENCY',
+      file: members[0],
+      line: 1,
+      target: members.join(' → '),
+      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
+      // Graph is value/runtime edges only (type-only imports omitted).
+      cycleKind: 'value',
+    }));
+}

package/bin/lib/remediation.mjs

@@ -0,0 +1,150 @@
+/**
+ * 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',
+];
+/**
+ * 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') {
+        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) {
+            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,
+                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.',
+            };
+        }
+        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) {
+                enriched.fixClass = 'file-move';
+                enriched.effort = 'small';
+                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';
+                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('/');
+}