arkgate 2.6.0 → 2.7.0

package/bin/ark-layer-match.mjs

@@ -1,168 +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;
+/**
+ * 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.
+ */
+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;
+        }
+        out += c;
     }
-    if (c === '{') depth += 1;
-    else if (c === '}') {
-      depth -= 1;
-      if (depth < 0) return false;
+    return out;
+}
+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;
+        }
     }
-  }
-  return depth === 0;
+    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`.
- */
 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;
+    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);
         }
-      } 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);
     }
-  }
-  const re = new RegExp(`^${out}$`);
-  _regexpCache.set(pattern, re);
-  return re;
+    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;
+    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;
 }
-
-/**
- * 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;
-    }
-    for (const pattern of layer.patterns ?? []) {
-      if (globToRegExp(pattern).test(rel)) {
-        const score = patternSpecificity(pattern);
-        if (score > bestScore) {
-          bestScore = score;
-          bestName = layer.name;
+export function layerForRelativePath(relPath, layers) {
+    // 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;
+}
+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;
+}
+/** 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',
+];
+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];
+}
+export function isScanExcludedRelative(relPath, config) {
+    const rel = String(relPath).split(/[/\\]/).join('/');
+    return scanExcludePatterns(config).some((pattern) => globToRegExp(pattern).test(rel));
 }
 
 
-/** 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;
-        }
-      }
-    }
-  }
-  return bestName;
-}
+import path from 'node:path';
 
-/** 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;
+/**
+ * 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-mcp.mjs

@@ -41,6 +41,9 @@ import {
   arkCommand,
   layerForFile,
   shouldShowNewHereNudge,
+  detectWorkspaces,
+  detectTsPackageRoots,
+  resolveIncludeRoots,
 } from './ark-shared.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
@@ -576,9 +579,9 @@ async function main() {
     {
       name: 'ark_place',
       description:
-        'Given a target file path, return which layer it belongs to, which layers it may and ' +
-        'must NOT import, and its forbidden globals — so generated code lands in a governed ' +
-        'location with the right dependencies. Call this BEFORE writing a new file.',
+        'Place a file in the architecture: pass filePath (preferred) and/or description. ' +
+        'Returns layer, mayImport / mustNotImport, forbiddenGlobals. Call BEFORE writing a new file. ' +
+        'If only description is given, returns a conventional path proposal under a governed layer.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -586,8 +589,12 @@ async function main() {
             type: 'string',
             description: 'Path (relative to project root or absolute) of the file to place.',
           },
+          description: {
+            type: 'string',
+            description:
+              'What you are building (e.g. "Remotion caption overlay"). Used when filePath is omitted to propose a path.',
+          },
         },
-        required: ['filePath'],
       },
     },
     {
@@ -599,6 +606,14 @@ async function main() {
         'Call BEFORE generating project structure on greenfield or early-adoption repos.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'ark_suggest_include',
+      description:
+        'Propose ark.config.json include roots from workspaces and nested TypeScript packages ' +
+        '(polyglot-safe). Same idea as ark-check --suggest-include. Use when coverage is empty ' +
+        'or the contract misses package roots.',
+      inputSchema: { type: 'object', properties: {} },
+    },
   ];
 
   const RESOURCES = [
@@ -741,8 +756,52 @@ async function main() {
   // `allowed:false` denies) — which layers it may and must not import.
   function runPlace(params) {
     const filePath = params?.arguments?.filePath;
+    const description = params?.arguments?.description;
+    if ((typeof filePath !== 'string' || !filePath) && typeof description === 'string' && description.trim()) {
+      // Description-only: propose a governed path under PresentationAdapters (UI default).
+      const slug = description
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 48) || 'component';
+      const proposedPath = `src/components/${slug}.tsx`;
+      const layerName = inferLayer(proposedPath, config, args.root) || 'PresentationAdapters';
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                filePath: proposedPath,
+                proposed: true,
+                description: description.trim(),
+                layer: layerName,
+                governed: Boolean(inferLayer(proposedPath, config, args.root)),
+                note:
+                  'filePath was omitted — proposed a conventional path from description. ' +
+                  'Pass filePath explicitly for authoritative placement. Then validate_code the snippet.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: false,
+      };
+    }
     if (typeof filePath !== 'string' || !filePath) {
-      return { content: [{ type: 'text', text: 'Missing required "filePath" argument.' }], isError: true };
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              'ark_place needs filePath and/or description. ' +
+              'Example: { "filePath": "src/components/Foo.tsx" } or { "description": "caption overlay UI component" }.',
+          },
+        ],
+        isError: true,
+      };
     }
     const layerName = inferLayer(filePath, config, args.root);
     if (!layerName) {
@@ -814,12 +873,50 @@ async function main() {
     };
   }
 
+  function runSuggestIncludeTool() {
+    try {
+      const workspaces = detectWorkspaces(args.root);
+      const tsPackages = detectTsPackageRoots(args.root);
+      const suggestedInclude = resolveIncludeRoots(args.root);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                ok: true,
+                workspaces,
+                tsPackages,
+                suggestedInclude:
+                  suggestedInclude.length > 0
+                    ? suggestedInclude
+                    : tsPackages.length > 0
+                      ? tsPackages
+                      : ['src'],
+                next: 'npx ark-check --adopt-contract --write',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   const TOOL_HANDLERS = {
     validate_code: runValidate,
     ark_check: runCheckTool,
     ark_coverage: runCoverageTool,
     ark_place: runPlace,
     ark_recommend: runRecommendTool,
+    ark_suggest_include: runSuggestIncludeTool,
   };
 
   const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);