arkgate 2.5.0 → 2.6.1

package/bin/ark-layer-match.mjs

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ */
+import path from 'node:path';
+
+const _regexpCache = new Map();
+
+function escapeLiteral(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`.
+ */
+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;
+        }
+      } 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;
+}
+
+// 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;
+}
+
+/**
+ * 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;
+        }
+      }
+    }
+  }
+  return bestName;
+}
+
+
+/** 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;
+}
+
+/** 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;
+}
+
+/**
+ * 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`.
+ */
+export const DEFAULT_GENERATED_FILE_GLOBS = [
+  '**/*.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];
+}
+
+/** 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));
+}

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`);