arkgate 2.12.0 → 3.0.0

package/bin/ark-shared.mjs

@@ -1,12 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_ARK_CONFIG_RULES,
+  withArkConfigMetadata,
+} from './lib/config-contract.mjs';
+import { collectForbiddenCapabilityUses } from './lib/analysis-engine.mjs';
+import { looksLikeArkIntent } from './lib/source-policy.mjs';
 
 /**
- * Default layer rule matrix + intent-prefix map, shared by both CLIs and by the ark-mcp
- * write-path gate so they enforce identically. These mirror the elevenLayerProfile in
- * src/kernel/layers/ArchitectureProfile.ts; kept here (not imported from dist) because the
- * CLIs run standalone with only `typescript` present, no build step.
+ * Default intent-prefix map shared by both CLIs and the ark-mcp write-path gate. The rule
+ * matrix comes from the generated Domain config contract above. Prefixes mirror the runtime
+ * profile but stay in this standalone CLI module because the CLIs run without a build step.
  */
 export const DEFAULT_INTENT_PREFIXES = [
   { layer: 'DomainModel', prefixes: ['Domain.'] },
@@ -41,35 +46,7 @@ export const DEFAULT_LAYER_DIRECTORIES = {
   Kernel: ['kernel'],
 };
 
-const DEFAULT_ALLOWED_FLOWS = [
-  { from: 'PresentationAdapters', to: 'ApplicationOrchestration' },
-  { from: 'ApplicationOrchestration', to: 'DomainModel' },
-  { from: 'WorkflowSagaEngine', to: 'ApplicationOrchestration' },
-  { from: 'WorkflowSagaEngine', to: 'DomainModel' },
-  { from: 'BackgroundJobsScheduling', to: 'ApplicationOrchestration' },
-];
-
-function flowKey(from, to) {
-  return `${from}->${to}`;
-}
-
-function createStrictDenyRules(layers, allowedFlows) {
-  const allowed = new Set(allowedFlows.map((flow) => flowKey(flow.from, flow.to)));
-  const rules = [];
-  for (const from of layers) {
-    for (const to of layers) {
-      if (from.layer === to.layer) continue;
-      if (allowed.has(flowKey(from.layer, to.layer))) continue;
-      rules.push({ from: from.layer, to: to.layer, allowed: false });
-    }
-  }
-  return rules;
-}
-
-export const DEFAULT_RULES = createStrictDenyRules(
-  DEFAULT_INTENT_PREFIXES,
-  DEFAULT_ALLOWED_FLOWS
-);
+export const DEFAULT_RULES = DEFAULT_ARK_CONFIG_RULES;
 
 /**
  * Default ambient globals forbidden in the domain layer: a pure domain does no I/O and is
@@ -82,7 +59,7 @@ export function createElevenLayerConfig(options = {}) {
   const rootDir = options.rootDir ?? 'src';
   const optional = options.optionalLayers ?? true;
   const prefix = rootDir === '.' ? '' : `${rootDir}/`;
-  const config = {
+  const config = withArkConfigMetadata({
     include: options.include ?? [rootDir],
     layers: DEFAULT_INTENT_PREFIXES.map((entry) => ({
       name: entry.layer,
@@ -96,7 +73,7 @@ export function createElevenLayerConfig(options = {}) {
         : {}),
     })),
     rules: DEFAULT_RULES,
-  };
+  });
   // When a project root is known, overlay Nest/Next/express filename conventions so a
   // flat framework starter is governed on day one (not "0% governed / false green").
   if (options.root) return applyFrameworkLayoutOverlays(config, options.root);
@@ -134,7 +111,7 @@ export function applyFrameworkLayoutOverlays(config, root) {
   try {
     signals = collectRepoShapeSignals(root);
   } catch {
-    return config;
+    return withArkConfigMetadata(config);
   }
 
   const next = {
@@ -155,6 +132,40 @@ export function applyFrameworkLayoutOverlays(config, root) {
     }
   };
 
+  // Framework-free application layouts are common in clean-room starters and
+  // brownfield products. Govern their explicit source conventions without
+  // claiming a framework that package.json does not declare.
+  if (signals.apiSurface && !signals.nestFramework && !signals.expressLike) {
+    ensureInclude('src');
+    mergeLayerPatterns(next, 'PresentationAdapters', [
+      'src/**/routes/**',
+      'src/**/controllers/**',
+      'src/**/http/**',
+      'src/**/api/**',
+    ]);
+    mergeLayerPatterns(next, 'ApplicationOrchestration', [
+      'src/**/services/**',
+      'src/**/use-cases/**',
+      'src/**/usecases/**',
+    ]);
+  }
+
+  if (signals.ui && !signals.nextFramework) {
+    ensureInclude('src');
+    mergeLayerPatterns(next, 'PresentationAdapters', [
+      'src/**/components/**',
+      'src/**/layouts/**',
+      'src/**/ui/**',
+      'src/**/routes/**',
+      'src/**/pages/**',
+    ]);
+    // Match the existing ui-surface profile: UI components may consume their
+    // display-domain models, while the domain still cannot depend on UI.
+    next.rules = next.rules.filter(
+      (rule) => !(rule.from === 'PresentationAdapters' && rule.to === 'DomainModel' && rule.allowed === false)
+    );
+  }
+
   if (signals.nestFramework) {
     ensureInclude('src');
     // Nest flat + modular conventions (controllers/services next to modules).
@@ -337,14 +348,33 @@ export function applyFrameworkLayoutOverlays(config, root) {
   if (signals.libraryOnly && !signals.nestFramework && !signals.nextFramework) {
     ensureInclude('src');
     ensureInclude('lib');
-    mergeLayerPatterns(next, 'DomainModel', ['src/**/*.ts', 'src/**/*.tsx', 'lib/**/*.ts']);
+    // Published libraries commonly expose a root entrypoint instead of src/. Include that
+    // real surface, but not test files: a public package entrypoint is application code and
+    // must not remain outside the contract simply because it is JavaScript or root-level.
+    ensureInclude('.');
+    mergeLayerPatterns(next, 'DomainModel', [
+      'src/**/*.ts',
+      'src/**/*.tsx',
+      'src/**/*.js',
+      'src/**/*.mjs',
+      'src/**/*.cjs',
+      'lib/**/*.ts',
+      'lib/**/*.js',
+      'lib/**/*.mjs',
+      'lib/**/*.cjs',
+      '*.ts',
+      '*.tsx',
+      '*.js',
+      '*.mjs',
+      '*.cjs',
+    ]);
     // Prefer domain over application for a single-folder lib: only domain if no split.
     next.frameworkOverlay = next.frameworkOverlay
       ? `${next.frameworkOverlay}+library`
       : 'library';
   }
 
-  return next;
+  return withArkConfigMetadata(next);
 }
 
 /**
@@ -398,45 +428,8 @@ export function resolveOperatingMode({
   return 'suggest';
 }
 
-/**
- * Find uses of forbidden ambient globals in a TypeScript source file.
- *
- * Detection is deliberately positional, not scope-aware (kept in sync with
- * `collectForbiddenGlobalUses` in src/kernel/ai-gate/AICodeGate.ts — the CLIs must not
- * import from dist):
- *   - a dotted entry ("Date.now") flags `Date.now` property accesses
- *   - a bare entry ("console", "fetch") flags property accesses on it (`console.log`),
- *     direct calls (`fetch(...)`), and constructions (`new WebSocket(...)`)
- * Bare identifier mentions in other positions (types, shadowed locals, import names) are
- * NOT flagged, trading a little recall for near-zero false positives without a type checker.
- *
- * Returns [{ name, node }] where `name` is the matched forbidden entry.
- */
 export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
-  const entries = new Set(forbidden ?? []);
-  if (entries.size === 0) return [];
-  const uses = [];
-
-  const visit = (node) => {
-    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
-      const dotted = `${node.expression.text}.${node.name.text}`;
-      if (entries.has(dotted)) {
-        uses.push({ name: dotted, node });
-      } else if (entries.has(node.expression.text)) {
-        uses.push({ name: node.expression.text, node });
-      }
-    } else if (
-      (ts.isCallExpression(node) || ts.isNewExpression(node)) &&
-      node.expression &&
-      ts.isIdentifier(node.expression) &&
-      entries.has(node.expression.text)
-    ) {
-      uses.push({ name: node.expression.text, node });
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return uses;
+  return collectForbiddenCapabilityUses(ts, sourceFile, forbidden ?? []);
 }
 
 // Layer glob matching — generated from canonical src/domain/layerMatch.ts (see generate:layer-match).
@@ -479,17 +472,8 @@ export function resolveIntentLayer(intent, layers) {
   return sorted.find((layer) => layer.prefixes.some((prefix) => intent.startsWith(prefix)))?.name;
 }
 
-/**
- * Intent-name recognizer. Kept deliberately in sync with `looksLikeIntentName` in
- * src/kernel/ai-gate/AICodeGate.ts: the two live in separate layers on purpose — the
- * CLIs run standalone (with only `typescript` present, no build), so they must not
- * import from the compiled library. Update both if the layer prefixes change.
- */
-const INTENT_NAME =
-  /^(Domain|Application|Adapter|Workflow|Job|Presentation|Reporting|Metadata|Security|Audit|Observability|Kernel)\.[A-Za-z0-9_.]+$/;
-
 export function looksLikeIntent(value) {
-  return INTENT_NAME.test(value);
+  return looksLikeArkIntent(value);
 }
 
 /**
@@ -938,6 +922,85 @@ function isSourceFile(name) {
   return /\.(tsx?|jsx?|mjsx?|cjsx?|mts|cts)$/i.test(name);
 }
 
+function readJsonc(file) {
+  try {
+    const text = fs
+      .readFileSync(file, 'utf8')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/^\s*\/\/.*$/gm, '')
+      .replace(/,\s*([}\]])/g, '$1');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function packageRole(rel, pkg) {
+  const tokens = rel.toLowerCase().split('/');
+  if (tokens.some((token) => ['docs', 'documentation', 'website', 'examples', 'example', 'tests', 'test', 'fixtures'].includes(token))) {
+    return tokens.some((token) => token.startsWith('doc') || token === 'website')
+      ? 'docs'
+      : tokens.some((token) => token.startsWith('test') || token === 'fixtures')
+        ? 'test'
+        : 'example';
+  }
+  if (pkg?.bin) return 'cli';
+  if (pkg?.exports || pkg?.main || pkg?.module || pkg?.types || pkg?.typings) return 'library';
+  return 'application';
+}
+
+function entrypointDirs(pkg) {
+  const values = [];
+  const add = (value) => {
+    if (typeof value === 'string' && !value.includes('*')) values.push(value);
+    else if (value && typeof value === 'object') Object.values(value).forEach(add);
+  };
+  for (const key of ['main', 'module', 'types', 'typings', 'exports']) add(pkg?.[key]);
+  return values.map((value) => path.posix.dirname(value.replace(/^\.\//, ''))).filter((dir) => dir !== '.');
+}
+
+/** Package/import units and their explicit source roots, before framework inference. */
+export function discoverRepoUnits(root) {
+  const packageRels = new Set(['.']);
+  for (const rel of detectTsPackageRoots(root)) packageRels.add(rel);
+  const units = [];
+  for (const rel of packageRels) {
+    const abs = rel === '.' ? root : path.join(root, rel);
+    const pkg = readPackageJson(abs);
+    if (!pkg && rel !== '.') continue;
+    const roots = new Set();
+    for (const name of ['src', 'source']) {
+      if (fs.existsSync(path.join(abs, name))) roots.add(name);
+    }
+    if (rel === '.') {
+      for (const name of ['api', 'lib', 'app', 'frontend', 'web', 'client']) {
+        if (dirHasTsSources(path.join(abs, name), 3)) roots.add(name);
+      }
+    }
+    for (const name of ['tsconfig.json', 'jsconfig.json']) {
+      const config = readJsonc(path.join(abs, name));
+      const rootDir = config?.compilerOptions?.rootDir;
+      if (typeof rootDir === 'string') roots.add(normalizeRel(rootDir));
+      for (const ref of config?.references ?? []) {
+        if (typeof ref?.path === 'string') roots.add(normalizeRel(ref.path).replace(/^\.\//, ''));
+      }
+    }
+    for (const dir of entrypointDirs(pkg)) {
+      if (!['dist', 'build', 'lib'].includes(dir.split('/')[0])) roots.add(normalizeRel(dir));
+    }
+    if (roots.size === 0 && dirHasTsSources(abs, 2)) roots.add('.');
+    const productionDeps = { ...(pkg?.dependencies ?? {}), ...(pkg?.peerDependencies ?? {}), ...(pkg?.optionalDependencies ?? {}) };
+    units.push({
+      root: rel,
+      role: packageRole(rel, pkg),
+      sourceRoots: [...roots],
+      productionDeps,
+      devDependencies: { ...(pkg?.devDependencies ?? {}) },
+    });
+  }
+  return units;
+}
+
 function walkSourceFiles(dir, files = [], depth = 0) {
   if (depth > 12) return files;
   const stat = fs.statSync(dir, { throwIfNoEntry: false });
@@ -1016,36 +1079,9 @@ function countTsxFiles(files) {
  */
 export function collectAggregatedDeps(root) {
   const deps = {};
-  const mergePkg = (pkg) => {
-    if (!pkg || typeof pkg !== 'object') return;
-    for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
-      const block = pkg[key];
-      if (block && typeof block === 'object') Object.assign(deps, block);
-    }
-  };
-  mergePkg(readPackageJson(root));
-  let entries = [];
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch {
-    return deps;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-    const childRoot = path.join(root, entry.name);
-    mergePkg(readPackageJson(childRoot));
-    // One level under conventional multi-package roots
-    if (['packages', 'apps', 'services', 'plugins', 'packages-internal'].includes(entry.name)) {
-      try {
-        for (const sub of fs.readdirSync(childRoot, { withFileTypes: true })) {
-          if (sub.isDirectory() && !sub.name.startsWith('.')) {
-            mergePkg(readPackageJson(path.join(childRoot, sub.name)));
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-    }
+  for (const unit of discoverRepoUnits(root)) {
+    if (['docs', 'example', 'test'].includes(unit.role)) continue;
+    Object.assign(deps, unit.productionDeps);
   }
   return deps;
 }
@@ -1056,27 +1092,32 @@ export function collectAggregatedDeps(root) {
  */
 export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
+  const repoUnits = discoverRepoUnits(root);
   const workspaceDirs = detectWorkspaces(root);
   const workspaces = workspaceDirs.length > 0;
   // Include frontend/web/client — common Next monorepo app folders.
-  const candidateScanDirs = [
-    'src',
-    'lib',
-    'api',
-    'packages',
-    'apps',
-    'frontend',
-    'web',
-    'client',
-    'app',
-    ...workspaceDirs,
-  ];
+  const candidateScanDirs = repoUnits
+    .filter((unit) => !['docs', 'example', 'test'].includes(unit.role))
+    .flatMap((unit) => unit.sourceRoots.map((sourceRoot) =>
+      normalizeRel(path.posix.join(unit.root === '.' ? '' : unit.root, sourceRoot))
+    ));
   const srcDirs = [...new Set(candidateScanDirs)].filter((d) =>
     fs.existsSync(path.join(root, d))
   );
   const scanRoots = srcDirs.length > 0 ? srcDirs.map((d) => path.join(root, d)) : [root];
-  const sourceFiles = scanRoots.flatMap((dir) => walkSourceFiles(dir));
+  const sourceFiles = [...new Set(scanRoots.flatMap((dir) => walkSourceFiles(dir)))];
   const sourceFileCount = sourceFiles.length;
+  const excludedUnitRoots = repoUnits
+    .filter((unit) => ['docs', 'example', 'test'].includes(unit.role) && unit.root !== '.')
+    .map((unit) => `${unit.root}/`);
+  const productionFiles = walkSourceFiles(root).filter((file) => {
+    const rel = path.relative(root, file).split(path.sep).join('/');
+    return !excludedUnitRoots.some((prefix) => rel.startsWith(prefix));
+  });
+  const discoveredFileSet = new Set(sourceFiles.map((file) => path.resolve(file)));
+  const projectedGovernedCoverage = productionFiles.length === 0
+    ? 0
+    : Math.round((productionFiles.filter((file) => discoveredFileSet.has(path.resolve(file))).length / productionFiles.length) * 100);
   const tinyTree = sourceFileCount < 3;
 
   // Nested package.json deps (not root-only) — critical for monorepo Next under frontend/
@@ -1214,6 +1255,8 @@ export function collectRepoShapeSignals(root) {
   }
 
   return {
+    repoUnits,
+    discoveredRoots: srcDirs,
     workspaces,
     workspaceDirs,
     ui,
@@ -1231,6 +1274,7 @@ export function collectRepoShapeSignals(root) {
     libraryOnly,
     tinyTree,
     sourceFileCount,
+    projectedGovernedCoverage,
     domain,
     application,
     domainHeavy,
@@ -1317,6 +1361,16 @@ export function whyFromMatchedSignals(signals, matched) {
   return why;
 }
 
+function evidenceFromMatchedSignals(signals, matched) {
+  return (matched ?? []).flatMap((token) => {
+    const negative = token.startsWith('!');
+    const signal = negative ? token.slice(1) : token;
+    const label = negative ? NEGATIVE_SIGNAL_WHY[signal] : SIGNAL_WHY[signal];
+    if (!label || !signals[signal]) return [];
+    return [{ signal, effect: negative ? 'negative' : 'positive', explanation: label(signals) }];
+  });
+}
+
 export function defaultPlaybookPath() {
   return path.join(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -1401,6 +1455,11 @@ export function scoreArchetypes(signals, playbook) {
       label: fallback.label,
       preset: fallback.preset,
       confidence,
+      requiresConfirmation: true,
+      confirmationReasons: [
+        `projected governed coverage is ${signals.projectedGovernedCoverage ?? 0}% (below 90%)`,
+        'no archetype received a positive score',
+      ],
       phases: fallback.phases,
       analogy: fallback.analogy,
       antiPatterns: fallback.antiPatterns,
@@ -1422,6 +1481,10 @@ export function scoreArchetypes(signals, playbook) {
   if (thinTs) {
     confidence = Math.min(confidence, 0.28);
   }
+  const closeRecommendations = Boolean(second && top.score - second.score <= 2);
+  const lowProjectedCoverage = (signals.projectedGovernedCoverage ?? 0) < 90;
+  if (closeRecommendations) confidence = Math.min(confidence, 0.49);
+  if (lowProjectedCoverage) confidence = Math.min(confidence, 0.49);
 
   return {
     ranked: scored,
@@ -1436,6 +1499,12 @@ export function scoreArchetypes(signals, playbook) {
             'TypeScript/JS surface is thin or missing — treat the archetype as a weak hint. Prefer ark-check --suggest-include / --adopt-contract on the real package roots before scaffolding.',
         }
       : {}),
+    requiresConfirmation: closeRecommendations || thinTs || lowProjectedCoverage,
+    confirmationReasons: [
+      ...(closeRecommendations ? ['top recommendations are within 2 score points'] : []),
+      ...(lowProjectedCoverage ? [`projected governed coverage is ${signals.projectedGovernedCoverage}% (below 90%)`] : []),
+      ...(thinTs ? ['the discovered source surface is thin'] : []),
+    ],
     phases: top.phases,
     analogy: top.analogy,
     antiPatterns: top.antiPatterns,
@@ -1473,6 +1542,8 @@ export function buildArchitectureRecommendation(root, options = {}) {
     label: result.label,
     preset: result.preset,
     confidence: result.confidence,
+    requiresConfirmation: result.requiresConfirmation ?? false,
+    confirmationReasons: result.confirmationReasons ?? [],
     ...(result.thinTsSurface ? { thinTsSurface: true, caution: result.caution } : {}),
     phases: result.phases,
     adoptInOrder,
@@ -1480,6 +1551,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     antiPatterns: result.antiPatterns,
     books: result.books,
     why: whyFromMatchedSignals(signals, result.matched),
+    evidence: evidenceFromMatchedSignals(signals, result.matched),
     matchedSignals: result.matched,
     runnerUp: result.runnerUp,
     toolHints: signals.toolHints,
@@ -1487,6 +1559,15 @@ export function buildArchitectureRecommendation(root, options = {}) {
     policyPack: policyPackId,
     signals: {
       sourceFileCount: signals.sourceFileCount,
+      projectedGovernedCoverage: signals.projectedGovernedCoverage,
+      discoveredRoots: signals.discoveredRoots,
+      packageUnits: signals.repoUnits.map((unit) => ({
+        root: unit.root,
+        role: unit.role,
+        sourceRoots: unit.sourceRoots,
+        productionDependencies: Object.keys(unit.productionDeps).sort(),
+        devOnlyDependencies: Object.keys(unit.devDependencies).sort(),
+      })),
       workspaces: signals.workspaces,
       ui: signals.ui,
       apiSurface: signals.apiSurface,
@@ -1583,6 +1664,10 @@ export function formatArchitectureRecommendationHuman(recommendation) {
   lines.push('');
   lines.push(`Archetype: ${recommendation.archetype} — ${recommendation.label}`);
   lines.push(`Preset: ${recommendation.preset} (confidence ${recommendation.confidence})`);
+  if (recommendation.requiresConfirmation) {
+    lines.push('⚠ Confirmation required before applying this recommendation.');
+    for (const reason of recommendation.confirmationReasons ?? []) lines.push(`  - ${reason}`);
+  }
   if (recommendation.galleryStarter) {
     lines.push(`Gallery starter: ${recommendation.galleryStarter}`);
   }
@@ -1692,6 +1777,8 @@ export function buildAdoptionPlanDocument(recommendation) {
     label: recommendation.label,
     preset: recommendation.preset,
     confidence: recommendation.confidence,
+    requiresConfirmation: recommendation.requiresConfirmation ?? false,
+    confirmationReasons: recommendation.confirmationReasons ?? [],
     phases: recommendation.phases,
     adoptInOrder: recommendation.adoptInOrder,
     matchedSignals: recommendation.matchedSignals ?? [],