arkgate 4.8.24 → 4.8.25

package/bin/lib/entry-points-io.mjs

@@ -0,0 +1,424 @@
+/**
+ * Entry evidence for the files-nothing-imports advisory (ADR 0037 D3).
+ *
+ * A closed list of sources, each with a `source` label: package.json fields
+ * and scripts (plus CI workflow run steps), framework conventions, the
+ * arkRun / arkOrder / slice-wall roots in ark.config.json, config and setup
+ * files (and the source files a config file names), ambient declaration files,
+ * and the optional `.ark/entry-points.json` sidecar. Reads are bounded. A file
+ * any source covers is never listed. Advisory input only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectWorkspaces, globToRegExp } from '../ark-shared.mjs';
+
+export const ENTRY_POINTS_SIDECAR = '.ark/entry-points.json';
+const SIDECAR_MAX_BYTES = 64 * 1024;
+const SIDECAR_MAX_ENTRIES = 200;
+const MAX_PACKAGES = 200;
+const MAX_TEXT_BYTES = 256 * 1024;
+const MAX_WORKFLOWS = 50;
+const SOURCE_EXT = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const BUILT_DIRS = ['dist', 'build', 'lib', 'out'];
+const CONFIG_FILE = /(?:^|\/)[^/]+\.config\.[cm]?[jt]s$/;
+const SETUP_FILE = /(?:^|\/)(?:vitest\.setup|jest\.setup|setupTests)\.[cm]?[jt]sx?$/;
+const NEXT_ROUTE =
+  /^(?:src\/)?app\/(?:.*\/)?(?:page|layout|template|loading|error|global-error|not-found|default|route|opengraph-image|twitter-image|icon|apple-icon|sitemap|robots|manifest)\.[cm]?[jt]sx?$/;
+const NEXT_PAGES = /^(?:src\/)?pages\//;
+const NEXT_ROOT_FILE = /^(?:src\/)?(?:middleware|proxy|instrumentation|instrumentation-client|mdx-components)\.[cm]?[jt]sx?$/;
+const STORY_FILE = /\.stories\.[cm]?[jt]sx?$/;
+const PATH_TOKEN = /[\w@.][\w@./-]*\.[cm]?[jt]sx?(?![\w/])/g;
+const STRING_LITERAL = /(['"`])([^'"`\n]{1,300})\1/g;
+const KEY_VALUE = /(?:(['"])([^'"\n]{1,200})\1|([A-Za-z_$][\w$]*))\s*:\s*(['"])([^'"\n]{1,300})\4/g;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+function readText(absolute, max = MAX_TEXT_BYTES) {
+  try {
+    const stat = fs.statSync(absolute);
+    if (!stat.isFile() || stat.size > max) return null;
+    return fs.readFileSync(absolute, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function readJson(absolute) {
+  const text = readText(absolute);
+  if (text == null) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** tsconfig is JSONC: drop comments and trailing commas before parsing. */
+function readJsonc(absolute) {
+  const text = readText(absolute);
+  if (text == null) return null;
+  const stripped = text
+    .replace(/("(?:\\.|[^"\\])*")|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (match, quoted) => quoted ?? '')
+    .replace(/,(\s*[}\]])/g, '$1');
+  try {
+    return JSON.parse(stripped);
+  } catch {
+    return null;
+  }
+}
+
+/** Repo-relative, posix, no leading `./`; null when it leaves the root. */
+function joinRel(base, rel) {
+  const raw = String(rel).replace(/\\/g, '/').replace(/^\/+/, '');
+  const joined = path.posix.normalize(base === '.' || base === '' ? raw : `${base}/${raw}`);
+  if (joined === '..' || joined.startsWith('../')) return null;
+  return joined.replace(/^\.\//, '');
+}
+
+function stripSourceExt(rel) {
+  return rel.replace(DECLARATION_FILE, '').replace(SOURCE_FILE, '');
+}
+
+/** Governed file for a path stem: exact, then with a source extension, then as a directory index. */
+export function probeGoverned(stem, governed) {
+  if (!stem) return null;
+  if (governed.has(stem)) return stem;
+  for (const ext of SOURCE_EXT) if (governed.has(`${stem}${ext}`)) return `${stem}${ext}`;
+  for (const ext of SOURCE_EXT) if (governed.has(`${stem}/index${ext}`)) return `${stem}/index${ext}`;
+  return null;
+}
+
+function packageRoots(root, governed) {
+  const roots = new Set(['.']);
+  let dirs = [];
+  try {
+    dirs = detectWorkspaces(root);
+  } catch {
+    dirs = [];
+  }
+  const hasGovernedUnder = (dir) => {
+    const prefix = `${dir}/`;
+    for (const file of governed) if (file.startsWith(prefix)) return true;
+    return false;
+  };
+  const add = (dir) => {
+    if (roots.size < MAX_PACKAGES && hasGovernedUnder(dir)) roots.add(dir);
+  };
+  for (const dir of dirs) {
+    const absolute = path.join(root, dir);
+    if (fs.existsSync(path.join(absolute, 'package.json'))) {
+      add(dir);
+      continue;
+    }
+    let children = [];
+    try {
+      children = fs.readdirSync(absolute, { withFileTypes: true });
+    } catch {
+      children = [];
+    }
+    for (const child of children) {
+      if (!child.isDirectory() || child.name.startsWith('.') || child.name === 'node_modules') continue;
+      if (fs.existsSync(path.join(absolute, child.name, 'package.json'))) add(`${dir}/${child.name}`);
+    }
+  }
+  return [...roots].sort();
+}
+
+function stringLeaves(value, out = []) {
+  if (typeof value === 'string') out.push(value);
+  else if (Array.isArray(value)) for (const item of value) stringLeaves(item, out);
+  else if (value && typeof value === 'object') for (const item of Object.values(value)) stringLeaves(item, out);
+  return out;
+}
+
+function tsOutput(root, pkgRoot, ts) {
+  const file = path.join(root, pkgRoot, 'tsconfig.json');
+  let options;
+  if (ts?.readConfigFile && ts?.sys?.readFile) {
+    options = ts.readConfigFile(file, ts.sys.readFile)?.config?.compilerOptions;
+  } else {
+    options = readJsonc(file)?.compilerOptions;
+  }
+  const clean = (value) =>
+    typeof value === 'string' && value.length > 0 ? value.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '') : null;
+  return { outDir: clean(options?.outDir), rootDir: clean(options?.rootDir) };
+}
+
+/** Config files at a package root: their literals name entries and built-name maps. */
+function scanConfigFiles(root, pkgRoot, governed) {
+  const named = new Set();
+  const outNames = new Map();
+  let entries = [];
+  try {
+    entries = fs.readdirSync(path.join(root, pkgRoot), { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !CONFIG_FILE.test(entry.name)) continue;
+    const text = readText(path.join(root, pkgRoot, entry.name));
+    if (text == null) continue;
+    for (const match of text.matchAll(KEY_VALUE)) {
+      const key = match[2] ?? match[3];
+      const target = probeGoverned(stripSourceExt(joinRel(pkgRoot, match[5]) ?? ''), governed);
+      if (key && target && !outNames.has(key)) outNames.set(key, target);
+    }
+    for (const match of text.matchAll(STRING_LITERAL)) {
+      const literal = match[2];
+      if (!literal.includes('/') && !SOURCE_FILE.test(literal)) continue;
+      const target = probeGoverned(stripSourceExt(joinRel(pkgRoot, literal) ?? ''), governed);
+      if (!target) continue;
+      named.add(target);
+      const stem = path.posix.basename(stripSourceExt(target));
+      if (!outNames.has(stem)) outNames.set(stem, target);
+    }
+  }
+  return { named, outNames };
+}
+
+/**
+ * Built path (`dist/x.js`) or source path → governed source.
+ * @returns {{ path: string } | { unmapped: string } | null} null = not ours to judge
+ */
+function mapToSource(rel, ctx) {
+  if (rel.includes('*')) return { unmapped: 'pattern export' };
+  const ext = path.posix.extname(rel);
+  if (ext && !SOURCE_FILE.test(rel) && !DECLARATION_FILE.test(rel)) return null;
+  if (ctx.governed.has(rel)) return { path: rel };
+  const direct = probeGoverned(stripSourceExt(rel), ctx.governed);
+  if (direct) return { path: direct };
+  const builtDirs = [...new Set([ctx.outDir, ...BUILT_DIRS].filter(Boolean))];
+  for (const built of builtDirs) {
+    const prefix = `${joinRel(ctx.pkgRoot, built)}/`;
+    if (!rel.startsWith(prefix)) continue;
+    const rest = stripSourceExt(rel.slice(prefix.length));
+    const viaBundler = ctx.outNames.get(rest);
+    if (viaBundler) return { path: viaBundler };
+    if (built === ctx.outDir && ctx.rootDir) {
+      const viaTsconfig = probeGoverned(joinRel(ctx.pkgRoot, `${ctx.rootDir}/${rest}`), ctx.governed);
+      if (viaTsconfig) return { path: viaTsconfig };
+    }
+    const viaSrc = probeGoverned(joinRel(ctx.pkgRoot, `src/${rest}`), ctx.governed);
+    if (viaSrc) return { path: viaSrc };
+    return { unmapped: 'built path maps to no governed source file' };
+  }
+  if (fs.existsSync(path.join(ctx.root, rel))) return null;
+  return { unmapped: 'path does not exist' };
+}
+
+function dependencyNames(pkg) {
+  return new Set(
+    [pkg?.dependencies, pkg?.devDependencies, pkg?.peerDependencies]
+      .flatMap((deps) => (deps && typeof deps === 'object' ? Object.keys(deps) : []))
+  );
+}
+
+function viteEntries(root, pkgRoot, governed) {
+  const html = readText(path.join(root, pkgRoot, 'index.html'));
+  if (html == null) return [];
+  const out = [];
+  for (const tag of html.matchAll(/<script\b[^>]*>/gi)) {
+    if (!/type\s*=\s*["']module["']/i.test(tag[0])) continue;
+    const src = /src\s*=\s*["']([^"']+)["']/i.exec(tag[0])?.[1];
+    const target = src ? probeGoverned(stripSourceExt(joinRel(pkgRoot, src) ?? ''), governed) : null;
+    if (target) out.push(target);
+  }
+  return out;
+}
+
+function nestEntry(root, pkgRoot, governed) {
+  const cli = readJson(path.join(root, pkgRoot, 'nest-cli.json'));
+  const sourceRoot = typeof cli?.sourceRoot === 'string' ? cli.sourceRoot : 'src';
+  const entryFile = typeof cli?.entryFile === 'string' ? cli.entryFile : 'main';
+  return probeGoverned(joinRel(pkgRoot, `${sourceRoot}/${entryFile}`), governed);
+}
+
+function workflowTexts(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((name) => /\.ya?ml$/.test(name)).sort().slice(0, MAX_WORKFLOWS);
+  } catch {
+    names = [];
+  }
+  return names.map((name) => readText(path.join(dir, name)) ?? '');
+}
+
+function arkConfigGlobs(config) {
+  const globs = [
+    ...(config?.arkRun?.kernelRoots ?? []),
+    ...(config?.arkRun?.compositionRoots ?? []),
+    ...(config?.arkOrder?.planeRoots ?? []),
+  ];
+  for (const rule of Array.isArray(config?.rules) ? config.rules : []) {
+    const stopAt = rule?.sharedImportsSlice?.stopAt;
+    if (Array.isArray(stopAt)) globs.push(...stopAt);
+  }
+  return globs.filter((glob) => typeof glob === 'string' && glob.length > 0);
+}
+
+function compileGlob(glob) {
+  try {
+    return globToRegExp(glob);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Optional user-declared entries. Malformed → suppresses nothing; a line says so.
+ * @param {string} root
+ * @param {string} today YYYY-MM-DD, supplied by the caller (no clock here)
+ */
+export function loadEntryPointsSidecar(root, today) {
+  const absolute = path.join(root, ENTRY_POINTS_SIDECAR);
+  let stat;
+  try {
+    stat = fs.statSync(absolute);
+  } catch {
+    return { status: 'absent', active: [], expired: [] };
+  }
+  const malformed = (why) => ({
+    status: 'malformed',
+    active: [],
+    expired: [],
+    note: `${ENTRY_POINTS_SIDECAR} was not used (${why}). It suppresses nothing until it is fixed.`,
+  });
+  if (!stat.isFile() || stat.size > SIDECAR_MAX_BYTES) return malformed('larger than 64 KiB');
+  const doc = readJson(absolute);
+  if (!doc || doc.schemaVersion !== '1' || !Array.isArray(doc.entryPoints)) {
+    return malformed('expected { "schemaVersion": "1", "entryPoints": [...] }');
+  }
+  if (doc.entryPoints.length > SIDECAR_MAX_ENTRIES) return malformed('more than 200 entries');
+  const active = [];
+  const expired = [];
+  for (const row of doc.entryPoints) {
+    const glob = typeof row?.glob === 'string' ? row.glob.trim() : '';
+    const reason = typeof row?.reason === 'string' ? row.reason.trim() : '';
+    const reviewBy = row?.reviewBy;
+    if (!glob || !reason || (reviewBy !== undefined && (typeof reviewBy !== 'string' || !DATE.test(reviewBy)))) {
+      return malformed('every entry needs a glob and a reason; reviewBy is YYYY-MM-DD');
+    }
+    if (reviewBy !== undefined && typeof today === 'string' && reviewBy < today) expired.push({ glob, reason, reviewBy });
+    else active.push({ glob, reason, ...(reviewBy ? { reviewBy } : {}) });
+  }
+  return { status: 'loaded', active, expired };
+}
+
+/**
+ * @param {string} root
+ * @param {{ governed: string[], config?: object, ts?: object, today?: string }} input
+ * @returns {{
+ *   entries: Map<string, string>,
+ *   unmapped: Array<{ declared: string, source: string, reason: string }>,
+ *   frameworks: string[],
+ *   sidecar: ReturnType<typeof loadEntryPointsSidecar>,
+ *   expiredByPath: Map<string, string[]>,
+ * }}
+ */
+export function collectEntryPoints(root, input) {
+  const governed = new Set(input.governed);
+  const entries = new Map();
+  const unmapped = [];
+  const frameworks = new Set();
+  const cover = (file, source) => {
+    if (file && governed.has(file) && !entries.has(file)) entries.set(file, source);
+  };
+  const workflows = workflowTexts(root);
+
+  for (const pkgRoot of packageRoots(root, governed)) {
+    const pkg = readJson(path.join(root, pkgRoot, 'package.json'));
+    const { named, outNames } = scanConfigFiles(root, pkgRoot, governed);
+    const ctx = { root, pkgRoot, governed, outNames, ...tsOutput(root, pkgRoot, input.ts) };
+    if (pkg) {
+      const fields = [pkg.main, pkg.module, pkg.types, pkg.typings, pkg.browser, pkg.bin, pkg.exports];
+      for (const leaf of stringLeaves(fields)) {
+        const rel = joinRel(pkgRoot, leaf);
+        const mapped = rel ? mapToSource(rel, ctx) : null;
+        if (mapped?.path) cover(mapped.path, 'package-json');
+        else if (mapped?.unmapped) unmapped.push({ declared: rel, source: 'package-json', reason: mapped.unmapped });
+      }
+      for (const script of stringLeaves(pkg.scripts ?? {})) {
+        for (const token of script.match(PATH_TOKEN) ?? []) {
+          const rel = joinRel(pkgRoot, token);
+          const mapped = rel ? mapToSource(rel, ctx) : null;
+          if (mapped?.path) cover(mapped.path, 'package-scripts');
+        }
+      }
+    }
+    if (pkgRoot === '.') {
+      for (const text of workflows) {
+        for (const token of text.match(PATH_TOKEN) ?? []) {
+          const rel = joinRel('.', token);
+          const mapped = rel ? mapToSource(rel, ctx) : null;
+          if (mapped?.path) cover(mapped.path, 'package-scripts');
+        }
+      }
+    }
+    for (const file of named) cover(file, 'config-file');
+
+    const deps = dependencyNames(pkg);
+    const prefix = pkgRoot === '.' ? '' : `${pkgRoot}/`;
+    const local = (file) => (file.startsWith(prefix) ? file.slice(prefix.length) : null);
+    const nextConfig = ['js', 'mjs', 'cjs', 'ts', 'mts'].some((ext) =>
+      fs.existsSync(path.join(root, pkgRoot, `next.config.${ext}`))
+    );
+    if (deps.has('next') || nextConfig) {
+      frameworks.add('next');
+      for (const file of governed) {
+        const rest = local(file);
+        if (rest && (NEXT_ROUTE.test(rest) || NEXT_PAGES.test(rest) || NEXT_ROOT_FILE.test(rest))) cover(file, 'framework');
+      }
+    }
+    const vite = viteEntries(root, pkgRoot, governed);
+    if (vite.length > 0 || deps.has('vite')) frameworks.add('vite');
+    for (const file of vite) cover(file, 'framework');
+    if (deps.has('@nestjs/core')) {
+      frameworks.add('nest');
+      cover(nestEntry(root, pkgRoot, governed), 'framework');
+    }
+    if ([...deps].some((name) => name === 'storybook' || name.startsWith('@storybook/'))) frameworks.add('storybook');
+  }
+  if (fs.existsSync(path.join(root, 'vercel.json'))) {
+    frameworks.add('vercel');
+    for (const file of governed) if (file.startsWith('api/')) cover(file, 'framework');
+  }
+
+  const arkGlobs = arkConfigGlobs(input.config).map(compileGlob).filter(Boolean);
+  const sidecar = loadEntryPointsSidecar(root, input.today);
+  const active = sidecar.active.map((row) => compileGlob(row.glob)).filter(Boolean);
+  const expired = sidecar.expired.map((row) => ({ row, re: compileGlob(row.glob) })).filter((item) => item.re);
+  const expiredByPath = new Map();
+  for (const file of governed) {
+    if (STORY_FILE.test(file)) cover(file, 'framework');
+    if (CONFIG_FILE.test(file) || SETUP_FILE.test(file)) cover(file, 'config-file');
+    if (arkGlobs.some((re) => re.test(file))) cover(file, 'ark-config');
+    if (active.some((re) => re.test(file))) cover(file, 'sidecar');
+    for (const { row, re } of expired) {
+      if (!re.test(file)) continue;
+      const notes = expiredByPath.get(file) ?? [];
+      notes.push(`its ${ENTRY_POINTS_SIDECAR} entry (${row.glob}) passed reviewBy ${row.reviewBy}`);
+      expiredByPath.set(file, notes);
+    }
+  }
+  unmapped.sort((left, right) => (left.declared < right.declared ? -1 : left.declared > right.declared ? 1 : 0));
+  return { entries, unmapped, frameworks: [...frameworks].sort(), sidecar, expiredByPath };
+}
+
+/** Ambient declaration files (`declare global` / `declare module`), checked lexically. */
+export function ambientEntries(root, candidates) {
+  const out = [];
+  for (const rel of candidates) {
+    const text = readText(path.join(root, rel));
+    if (text && /\bdeclare\s+(?:global\b|module\s+['"])/.test(text)) out.push(rel);
+  }
+  return out;
+}
+
+/** Entry counts per source label, for the evidence line. */
+export function entriesBySource(entries) {
+  const bySource = {};
+  for (const source of entries.values()) bySource[source] = (bySource[source] ?? 0) + 1;
+  return bySource;
+}

package/bin/lib/extra-merge-teeth.mjs

@@ -81,6 +81,42 @@ export function demoteExtraPlaneTeethUnderClassificationFloor(violations, classi
 }
 /** Stamp for extra-plane honesty: never one architecture score. */
 export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score); ArkOrder = the few big product choices (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth. Advisory ArkOrder ≠ merge teeth.';
+/**
+ * Doctor callers pass loosely typed ArkRules counts; the plane is active only
+ * when `active` is literally true. Counts pass through for countOrZero.
+ */
+export function mergePlanesArkRulesInput(arkRules) {
+    return {
+        active: arkRules?.active === true,
+        structureEnforced: arkRules?.structureEnforced,
+        structureTotal: arkRules?.structureTotal,
+        structureAdvisory: arkRules?.structureAdvisory,
+        invariantEnforced: arkRules?.invariantEnforced,
+        invariantTotal: arkRules?.invariantTotal,
+        invariantAdvisory: arkRules?.invariantAdvisory,
+        covered: arkRules?.covered,
+        uncovered: arkRules?.uncovered,
+    };
+}
+/** Thin status slice — counts only; residual null means unknown, not green. */
+export function projectExtraPlaneStatus(input = {}) {
+    const present = input.present === true;
+    const mode = input.mode === 'enforced' || input.mode === 'advisory' ? input.mode : null;
+    const residualRaw = input.residual;
+    let residual = null;
+    if (typeof residualRaw === 'number' && Number.isFinite(residualRaw) && residualRaw >= 0) {
+        residual = Math.floor(residualRaw);
+    }
+    if (!present)
+        residual = residual == null ? 0 : residual;
+    return {
+        notAScore: true,
+        present,
+        mode: present ? mode : null,
+        extraMergeTeeth: present && mode === 'enforced' && input.extraMergeTeeth === true,
+        residual,
+    };
+}
 function countOrZero(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }

package/bin/lib/field-install.mjs

@@ -40,21 +40,41 @@ function matchingBrace(text, openIndex) {
   return -1;
 }
 
-function addDevDependencyPreservingFormat(source, version) {
+/**
+ * Insert `"name": value` into a top-level package.json object section (created at
+ * the end of the root object when absent) while preserving indentation, line
+ * endings, and single-line vs multi-line layout. Never replaces an existing key;
+ * callers check for it first.
+ *
+ * @param {string} source package.json text
+ * @param {string} section top-level key, e.g. `scripts` or `devDependencies`
+ * @param {string} name property name
+ * @param {string} value property value (JSON-encoded here)
+ * @param {string} [unbalancedLabel] error label when the section's braces do not close
+ */
+export function addPackageJsonPropertyPreservingFormat(
+  source,
+  section,
+  name,
+  value,
+  unbalancedLabel = section
+) {
   const multiline = /\r?\n/.test(source);
   const eol = source.includes('\r\n') ? '\r\n' : '\n';
   const rootPropertyIndent = source.match(/\r?\n([ \t]+)"[^"\n]+"\s*:/)?.[1] ?? '  ';
   const indentUnit = rootPropertyIndent;
-  const encoded = JSON.stringify(version);
-  const devMatch = /"devDependencies"\s*:\s*\{/.exec(source);
+  const encoded = JSON.stringify(value);
+  const key = JSON.stringify(name);
+  const sectionKey = JSON.stringify(section);
+  const sectionMatch = new RegExp(`${sectionKey}\\s*:\\s*\\{`).exec(source);
 
-  if (devMatch) {
-    const open = source.indexOf('{', devMatch.index);
+  if (sectionMatch) {
+    const open = source.indexOf('{', sectionMatch.index);
     const close = matchingBrace(source, open);
-    if (close === -1) throw new Error('Unbalanced devDependencies object');
+    if (close === -1) throw new Error(`Unbalanced ${unbalancedLabel} object`);
     const body = source.slice(open + 1, close);
     if (!multiline) {
-      const addition = body.trim() ? `,"arkgate":${encoded}` : `"arkgate":${encoded}`;
+      const addition = body.trim() ? `,${key}:${encoded}` : `${key}:${encoded}`;
       return `${source.slice(0, close)}${addition}${source.slice(close)}`;
     }
     const beforeClose = source.slice(0, close);
@@ -63,8 +83,8 @@ function addDevDependencyPreservingFormat(source, version) {
     const closingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
     const propertyIndent = `${closingIndent}${indentUnit}`;
     const addition = body.trim()
-      ? `,${eol}${propertyIndent}"arkgate": ${encoded}`
-      : `${propertyIndent}"arkgate": ${encoded}`;
+      ? `,${eol}${propertyIndent}${key}: ${encoded}`
+      : `${propertyIndent}${key}: ${encoded}`;
     return `${source.slice(0, contentEnd)}${addition}${eol}${closingIndent}${source.slice(close)}`;
   }
 
@@ -73,16 +93,20 @@ function addDevDependencyPreservingFormat(source, version) {
   const rootBody = source.slice(0, rootClose);
   if (!multiline) {
     const separator = rootBody.trim().endsWith('{') ? '' : ',';
-    return `${rootBody}${separator}"devDependencies":{"arkgate":${encoded}}${source.slice(rootClose)}`;
+    return `${rootBody}${separator}${sectionKey}:{${key}:${encoded}}${source.slice(rootClose)}`;
   }
   const trailing = rootBody.match(/\s*$/)?.[0] ?? '';
   const contentEnd = rootClose - trailing.length;
   const rootClosingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
   const separator = source.slice(0, contentEnd).trimEnd().endsWith('{') ? '' : ',';
-  const addition = `${separator}${eol}${rootPropertyIndent}"devDependencies": {${eol}${rootPropertyIndent}${indentUnit}"arkgate": ${encoded}${eol}${rootPropertyIndent}}`;
+  const addition = `${separator}${eol}${rootPropertyIndent}${sectionKey}: {${eol}${rootPropertyIndent}${indentUnit}${key}: ${encoded}${eol}${rootPropertyIndent}}`;
   return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
 }
 
+function addDevDependencyPreservingFormat(source, version) {
+  return addPackageJsonPropertyPreservingFormat(source, 'devDependencies', 'arkgate', version);
+}
+
 function replaceArkgateDependencyPreservingFormat(source, version) {
   const encoded = JSON.stringify(version);
   const next = source.replace(/("arkgate"\s*:\s*)(?:"(?:\\.|[^"\\])*")/, `$1${encoded}`);
@@ -126,7 +150,7 @@ const YAML_CONCURRENCY_GROUP_RE = /^\s*group:\s+/;
  * True when the line invokes ark-check / arkgate-check (npx/pnpm/yarn/npm/node/run).
  * YAML concurrency.group and job-id keys that only contain the name are not invocations.
  */
-export function isArkCheckInvocationLine(command) {
+function isArkCheckInvocationLine(command) {
   if (typeof command !== 'string' || !command.trim()) return false;
   if (/^\s*#/.test(command)) return false;
   if (YAML_CHECK_JOB_ID_RE.test(command)) return false;
@@ -258,7 +282,7 @@ export function syncBaselineIntoCheckSurfaces(root, opts = {}) {
  * @param {string} root
  * @returns {string|null}
  */
-export function readDeclaredArkgatePin(root) {
+function readDeclaredArkgatePin(root) {
   const pkgPath = path.join(root, 'package.json');
   if (!fs.existsSync(pkgPath)) return null;
   try {
@@ -278,7 +302,7 @@ export function readDeclaredArkgatePin(root) {
  * Consumers never match: they depend on arkgate; they are not named arkgate with bin/.
  * @param {string} root
  */
-export function isArkgateSelfHostRoot(root) {
+function isArkgateSelfHostRoot(root) {
   try {
     const pkgPath = path.join(root, 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

package/bin/lib/first-run-help.mjs

@@ -111,16 +111,16 @@ Non-interactive (no TTY): uses the same defaults as --yes — never calls readli
 }
 
 /** `--sensors` is contract + coverage-evidence only — never a full-check pass. */
-export const SENSORS_PARTIAL_MODE_LINE =
+const SENSORS_PARTIAL_MODE_LINE =
   'Contract + coverage-evidence only: no TypeScript, no analysis. Not a validity verdict.';
 
-export const SENSORS_DID_NOT_RUN = Object.freeze(['TypeScript', 'analysis']);
+const SENSORS_DID_NOT_RUN = Object.freeze(['TypeScript', 'analysis']);
 
 /**
  * Stamp a successful `--sensors --json` payload so agents cannot read exit 0 as
  * a full-check pass. Failure payloads (`sensors.ok === false`) stay untouched.
  */
-export function stampSensorsPartialModePayload(payload) {
+function stampSensorsPartialModePayload(payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
   const sensors = payload.sensors;
   if (!sensors || typeof sensors !== 'object' || Array.isArray(sensors)) return payload;
@@ -212,6 +212,10 @@ export function checkUsageAll() {
     '           what enforcing would cost: the findings each advisory rule already produces, from ONE run rather than one run per attempt.',
     '           Plan by default; --promote <ruleId> --apply (or --promote=<ruleId>) writes mode "enforced" into the ArkRules file that declares it.',
     '           A cost the run could not measure (incomplete analysis, classification floor) is named and --apply refuses. Exit 0 / 1 refused / 2 bad args.',
+    '       ark-check --probe-invariants[=<id>] [--write] [--json] [--runner vitest|jest|node]',
+    '           breaks each invariant\'s coverage.symbol on purpose (at most 3 small changes) in a temporary copy and runs only its covering tests',
+    '           with your own runner. Not a score; never part of a check. --write saves .ark/invariant-probe.json: a fresh survived or',
+    '           not-reached row refuses promotion. Your files are never changed. Exit 0 caught / 1 survived or not reached / 2 could not run.',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
     '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',

package/bin/lib/flat-parent-importers.mjs

@@ -1,13 +1,14 @@
 /**
  * Importer graph for the flat-parent doctor suggestion.
  *
- * Prefers the resolved dependency facts ark-check already built (tsconfig
- * paths included). Without facts it scans the text and resolves relative
+ * Prefers the importer index the scan projected from resolved facts (ADR 0037),
+ * then raw resolved dependency facts (tsconfig paths included). Without either it scans the text and resolves relative
  * specifiers plus tsconfig path aliases, so an `@/…` importer is never
  * invisible. Advisory input only.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { importerGraphFromIndex } from './import-graph-projection.mjs';
 import { readTsconfigAliases, resolveSpecifierToRel } from './import-resolve.mjs';
 
 const SPEC_MARKS = [' from "', " from '", ' from `', 'require("', "require('", 'import("', "import('"];
@@ -36,7 +37,7 @@ function withoutComments(text) {
 }
 
 /** Every string module specifier in `text` (relative and bare). */
-export function moduleSpecifiers(text) {
+function moduleSpecifiers(text) {
   const specs = [];
   const source = withoutComments(String(text));
   let i = 0;
@@ -112,6 +113,7 @@ function addEdge(graph, target, importer) {
  * @param {{ root: string, files: string[], facts?: object, ts?: object }} input
  */
 export function flatParentImporterGraph({ root, files, facts, ts }) {
+  if (facts?.importGraph) return importerGraphFromIndex(facts.importGraph);
   const graph = new Map();
   const fileSet = new Set(files);
   const dependencies = Array.isArray(facts?.dependencies) ? facts.dependencies : null;