arkgate 2.6.1 → 2.8.0

package/bin/ark-layer-match.mjs

@@ -1,197 +1,174 @@
 /**
- * Pure layer-glob matching for ark.config.json.
- * Single source of truth for CLI (ark-shared / ark-check) and ESLint (bundled via import).
- * No Node I/O beyond path.sep normalization — pure string/path math only.
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/layerMatch.ts
+ * Regenerate: node scripts/generate-layer-match.mjs
+ * Drift check: node scripts/generate-layer-match.mjs --check
+ *
+ * Pure layer-glob matching for ark.config.json (CLI load path).
+ * CLI-only layerForFile (Node path resolution) is appended below the pure core.
  */
-import path from 'node:path';
-
-const _regexpCache = new Map();
 
+const regexpCache = new Map();
 function escapeLiteral(ch) {
-  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
 }
-
-/** True only when every `{` has a matching `}` (ignoring backslash-escaped braces). */
-function bracesBalanced(glob) {
-  let depth = 0;
-  for (let i = 0; i < glob.length; i += 1) {
-    const c = glob[i];
-    if (c === '\\') {
-      i += 1; // skip the escaped character
-      continue;
-    }
-    if (c === '{') depth += 1;
-    else if (c === '}') {
-      depth -= 1;
-      if (depth < 0) return false;
-    }
-  }
-  return depth === 0;
-}
-
 /**
- * Convert an ark.config.json layer glob pattern to an anchored RegExp (compiled once per
- * pattern, then cached).
- *
- * IMPORTANT: the double-star is expanded in a SINGLE pass. A chained two-step replace
- * (double-star to dot-star, then single-star to a no-slash class) corrupts the double-star,
- * because the second step re-matches the star inside the substitution the first step just
- * inserted. That made "src/kernel/**" stop matching nested paths, silently unclassifying
- * every file in a subdirectory. Scanning one character at a time also lets us support
- * brace alternation ("*.{ts,tsx}") and backslash escapes ("\\{" → literal brace).
- *
- * Brace alternation is only enabled when braces are balanced; an unbalanced brace (a config
- * typo) is treated as a literal so the gate never crashes on `new RegExp`.
+ * Normalize path separators to `/` without destroying glob escape sequences.
+ * `src\domain\x` → `src/domain/x` (Windows paths); `src/\{legacy\}/**` keeps `\{` / `\}`.
+ * A plain `pattern.split('\\').join('/')` would eat those escapes.
  */
-export function globToRegExp(pattern) {
-  const cached = _regexpCache.get(pattern);
-  if (cached) return cached;
-
-  const glob = pattern.split(path.sep).join('/');
-  const useBraces = bracesBalanced(glob);
-  let out = '';
-  let braceDepth = 0;
-  for (let i = 0; i < glob.length; i += 1) {
-    const c = glob[i];
-    if (c === '\\' && i + 1 < glob.length) {
-      out += escapeLiteral(glob[i + 1]); // backslash escapes the next char to a literal
-      i += 1;
-    } else if (c === '*') {
-      if (glob[i + 1] === '*') {
-        if (glob[i + 2] === '/') {
-          out += '(?:.*/)?'; // `**/` matches zero or more path segments
-          i += 2;
-        } else {
-          out += '.*'; // `**` matches across `/`
-          i += 1;
+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];
+            // Keep escapes for glob metacharacters (and escaped backslash).
+            if ('*?{}[],'.includes(next) || next === '\\') {
+                out += '\\' + next;
+                i += 1;
+                continue;
+            }
+            // Otherwise treat `\` as a path separator (Windows).
+            out += '/';
+            continue;
         }
-      } else {
-        out += '[^/]*'; // `*` matches within a single segment
-      }
-    } else if (c === '?') {
-      out += '[^/]';
-    } else if (c === '{' && useBraces) {
-      out += '(?:';
-      braceDepth += 1;
-    } else if (c === '}' && useBraces && braceDepth > 0) {
-      out += ')';
-      braceDepth -= 1;
-    } else if (c === ',' && useBraces && braceDepth > 0) {
-      out += '|';
-    } else {
-      out += escapeLiteral(c);
+        out += c;
     }
-  }
-  const re = new RegExp(`^${out}$`);
-  _regexpCache.set(pattern, re);
-  return re;
-}
-
-// Specificity score for a layer glob: more literal path segments before the first wildcard
-// wins, then longer literal text. So `src/kernel/app/**` (3 literal segments) beats
-// `src/kernel/**` (2), and an exact file like `src/kernel/events.ts` beats both. This is what
-// makes a facade split (a KernelApi surface layer overlapping a KernelInternal catch-all)
-// resolve to the surface REGARDLESS of layer declaration order — the intuitive result.
-export function patternSpecificity(pattern) {
-  const glob = String(pattern).split(path.sep).join('/');
-  const beforeWildcard = glob.split('*')[0];
-  const literalSegments = beforeWildcard.split('/').filter(Boolean).length;
-  const literalLength = glob.replace(/\*/g, '').length;
-  return literalSegments * 10000 + literalLength;
+    return out;
 }
-
-/**
- * Resolve a file's architecture layer from ark.config.json layer glob patterns. When more
- * than one layer matches (overlapping globs, e.g. a facade split), the MOST SPECIFIC pattern
- * wins; ties break by declaration order (first wins). Order-independent for non-ambiguous
- * overlaps, so a config author can't silently break a facade by listing the catch-all first.
- *
- * A layer may also declare `exclude` globs. A file matching ANY exclude glob is NOT a
- * candidate for that layer even if a `patterns` glob matches — this lets a broad pattern
- * (e.g. `src/**​/domain/**`) carve out subtrees it should not govern (framework internals
- * like `**​/kernel/**`) without enumerating every include. Excluding a file from its layer
- * also removes it from that layer's rule and `forbiddenGlobals` enforcement, since both key
- * off this classification — which is exactly how a broad domain glob stops mis-flagging
- * `src/kernel/domain` as impure domain code. This is the single file→layer matcher shared by
- * the ark-check CI gate and the ark-mcp write gate, so `exclude` behaves identically in both.
- */
-export function layerForFile(root, file, layers) {
-  const abs = path.isAbsolute(file) ? file : path.resolve(root, file);
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  let bestName;
-  let bestScore = -1;
-  for (const layer of layers ?? []) {
-    if ((layer.exclude ?? []).some((pattern) => globToRegExp(pattern).test(rel))) {
-      continue;
+function bracesBalanced(glob) {
+    let depth = 0;
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === '\\') {
+            i += 1;
+            continue;
+        }
+        if (c === '{')
+            depth += 1;
+        else if (c === '}') {
+            depth -= 1;
+            if (depth < 0)
+                return false;
+        }
     }
-    for (const pattern of layer.patterns ?? []) {
-      if (globToRegExp(pattern).test(rel)) {
-        const score = patternSpecificity(pattern);
-        if (score > bestScore) {
-          bestScore = score;
-          bestName = layer.name;
+    return depth === 0;
+}
+export function globToRegExp(pattern) {
+    const cached = regexpCache.get(pattern);
+    if (cached)
+        return cached;
+    const glob = normalizeGlobSeparators(pattern);
+    const useBraces = bracesBalanced(glob);
+    let out = '';
+    let braceDepth = 0;
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === '\\' && i + 1 < glob.length) {
+            out += escapeLiteral(glob[i + 1]);
+            i += 1;
+        }
+        else if (c === '*') {
+            if (glob[i + 1] === '*') {
+                if (glob[i + 2] === '/') {
+                    out += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    out += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                out += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            out += '[^/]';
+        }
+        else if (c === '{' && useBraces) {
+            out += '(?:';
+            braceDepth += 1;
+        }
+        else if (c === '}' && useBraces && braceDepth > 0) {
+            out += ')';
+            braceDepth -= 1;
+        }
+        else if (c === ',' && useBraces && braceDepth > 0) {
+            out += '|';
+        }
+        else {
+            out += escapeLiteral(c);
         }
-      }
     }
-  }
-  return bestName;
+    const re = new RegExp(`^${out}$`);
+    regexpCache.set(pattern, re);
+    return re;
+}
+export function patternSpecificity(pattern) {
+    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 * 10000 + literalLength;
 }
-
-
-/** Classify a project-relative path (posix) without needing an absolute root. */
 export function layerForRelativePath(relPath, layers) {
-  const rel = String(relPath).split(path.sep).join('/');
-  let bestName;
-  let bestScore = -1;
-  for (const layer of layers ?? []) {
-    if ((layer.exclude ?? []).some((pattern) => globToRegExp(pattern).test(rel))) {
-      continue;
-    }
-    for (const pattern of layer.patterns ?? []) {
-      if (globToRegExp(pattern).test(rel)) {
-        const score = patternSpecificity(pattern);
-        if (score > bestScore) {
-          bestScore = score;
-          bestName = layer.name;
+    // File paths (not globs): any OS separator → posix relative.
+    const rel = String(relPath).split(/[/\\]/).join('/');
+    let bestName;
+    let bestScore = -1;
+    for (const layer of layers ?? []) {
+        if ((layer.exclude ?? []).some((pattern) => globToRegExp(pattern).test(rel))) {
+            continue;
+        }
+        for (const pattern of layer.patterns ?? []) {
+            if (globToRegExp(pattern).test(rel)) {
+                const score = patternSpecificity(pattern);
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestName = layer.name;
+                }
+            }
         }
-      }
     }
-  }
-  return bestName;
+    return bestName;
 }
-
-/** True when rules[] explicitly deny from→to. Missing rule = allowed (implicit). */
 export function isEdgeDenied(rules, from, to) {
-  if (from === to) return false;
-  const hit = (rules ?? []).find((r) => r.from === from && r.to === to);
-  return hit?.allowed === false;
+    if (from === to)
+        return false;
+    const hit = (rules ?? []).find((r) => r.from === from && r.to === to);
+    return hit?.allowed === false;
 }
-
-/**
- * Codegen / generated source globs skipped by the default scan.
- * Universal (TanStack Router routeTree.gen, many `*.generated.ts` tools, etc.).
- * Opt out with `excludeGenerated: false` in ark.config.json; add more via top-level `exclude`.
- */
+/** Codegen globs skipped by default scan (emitted into the CLI derived matcher). */
 export const DEFAULT_GENERATED_FILE_GLOBS = [
-  '**/*.gen.ts',
-  '**/*.gen.tsx',
-  '**/*.generated.ts',
-  '**/*.generated.tsx',
+    '**/*.gen.ts',
+    '**/*.gen.tsx',
+    '**/*.generated.ts',
+    '**/*.generated.tsx',
 ];
-
-/**
- * Globs that remove files from ark-check scan (cycles, layers, coverage).
- * @param {{ exclude?: string[], excludeGenerated?: boolean } | null | undefined} config
- */
 export function scanExcludePatterns(config) {
-  const custom = Array.isArray(config?.exclude) ? config.exclude.filter((p) => typeof p === 'string') : [];
-  const generated =
-    config?.excludeGenerated === false ? [] : DEFAULT_GENERATED_FILE_GLOBS;
-  return [...generated, ...custom];
+    const custom = Array.isArray(config?.exclude)
+        ? config.exclude.filter((p) => typeof p === 'string')
+        : [];
+    const generated = config?.excludeGenerated === false ? [] : DEFAULT_GENERATED_FILE_GLOBS;
+    return [...generated, ...custom];
 }
-
-/** Relative path (posix) matches any scan-exclude glob. */
 export function isScanExcludedRelative(relPath, config) {
-  const rel = String(relPath).split(path.sep).join('/');
-  return scanExcludePatterns(config).some((pattern) => globToRegExp(pattern).test(rel));
+    const rel = String(relPath).split(/[/\\]/).join('/');
+    return scanExcludePatterns(config).some((pattern) => globToRegExp(pattern).test(rel));
+}
+
+
+import path from 'node:path';
+
+/**
+ * Resolve a file's architecture layer from ark.config.json layer glob patterns.
+ * Uses Node path resolution, then the pure layerForRelativePath classifier.
+ */
+export function layerForFile(root, file, layers) {
+  const abs = path.isAbsolute(file) ? file : path.resolve(root, file);
+  const rel = path.relative(root, abs).split(path.sep).join('/');
+  return layerForRelativePath(rel, layers);
 }

package/bin/ark-shared.mjs

@@ -380,7 +380,7 @@ export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
   return uses;
 }
 
-// Layer glob matching — single source of truth in ark-layer-match.mjs (also used by ESLint).
+// Layer glob matching — generated from canonical src/domain/layerMatch.ts (see generate:layer-match).
 export {
   globToRegExp,
   patternSpecificity,
@@ -431,102 +431,15 @@ export function looksLikeIntent(value) {
 }
 
 /**
- * Co-pilot Phase F — the work classifier. Every architecture violation is remediated in one of
- * three ways, and this is the TRUST BOUNDARY that decides what an agent may auto-apply:
- *
- *   - 'mechanical-safe' : behavior-preserving AND gate-verifiable → an agent may auto-apply it.
- *   - 'judgment'        : real coupling or a design choice → Ark PROPOSES it, a human decides.
- *   - '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. Only statically-provable type-surface fixes earn 'auto':
- *   (1) whole source file is pure type-surface + type-only edge → relocate the file
- *   (2) import/export already marked type-only → move/re-export the type
- *   (3) static value-syntax import of a pure type-only *target* module → import type
- * Pure function of one violation object so CLI, MCP, and apply-loop classify identically.
- * Returns { class, confidence, rationale, remediationKind? }.
+ * Co-pilot Phase F — work classifier + fix-class enrich (R4).
+ * Canonical TypeScript: src/domain/remediation.ts
+ * Generated CLI load path: bin/lib/remediation.mjs (`npm run generate:cli-pure`).
  */
-export const REMEDIATION_CLASSES = ['mechanical-safe', 'judgment', 'deferred'];
-
-export function classifyRemediation(violation) {
-  const ruleId = violation?.ruleId;
-  if (ruleId === 'LAYER_IMPORT_VIOLATION') {
-    // Pure type-only *source file* with a type-only edge: relocating the whole file is
-    // behavior-preserving (no runtime body). Distinct from a single import-type move.
-    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.',
-      };
-    }
-    // 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,
-        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.',
-  };
-}
+export {
+  REMEDIATION_CLASSES,
+  classifyRemediation,
+  enrichViolationWithFixClass,
+} from './lib/remediation.mjs';
 
 /**
  * Normalize a required/imported TypeScript module for ark-check's host.
@@ -1547,69 +1460,6 @@ export function shouldShowNewHereNudge(root, configPath, governedPercent, config
   return false;
 }
 
-/**
- * Deterministic fix-class labels for JSON output (English, shared with future skills).
- */
-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;
-}
-
 export function formatArchitectureRecommendationHuman(recommendation) {
   const lines = [];
   lines.push('Ark architecture recommendation (application shape, not vendor stack)');