arkgate 2.8.3 → 2.9.0

package/bin/lib/import-resolve.mjs

@@ -0,0 +1,133 @@
+/**
+ * Shared import path → repo-relative + layer resolution for ark-mcp write-gate.
+ * Single primitive so peerIsolation and layer rules share one resolver.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { layerForFile } from '../ark-layer-match.mjs';
+
+/**
+ * Read tsconfig path aliases via the TypeScript config parser (JSONC + extends).
+ * @returns {{ baseUrl: string, aliases: Array<{ from: string, to: string }> }}
+ */
+export function readTsconfigAliases(ts, root) {
+  if (!ts) return { baseUrl: root, aliases: [] };
+  try {
+    const configPath = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json');
+    if (!configPath) return { baseUrl: root, aliases: [] };
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error) return { baseUrl: root, aliases: [] };
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
+    const opts = parsed.options || {};
+    const baseUrl = opts.baseUrl || path.dirname(configPath);
+    const aliases = [];
+    for (const [pattern, targets] of Object.entries(opts.paths || {})) {
+      if (!Array.isArray(targets) || targets.length === 0) continue;
+      // Catch-all `*` → empty prefix would match every specifier; skip it.
+      const from = pattern.replace(/\*$/, '');
+      if (!from) continue;
+      aliases.push({ from, to: String(targets[0]).replace(/\*$/, '') });
+    }
+    aliases.sort((a, b) => b.from.length - a.from.length);
+    return { baseUrl, aliases };
+  } catch {
+    return { baseUrl: root, aliases: [] };
+  }
+}
+
+/**
+ * Resolve an import specifier to a repo-relative path.
+ * Relative + tsconfig-aliased only; bare packages → undefined.
+ */
+export function resolveSpecifierToRel(specifier, fromFilePath, root, tsAliases) {
+  let abs;
+  if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    if (!fromFilePath) return undefined;
+    const fromAbs = path.isAbsolute(fromFilePath)
+      ? fromFilePath
+      : path.resolve(root, fromFilePath);
+    abs = path.resolve(path.dirname(fromAbs), specifier);
+  } else {
+    const alias = tsAliases.aliases.find((a) => specifier.startsWith(a.from));
+    if (!alias) return undefined;
+    abs = path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`);
+  }
+  const rel = path.relative(root, abs).split(path.sep).join('/');
+  return rel.startsWith('..') ? undefined : rel;
+}
+
+function filePathToRel(filePath, root) {
+  if (!filePath || typeof filePath !== 'string') return undefined;
+  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath);
+  const rel = path.relative(root, abs).split(path.sep).join('/');
+  return rel.startsWith('..') ? undefined : rel;
+}
+
+function classifyProbe(root, rel, layers) {
+  let probe = rel;
+  try {
+    if (fs.statSync(path.join(root, rel)).isDirectory()) probe = `${rel}/index.ts`;
+  } catch {
+    /* not on disk */
+  }
+  return (
+    layerForFile(root, probe, layers) || layerForFile(root, `${rel}/index.ts`, layers)
+  );
+}
+
+/**
+ * One resolver for write-gate: specifier or absolute/repo-relative source file →
+ * `{ relPath, layer }`.
+ */
+export function createImportTargetResolver(ts, root, config) {
+  const layers = config?.layers ?? [];
+  if (layers.length === 0) return undefined;
+  const tsAliases = readTsconfigAliases(ts, root);
+
+  return (specifierOrFilePath, fromFilePath) => {
+    if (!specifierOrFilePath || typeof specifierOrFilePath !== 'string') return undefined;
+
+    // Absolute filesystem path (file being written)
+    if (path.isAbsolute(specifierOrFilePath)) {
+      const relPath = filePathToRel(specifierOrFilePath, root);
+      if (!relPath) return undefined;
+      return { relPath, layer: classifyProbe(root, relPath, layers) };
+    }
+
+    // Relative or path-alias import
+    if (
+      specifierOrFilePath.startsWith('./') ||
+      specifierOrFilePath.startsWith('../') ||
+      specifierOrFilePath.startsWith('@')
+    ) {
+      const rel = resolveSpecifierToRel(
+        specifierOrFilePath,
+        fromFilePath,
+        root,
+        tsAliases
+      );
+      if (!rel) return undefined;
+      return { relPath: rel, layer: classifyProbe(root, rel, layers) };
+    }
+
+    // Try as import alias / bare package first
+    const asImport = resolveSpecifierToRel(
+      specifierOrFilePath,
+      fromFilePath,
+      root,
+      tsAliases
+    );
+    if (asImport) {
+      return { relPath: asImport, layer: classifyProbe(root, asImport, layers) };
+    }
+
+    // Repo-relative source file path (not an import specifier)
+    const asFile = filePathToRel(specifierOrFilePath, root);
+    if (asFile) {
+      return { relPath: asFile, layer: classifyProbe(root, asFile, layers) };
+    }
+
+    return undefined;
+  };
+}
+

package/bin/lib/presets.mjs

@@ -19,16 +19,35 @@ export function denyUpward(names) {
   return rules;
 }
 
+/**
+ * peerIsolation matrix: deny only when importer/importee sit under different slices.
+ * Covers same-layer and cross-layer pairs (honest DDD / vertical-slice isolation).
+ */
+export function peerIsolationEdges(layerNames, sliceFolders, message) {
+  const rules = [];
+  for (const from of layerNames) {
+    for (const to of layerNames) {
+      rules.push({
+        from,
+        to,
+        allowed: false,
+        peerIsolation: true,
+        sliceFolders,
+        ...(message ? { message } : {}),
+      });
+    }
+  }
+  return rules;
+}
+
 // Named starter configs. Globs use `**` so they fit both flat (src/domain/**) and
 // modular (src/modules/x/domain/**) layouts. Every layer is optional, so the strict
 // check passes on a greenfield repo and each layer switches on as its dir gains files.
 //
-// Framework internals live under conventional names like `kernel/` and are NOT application
-// architecture — a broad `src/**/domain/**` would otherwise swallow `src/kernel/domain`
-// (DI/runtime wiring) and fire domain-purity rules on it, the false-positive class that
-// motivated `exclude`. Carve those out of every wildcard preset layer by default; a config
-// author who really does keep app code under kernel/ can drop the exclude.
-export const FRAMEWORK_INTERNAL_EXCLUDE = ['**/kernel/**'];
+// Framework internals under `src/kernel/**` are NOT application architecture — a broad
+// `src/**/domain/**` would otherwise swallow `src/kernel/domain`. Do NOT use `**/kernel/**`
+// (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
+export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
 export function presetWithOverlays(baseConfig, root) {
   if (!root) return baseConfig;
   return applyFrameworkLayoutOverlays(baseConfig, root);
@@ -153,20 +172,22 @@ export const ARCHITECTURE_PRESETS = {
   'feature-sliced': (_workspaces, root) => {
     const order = ['App', 'Pages', 'Widgets', 'Features', 'Entities', 'Shared'];
     const purpose = {
-      App: 'App-wide setup, providers, and routing.',
-      Pages: 'Route-level compositions.',
+      App: 'App-wide setup, providers, and routing (FSD app/ + Next app router when co-located under src/app).',
+      Pages: 'Route-level compositions (FSD pages/ and Next pages router).',
       Widgets: 'Self-contained UI blocks composed from features and entities.',
       Features: 'User-facing feature units.',
       Entities: 'Business entities with their UI and logic.',
       Shared: 'Reusable primitives with no business knowledge.',
     };
+    // Canonical FSD under src/<layer>/**; also root <layer>/** for packages that hoist segments.
+    const fsdPatterns = (dir) => [`src/${dir}/**`, `${dir}/**`];
     return presetWithOverlays(
       {
-        include: ['src'],
+        include: ['src', 'app', 'pages'],
         layers: order.map((name) => ({
           name,
           description: purpose[name],
-          patterns: [`src/${name.toLowerCase()}/**`],
+          patterns: fsdPatterns(name.toLowerCase()),
           optional: true,
         })),
         rules: denyUpward(order),
@@ -185,7 +206,8 @@ export const ARCHITECTURE_PRESETS = {
       const resolved = resolveIncludeRoots(root);
       if (resolved.length > 0) include = resolved;
     }
-    if (include.length === 0) include = ['packages', 'apps'];
+    // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
+    if (include.length === 0) include = ['packages', 'apps', 'libs'];
     return presetWithOverlays(
       {
         include,
@@ -377,8 +399,182 @@ export const ARCHITECTURE_PRESETS = {
       },
       root
     ),
+
+  /**
+   * Vertical Slice: feature folders own UI+logic+api; no cross-feature imports
+   * (peerIsolation). Shared primitives and pure lib/infra are the only escape hatches.
+   */
+  'vertical-slice': (_workspaces, root) =>
+    presetWithOverlays(
+      {
+        include: ['src'],
+        layers: [
+          {
+            name: 'Features',
+            description:
+              'Feature / use-case slices (co-located API, UI, hooks, types). No import across sibling slices.',
+            patterns: ['src/features/**', 'src/modules/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'Shared',
+            description: 'Reusable UI primitives, utils, and types with no feature knowledge.',
+            patterns: ['src/shared/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'Lib',
+            description: 'Infrastructure clients (db, HTTP, env) shared across features.',
+            patterns: ['src/lib/**', 'src/infra/**', 'src/infrastructure/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'App',
+            description: 'App shell, routing, providers, composition root.',
+            patterns: ['src/app/**', 'app/**', 'src/pages/**', 'pages/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+        ],
+        rules: [
+          {
+            from: 'Features',
+            to: 'Features',
+            allowed: false,
+            peerIsolation: true,
+            sliceFolders: ['features', 'modules'],
+            message:
+              'Features must not import other feature slices. Extract shared code to Shared/Lib or coordinate via events.',
+          },
+          // Features must not pull in the composition root (re-coupling via App).
+          { from: 'Features', to: 'App', allowed: false },
+          { from: 'Shared', to: 'Features', allowed: false },
+          { from: 'Shared', to: 'App', allowed: false },
+          { from: 'Lib', to: 'Features', allowed: false },
+          { from: 'Lib', to: 'Shared', allowed: false },
+          { from: 'Lib', to: 'App', allowed: false },
+          // App may compose Features + Shared + Lib (no deny).
+          // Features may import Shared + Lib (no deny).
+        ],
+      },
+      root
+    ),
+
+  /**
+   * DDD bounded contexts: per-context domain/application/infra/presentation + shared kernel.
+   * peerIsolation on every pair of context-local layers blocks cross-context imports
+   * (same or cross technical layer). SharedKernel is exempt (not in the peer matrix).
+   * Classic hexagonal denies still block e.g. Domain → Persistence within a context.
+   */
+  'ddd-bounded-contexts': (_workspaces, root) => {
+    const contextLayers = [
+      'DomainModel',
+      'ApplicationOrchestration',
+      'PresentationAdapters',
+      'PersistenceAdapters',
+    ];
+    const sliceFolders = ['contexts', 'bounded-contexts'];
+    return presetWithOverlays(
+      {
+        include: ['src'],
+        layers: [
+          {
+            name: 'DomainModel',
+            description:
+              'Per-context pure domain (entities, VOs, domain events). No I/O, no framework.',
+            patterns: [
+              'src/contexts/**/domain/**',
+              'src/bounded-contexts/**/domain/**',
+              'src/**/domain/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+            optional: true,
+          },
+          {
+            name: 'ApplicationOrchestration',
+            description: 'Per-context use cases / application services.',
+            patterns: [
+              'src/contexts/**/application/**',
+              'src/bounded-contexts/**/application/**',
+              'src/**/application/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PresentationAdapters',
+            description: 'Per-context controllers, HTTP, UI adapters.',
+            patterns: [
+              'src/contexts/**/presentation/**',
+              'src/contexts/**/controllers/**',
+              'src/bounded-contexts/**/presentation/**',
+              'src/**/presentation/**',
+              'src/**/controllers/**',
+              'src/**/http/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PersistenceAdapters',
+            description: 'Per-context infrastructure: repositories, DB, external APIs.',
+            patterns: [
+              'src/contexts/**/infrastructure/**',
+              'src/contexts/**/adapters/**',
+              'src/bounded-contexts/**/infrastructure/**',
+              'src/**/infrastructure/**',
+              'src/**/adapters/**',
+              'src/**/persistence/**',
+              'src/**/repositories/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'SharedKernel',
+            description: 'Truly shared kernel types and primitives across contexts.',
+            patterns: ['src/shared/kernel/**', 'src/shared/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+        ],
+        rules: [
+          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
+          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
+          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
+          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
+          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
+          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          { from: 'SharedKernel', to: 'DomainModel', allowed: false },
+          { from: 'SharedKernel', to: 'ApplicationOrchestration', allowed: false },
+          { from: 'SharedKernel', to: 'PresentationAdapters', allowed: false },
+          { from: 'SharedKernel', to: 'PersistenceAdapters', allowed: false },
+          ...peerIsolationEdges(
+            contextLayers,
+            sliceFolders,
+            'Bounded contexts must not import each other. Use shared kernel or integration events.'
+          ),
+        ],
+      },
+      root
+    );
+  },
 };
 
+// Aliases: Clean / Onion map to the hexagonal factory (same matrix + globs). Avoid dual maintenance.
+ARCHITECTURE_PRESETS['clean-architecture'] = ARCHITECTURE_PRESETS.hexagonal;
+ARCHITECTURE_PRESETS['onion-architecture'] = ARCHITECTURE_PRESETS.hexagonal;
+
+/** Stable public preset keys (CLI help, score fit, docs). Order is display order. */
+export const ARCHITECTURE_PRESET_NAMES = Object.keys(ARCHITECTURE_PRESETS);
+
 // ── Layer suggestion engine ──────────────────────────────────────────────────
 // Everything here is HARVESTED from Ark's own canonical sources — the 11-layer defaults
 // (DEFAULT_LAYER_DIRECTORIES) and the named presets — so a suggestion can never drift from

package/bin/lib/remediation.mjs

@@ -24,6 +24,7 @@ export const MECHANICAL_SAFE_KINDS = [
 export const KNOWN_FIX_CLASSES = [
     'file-move',
     'port-inversion',
+    'cross-slice-boundary',
     'inject-port',
     'registered-intent',
     'add-source-metadata',
@@ -39,6 +40,14 @@ export const KNOWN_FIX_CLASSES = [
 export function classifyRemediation(violation) {
     const ruleId = violation?.ruleId;
     if (ruleId === 'LAYER_IMPORT_VIOLATION') {
+        // Cross-slice peer isolation is always judgment (extract shared / events — not mechanical).
+        if (violation?.peerIsolation) {
+            return {
+                class: 'judgment',
+                confidence: 0.9,
+                rationale: 'peerIsolation blocks cross-slice imports: extract to shared, use events/ports, or redesign ownership — not a mechanical auto-fix.',
+            };
+        }
         // Single invariant: runtime module loads are never mechanical-safe.
         const edgeKind = violation?.edgeKind;
         if (edgeKind === 'require' || edgeKind === 'dynamic-import') {
@@ -131,6 +140,12 @@ export function enrichViolationWithFixClass(violation) {
                         ? '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 if (violation.peerIsolation) {
+                enriched.fixClass = 'cross-slice-boundary';
+                enriched.effort = 'medium';
+                enriched.enthusiastHint =
+                    'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
+            }
             else {
                 enriched.fixClass = 'port-inversion';
                 enriched.effort = 'medium';

package/bin/lib/suggestions.mjs

@@ -3,7 +3,11 @@
  */
 import path from 'node:path';
 import { DEFAULT_LAYER_DIRECTORIES } from '../ark-shared.mjs';
-import { ARCHITECTURE_PRESETS, CANONICAL_LAYER_NAMES } from './presets.mjs';
+import {
+  ARCHITECTURE_PRESETS,
+  ARCHITECTURE_PRESET_NAMES,
+  CANONICAL_LAYER_NAMES,
+} from './presets.mjs';
 
 export function dirSegmentsFromGlob(pattern) {
   return String(pattern)
@@ -31,7 +35,8 @@ export function layerByDir() {
   // (services→Application, components/pages→Presentation, data/infrastructure→Persistence…)
   // map cleanly onto the same taxonomy. feature-sliced uses a different vocabulary
   // (Widgets/Entities/…) that doesn't reduce to the 11, so it's covered by model-fit, not here.
-  for (const preset of ['hexagonal', 'layered', 'monorepo']) {
+  for (const preset of ARCHITECTURE_PRESET_NAMES) {
+    // feature-sliced uses a different vocabulary (App/Pages/…) — still harvest dirs.
     for (const layer of ARCHITECTURE_PRESETS[preset]([]).layers) {
       if (!CANONICAL_LAYER_NAMES.has(layer.name)) continue;
       for (const pattern of layer.patterns ?? []) {
@@ -67,7 +72,7 @@ export function suggestLayerForPath(relDir) {
 // `ark init --preset <name>`. null when nothing lines up.
 export function detectBestFitModel(dirBasenames) {
   const present = new Set(dirBasenames);
-  const scored = ['hexagonal', 'layered', 'feature-sliced', 'monorepo'].map((name) => {
+  const scored = ARCHITECTURE_PRESET_NAMES.map((name) => {
     const segments = new Set();
     for (const layer of ARCHITECTURE_PRESETS[name]([]).layers) {
       for (const pattern of layer.patterns ?? []) {

package/dist/eslint/index.cjs

@@ -156,10 +156,64 @@ function layerForRelativePath(relPath, layers) {
   }
   return bestName;
 }
-function isEdgeDenied(rules2, from, to) {
-  if (from === to) return false;
-  const hit = (rules2 ?? []).find((r) => r.from === from && r.to === to);
-  return hit?.allowed === false;
+function sliceIdForPath(relPath, sliceFolders) {
+  if (!sliceFolders?.length) return void 0;
+  const parts = String(relPath).split(/[/\\]/).filter(Boolean);
+  const folders = new Set(sliceFolders.map((s) => String(s).toLowerCase()));
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (folders.has(parts[i].toLowerCase())) {
+      return `${parts[i]}/${parts[i + 1]}`;
+    }
+  }
+  return void 0;
+}
+function inferSliceFoldersFromPatterns(patterns) {
+  const out = /* @__PURE__ */ new Set();
+  for (const pattern of patterns ?? []) {
+    const glob = normalizeGlobSeparators(String(pattern));
+    const parts = glob.split("/").filter(Boolean);
+    for (let i = 0; i < parts.length; i += 1) {
+      const part = parts[i];
+      if ((part === "**" || part === "*") && i > 0) {
+        const prev = parts[i - 1];
+        if (prev && !prev.includes("*") && !prev.includes("{") && !prev.includes("}")) {
+          out.add(prev);
+        }
+      }
+    }
+  }
+  return [...out];
+}
+function resolveSliceFolders(rule, layerName, layers) {
+  if (Array.isArray(rule.sliceFolders) && rule.sliceFolders.length > 0) {
+    return rule.sliceFolders.filter((s) => typeof s === "string" && s.length > 0);
+  }
+  const layer = (layers ?? []).find((l) => l.name === layerName);
+  return inferSliceFoldersFromPatterns(layer?.patterns);
+}
+function findDeniedEdgeRule(rules2, from, to, options) {
+  for (const rule of rules2 ?? []) {
+    if (rule.from !== from || rule.to !== to) continue;
+    if (rule.allowed !== false) continue;
+    if (rule.peerIsolation) {
+      const fromPath = options?.fromPath;
+      const toPath = options?.toPath;
+      if (!fromPath || !toPath) continue;
+      const folders = resolveSliceFolders(rule, from, options?.layers);
+      if (folders.length === 0) continue;
+      const fromSlice = sliceIdForPath(fromPath, folders);
+      const toSlice = sliceIdForPath(toPath, folders);
+      if (!fromSlice || !toSlice) continue;
+      if (fromSlice !== toSlice) return rule;
+      continue;
+    }
+    if (from === to) continue;
+    return rule;
+  }
+  return void 0;
+}
+function isEdgeDenied(rules2, from, to, options) {
+  return findDeniedEdgeRule(rules2, from, to, options) !== void 0;
 }
 
 // src/eslint/index.ts
@@ -302,7 +356,11 @@ var noDomainInfraImports = {
         if (relTarget.startsWith("..")) return;
         const toLayer = layerForRelativePath(relTarget, config.layers);
         if (!toLayer) return;
-        if (isEdgeDenied(config.rules, fromLayer, toLayer)) {
+        if (isEdgeDenied(config.rules, fromLayer, toLayer, {
+          fromPath: relFile,
+          toPath: relTarget,
+          layers: config.layers
+        })) {
           context.report({
             node,
             messageId: "forbiddenImport",