arkgate 2.4.0 → 2.6.0

package/bin/lib/presets.mjs

@@ -0,0 +1,244 @@
+/**
+ * Architecture starter presets for ark-check init/coverage suggestions.
+ */
+import {
+  applyFrameworkLayoutOverlays,
+  createElevenLayerConfig,
+  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+  DEFAULT_INTENT_PREFIXES,
+} from '../ark-shared.mjs';
+
+export function denyUpward(names) {
+  const rules = [];
+  for (let i = 0; i < names.length; i += 1) {
+    for (let j = i + 1; j < names.length; j += 1) {
+      rules.push({ from: names[j], to: names[i], allowed: false });
+    }
+  }
+  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/**'];
+export function presetWithOverlays(baseConfig, root) {
+  if (!root) return baseConfig;
+  return applyFrameworkLayoutOverlays(baseConfig, root);
+}
+
+export const ARCHITECTURE_PRESETS = {
+  // Second arg `root` is optional — when provided (init/start on a real repo), framework
+  // filename conventions (Nest/Next/express) are overlaid so starters get real governed%.
+  hexagonal: (_workspaces, root) =>
+    presetWithOverlays(
+      {
+        include: ['src'],
+        layers: [
+          {
+            name: 'DomainModel',
+            description: 'Pure business rules and entities. No I/O, no framework, no ambient globals.',
+            patterns: ['src/**/domain/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+            optional: true,
+          },
+          {
+            name: 'ApplicationOrchestration',
+            description: 'Use cases that coordinate the domain through ports. No I/O of its own.',
+            patterns: ['src/**/application/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PresentationAdapters',
+            description: 'Entrypoints — HTTP routes, controllers, UI. Drives use cases.',
+            patterns: [
+              'src/**/presentation/**',
+              'src/**/controllers/**',
+              'src/**/interface-adapters/**',
+              'src/**/http/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PersistenceAdapters',
+            description: 'Implements ports with real infrastructure: DB, external APIs, filesystem.',
+            patterns: [
+              'src/**/infrastructure/**',
+              'src/**/adapters/**',
+              'src/**/persistence/**',
+              'src/**/repositories/**',
+            ],
+            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 },
+        ],
+      },
+      root
+    ),
+  layered: (_workspaces, root) =>
+    presetWithOverlays(
+      {
+        include: ['src'],
+        layers: [
+          {
+            name: 'PresentationAdapters',
+            description: 'UI and API entrypoints.',
+            patterns: [
+              'src/**/presentation/**',
+              'src/**/controllers/**',
+              'src/**/ui/**',
+              'src/**/http/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'ApplicationOrchestration',
+            description: 'Business services and use-case coordination.',
+            patterns: ['src/**/application/**', 'src/**/services/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'DomainModel',
+            description: 'Pure business rules and entities. No I/O, no framework, no ambient globals.',
+            patterns: ['src/**/domain/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+            optional: true,
+          },
+          {
+            name: 'PersistenceAdapters',
+            description: 'Data access and infrastructure.',
+            patterns: [
+              'src/**/persistence/**',
+              'src/**/data/**',
+              'src/**/repositories/**',
+              'src/**/infrastructure/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+        ],
+        rules: denyUpward([
+          'PresentationAdapters',
+          'ApplicationOrchestration',
+          'DomainModel',
+          'PersistenceAdapters',
+        ]),
+      },
+      root
+    ),
+  '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.',
+      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.',
+    };
+    return presetWithOverlays(
+      {
+        include: ['src'],
+        layers: order.map((name) => ({
+          name,
+          description: purpose[name],
+          patterns: [`src/${name.toLowerCase()}/**`],
+          optional: true,
+        })),
+        rules: denyUpward(order),
+      },
+      root
+    );
+  },
+  // Cross-package profile for workspace monorepos. Patterns match by directory NAME
+  // anywhere in the tree (`**/domain/**` hits packages/x/domain AND apps/y/src/domain),
+  // so one profile governs every package. include defaults to the detected workspace
+  // roots (falls back to packages+apps). Naming varies by repo — adjust and re-check.
+  monorepo: (includeDirs, root) =>
+    presetWithOverlays(
+      {
+        include: includeDirs && includeDirs.length > 0 ? includeDirs : ['packages', 'apps'],
+        layers: [
+          {
+            name: 'DomainModel',
+            description:
+              'Pure business rules and entities, in any package. No I/O, no framework, no ambient globals.',
+            patterns: ['**/domain/**', '**/entities/**'],
+            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+            optional: true,
+          },
+          {
+            name: 'ApplicationOrchestration',
+            description: 'Use cases and services that coordinate the domain through ports.',
+            patterns: ['**/application/**', '**/use-cases/**', '**/services/**'],
+            optional: true,
+          },
+          {
+            name: 'PresentationAdapters',
+            description: 'Entrypoints — HTTP routes, controllers, UI, framework app/pages dirs.',
+            patterns: [
+              '**/app/**',
+              '**/pages/**',
+              '**/components/**',
+              '**/controllers/**',
+              '**/http/**',
+              '**/routes/**',
+            ],
+            optional: true,
+          },
+          {
+            name: 'PersistenceAdapters',
+            description: 'Implements ports with real infrastructure: DB, external APIs, filesystem.',
+            patterns: [
+              '**/infrastructure/**',
+              '**/adapters/**',
+              '**/persistence/**',
+              '**/repositories/**',
+            ],
+            optional: true,
+          },
+        ],
+        rules: [
+          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
+          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
+          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
+          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+        ],
+      },
+      root
+    ),
+};
+
+// ── 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
+// what the gate actually enforces. No ad-hoc directory heuristics: a directory Ark doesn't
+// already know about is reported as "unrecognized — you classify", never guessed. This is
+// what lets `init`/`--coverage` PROPOSE where ungoverned code belongs instead of silently
+// leaving the majority of a repo ungoverned behind a false-green check.
+export const CANONICAL_LAYER_NAMES = new Set(DEFAULT_INTENT_PREFIXES.map((entry) => entry.layer));

package/bin/lib/suggestions.mjs

@@ -0,0 +1,109 @@
+/**
+ * Unclassified-path layer suggestions for coverage/doctor.
+ */
+import path from 'node:path';
+import { DEFAULT_LAYER_DIRECTORIES } from '../ark-shared.mjs';
+import { ARCHITECTURE_PRESETS, CANONICAL_LAYER_NAMES } from './presets.mjs';
+
+export function dirSegmentsFromGlob(pattern) {
+  return String(pattern)
+    .split('/')
+    .filter((segment) => segment && !segment.includes('*'));
+}
+
+let _layerByDir;
+// Map<dirBasename, string[] layers>. A basename mapping to >1 layer (e.g. `app` — Application
+// orchestration in the 11-layer defaults, but Presentation in the monorepo/Next preset) is
+// genuinely ambiguous; every candidate is surfaced rather than silently picked.
+export function layerByDir() {
+  if (_layerByDir) return _layerByDir;
+  const map = new Map();
+  const add = (segment, layer) => {
+    if (!segment) return;
+    const existing = map.get(segment) ?? [];
+    if (!existing.includes(layer)) existing.push(layer);
+    map.set(segment, existing);
+  };
+  for (const [layer, dirs] of Object.entries(DEFAULT_LAYER_DIRECTORIES)) {
+    for (const dir of dirs) add(dirSegmentsFromGlob(dir).pop(), layer);
+  }
+  // The canonical-named presets reuse the 11 layer names, so their directory synonyms
+  // (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 layer of ARCHITECTURE_PRESETS[preset]([]).layers) {
+      if (!CANONICAL_LAYER_NAMES.has(layer.name)) continue;
+      for (const pattern of layer.patterns ?? []) {
+        add(dirSegmentsFromGlob(pattern).pop(), layer.name);
+      }
+    }
+  }
+  _layerByDir = map;
+  return map;
+}
+
+// Suggest a canonical layer for a directory by its basename. null when Ark doesn't recognize
+// it (the honest "you classify this" case), else { layer, alternatives }.
+export function suggestLayerForDir(name) {
+  const layers = layerByDir().get(name);
+  if (!layers || layers.length === 0) return null;
+  return { layer: layers[0], alternatives: layers.slice(1) };
+}
+
+// Suggest a layer for a directory PATH by finding the deepest segment Ark recognizes, so
+// `src/lib/repositories` proposes PersistenceAdapters even though `lib` itself is unknown.
+export function suggestLayerForPath(relDir) {
+  const segments = relDir.split('/').filter(Boolean);
+  for (let i = segments.length - 1; i >= 0; i -= 1) {
+    const hit = suggestLayerForDir(segments[i]);
+    if (hit) return { ...hit, matchedDir: segments[i] };
+  }
+  return null;
+}
+
+// Which starter model does this set of directory basenames most resemble? Scored purely by
+// how many of the repo's directories each preset's patterns recognize — a hint toward
+// `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 segments = new Set();
+    for (const layer of ARCHITECTURE_PRESETS[name]([]).layers) {
+      for (const pattern of layer.patterns ?? []) {
+        const seg = dirSegmentsFromGlob(pattern).pop();
+        if (seg) segments.add(seg);
+      }
+    }
+    let hits = 0;
+    for (const dir of present) if (segments.has(dir)) hits += 1;
+    return { name, hits };
+  });
+  scored.sort((a, b) => b.hits - a.hits);
+  return scored[0].hits > 0 ? scored[0] : null;
+}
+
+// Group ungoverned files by their parent directory and attach a proposed layer (or the
+// honest "unrecognized"). The single source the coverage report and init both format.
+export function buildUnclassifiedSuggestions(unclassifiedRelFiles) {
+  const byDir = new Map();
+  for (const rel of unclassifiedRelFiles) {
+    const dir = rel.split('/').slice(0, -1).join('/') || '.';
+    byDir.set(dir, (byDir.get(dir) ?? 0) + 1);
+  }
+  return [...byDir.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, files]) => {
+    const hit = suggestLayerForPath(dir);
+    return hit
+      ? {
+          dir,
+          files,
+          layer: hit.layer,
+          ...(hit.alternatives.length > 0 ? { alternatives: hit.alternatives } : {}),
+        }
+      : { dir, files, unrecognized: true };
+  });
+}
+
+// For `init`: propose a layer for every ungoverned top-level directory, descending one level
+// into unrecognized ones so `lib/repositories`, `lib/db` etc. still get a concrete proposal
+// instead of a blanket "lib is ungoverned".

package/bin/lib/violations.mjs

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const color = {
+  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+};
+
+export function baselineKey(violation) {
+  return [
+    violation.ruleId,
+    violation.file,
+    violation.fromLayer ?? '',
+    violation.toLayer ?? '',
+    violation.target ?? '',
+  ].join('|');
+}
+
+export function readBaseline(root, baselinePath) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  if (!fs.existsSync(fullPath)) return { keys: new Set(), fullPath, exists: false };
+  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+  return { keys: new Set(raw.violations ?? []), fullPath, exists: true };
+}
+
+export function writeBaseline(root, baselinePath, violations) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  const keys = [...new Set(violations.map(baselineKey))].sort();
+  fs.writeFileSync(
+    fullPath,
+    `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`
+  );
+  return { fullPath, count: keys.length };
+}
+
+export const FIX_HINTS = {
+  LAYER_IMPORT_VIOLATION:
+    'Depend on a port/interface owned by an inner layer instead, or move this code to a layer allowed to make this import.',
+  LAYER_INTENT_REFERENCE_VIOLATION:
+    'Reference intents through a layer that owns them (e.g. subscribe from an adapter, not from the domain).',
+  RAW_EVENT_PUBLISH:
+    'Define the intent with ark.registry.define(...) and publish through the returned creator.',
+  PUBLISH_MISSING_SOURCE:
+    'Add metadata.source (the publishing intent name) to the publish call.',
+  PUBLISH_SOURCE_LAYER_MISMATCH:
+    'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
+  FORBIDDEN_GLOBAL:
+    'Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort) instead of reaching for the ambient global.',
+  CIRCULAR_DEPENDENCY:
+    'Break the cycle: extract the shared code into a module both sides import, invert one edge behind a port/interface, or merge the files if they are really one unit.',
+};
+
+export function printViolation(violation) {
+  const location = `${violation.file}:${violation.line}`;
+  console.error(`${color.red('✖')} ${color.bold(violation.ruleId)}  ${location}`);
+  if (violation.fromLayer && violation.toLayer) {
+    const target = violation.target ? `  ${color.dim(`(${violation.target})`)}` : '';
+    console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
+  }
+  console.error(`  ${violation.message}`);
+  const hint = FIX_HINTS[violation.ruleId];
+  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
+  console.error('');
+}
+
+// ── Violation diagnosis ──────────────────────────────────────────────────────
+// Groups violations by their layer EDGE (and target subtree) so a wall of N violations reads
+// as "M distinct problems, ranked by size" — the burn-down order. The killer signal: when
+// one edge dominates, the CONTRACT is usually wrong, not the code (e.g. every API route
+// importing the kernel through a sanctioned entrypoint). Freezing that as "debt" buries a
+// config fix behind a baseline, so --update-baseline refuses a lopsided freeze (see guard).
+export const CONCENTRATION_MIN_VIOLATIONS = 10;
+export const CONCENTRATION_SHARE = 0.9;
+
+export function violationEdge(violation) {
+  if (violation.ruleId === 'CIRCULAR_DEPENDENCY') return 'circular dependency';
+  if (violation.ruleId === 'FORBIDDEN_GLOBAL') return `${violation.fromLayer ?? '?'} → ambient global`;
+  if (violation.fromLayer && violation.toLayer) return `${violation.fromLayer} → ${violation.toLayer}`;
+  return violation.ruleId;
+}
+
+// The directory the offending import lands in — the signal for "where does this edge go?".
+// For a LAYER_IMPORT_VIOLATION the target is a resolved file path; cluster by its dir prefix
+// so `kernel/internal/x` and `kernel/internal/y` collapse to one "into kernel/internal/".
+export function violationTargetSubtree(violation) {
+  if (!violation.target || typeof violation.target !== 'string' || !violation.target.includes('/')) {
+    return undefined;
+  }
+  const segments = violation.target.split('/');
+  return segments.slice(0, Math.min(3, segments.length - 1)).join('/');
+}
+
+export function summarizeViolations(violations) {
+  const byEdge = new Map();
+  let typeOnly = 0;
+  for (const violation of violations) {
+    if (violation.typeOnly) typeOnly += 1;
+    const key = violationEdge(violation);
+    const entry = byEdge.get(key) ?? { edge: key, count: 0, typeOnly: 0, targets: new Map() };
+    entry.count += 1;
+    if (violation.typeOnly) entry.typeOnly += 1;
+    const subtree = violationTargetSubtree(violation);
+    if (subtree) entry.targets.set(subtree, (entry.targets.get(subtree) ?? 0) + 1);
+    byEdge.set(key, entry);
+  }
+  const edges = [...byEdge.values()]
+    .map((entry) => ({
+      edge: entry.edge,
+      count: entry.count,
+      typeOnly: entry.typeOnly,
+      topTargets: [...entry.targets.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([dir, count]) => ({ dir, count })),
+    }))
+    .sort((a, b) => b.count - a.count);
+  const total = violations.length;
+  const dominant = edges[0];
+  const dominantShare = total > 0 && dominant ? dominant.count / total : 0;
+  return {
+    total,
+    // Value edges are real runtime coupling; type-only edges (erased at compile time) are
+    // just type placement — fix the value ones first, the type-only ones move with the type.
+    valueCount: total - typeOnly,
+    typeOnlyCount: typeOnly,
+    edges,
+    dominant: dominant ? dominant.edge : undefined,
+    dominantShare,
+    concentrated: total >= CONCENTRATION_MIN_VIOLATIONS && dominantShare >= CONCENTRATION_SHARE,
+  };
+}
+
+export function printViolationBreakdown(summary, { toStderr = false } = {}) {
+  const out = toStderr ? (line) => console.error(line) : (line) => console.log(line);
+  out('');
+  out(`Violation breakdown — ${summary.total} across ${summary.edges.length} edge(s), largest first:`);
+  if (summary.typeOnlyCount > 0) {
+    out(
+      `  ${summary.valueCount} value (runtime coupling — fix first) · ${summary.typeOnlyCount} type-only (type placement — moves with the type)`
+    );
+  }
+  for (const edge of summary.edges) {
+    const pct = Math.round((edge.count / summary.total) * 100);
+    const typeNote = edge.typeOnly > 0 ? `, ${edge.typeOnly} type-only` : '';
+    out(`  ${String(edge.count).padStart(5)}  ${edge.edge}  (${pct}%${typeNote})`);
+    for (const target of edge.topTargets) {
+      out(`         ↳ ${target.count}× into ${target.dir}/`);
+    }
+  }
+  if (summary.concentrated) {
+    out('');
+    out(`⚠ ${Math.round(summary.dominantShare * 100)}% of violations are a SINGLE edge: ${summary.dominant}.`);
+    out('  That usually means the CONTRACT is wrong, not the code — e.g. app-land reaching a');
+    out('  framework/kernel through a sanctioned entrypoint. Before treating it as debt:');
+    out('    • If the edge is intended, allow it — or split the target layer into a public');
+    out('      surface app-land may import + internals it may not (see the target dirs above');
+    out('      to find the surface). Do it via /ark-contract.');
+    out('    • Only the minority hitting real internals is genuine debt for /ark-fix.');
+    out(`  Fixing the contract clears ~${summary.edges[0].count} of ${summary.total} at once.`);
+  }
+}
+
+// Finds strongly-connected components in the resolved import graph. Any component
+// with more than one file is a set of files that transitively import each other —
+// a circular dependency. One violation per component keeps the output minimal and
+// the baseline key stable (anchored at the alphabetically-first member).