arkgate 4.8.15 → 4.8.17

package/bin/lib/prototype-shortcuts.mjs

@@ -0,0 +1,224 @@
+/**
+ * Soft prototype-shortcut residual (P2 §3 / Guiar).
+ * Tooling I/O. Never a gate fail.
+ *
+ * SQLite / JSON-file stores standing in for a declared Persistence home,
+ * and admin / god-mode literals sitting outside Domain or an auth tag.
+ * Silent when the contract does not imply those houses, the shortcut is
+ * already in the right house, or the tree has no such markers.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { layerForFile } from '../ark-shared.mjs';
+import { isDomainRoleLayerName } from './arkrules-sensors.mjs';
+import { isNonProductionPilotPath } from './design-smells.mjs';
+
+export const PROTOTYPE_KIND = Object.freeze({
+  SQLITE: 'sqlite',
+  JSON_FILE: 'json-file',
+  ADMIN: 'admin-literals',
+});
+
+export const PROTOTYPE_SQLITE_ASK =
+  'SQLite is the standing store, and it is not in Persistence.';
+
+export const PROTOTYPE_JSON_ASK =
+  'A JSON file is standing in for Persistence.';
+
+export const PROTOTYPE_ADMIN_ASK =
+  'Admin / god-mode literals sit outside Domain (or an auth tag).';
+
+export const PROTOTYPE_PACK_ASK =
+  'Prototype shortcuts are still standing in for Persistence or Domain policy.';
+
+export const PROTOTYPE_PERSISTENCE_NEXT =
+  'Create a Persistence adapter (/ark-place), then move the file store behind it (/ark-autopilot). Do not harden the shortcut.';
+
+export const PROTOTYPE_ADMIN_NEXT =
+  'Move admin / god-mode literals behind Domain or an auth tag (/ark-place). Then one small refactor with /ark-autopilot.';
+
+export const PROTOTYPE_PACK_NEXT =
+  'Create a Persistence adapter (/ark-place) for the file store, and move admin literals behind Domain or an auth tag. Then one small refactor with /ark-autopilot.';
+
+const SOURCE_EXT = /\.(?:ts|tsx|js|jsx|mts|cts)$/;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_SCAN_FILES = 800;
+
+const SQLITE_IMPORT_RE =
+  /\b(?:from|require\()\s*['"](?:better-sqlite3|sqlite3|sql\.js|bun:sqlite|node:sqlite)['"]/;
+
+const JSON_DB_IMPORT_RE = /\b(?:from|require\()\s*['"](?:lowdb|node-json-db)['"]/;
+
+const JSON_DB_PATH_RE =
+  /['"`](?:[^'"`]*[\\/])?(?:db|database|store|data-store|dump)\.json['"`]/i;
+
+const FS_OR_JSON_RE = /\b(?:readFile|writeFile|readFileSync|writeFileSync|JSON\.parse|JSON\.stringify)\b/;
+
+const PRIVILEGE_LITERAL_RE =
+  /['"](?:admin|superadmin|super-admin|superuser|god|god-mode|godmode)['"]/i;
+
+const PRIVILEGE_CONTEXT_RE =
+  /\b(?:role|roles|privilege|permission|permissions|acl|isAdmin|isSuperuser|godMode|GOD_MODE)\b/;
+
+const HARDCODED_ADMIN_RE = /\bisAdmin\s*=\s*true\b/;
+
+const GOD_IDENT_RE = /\b(?:isGodMode|godMode|GOD_MODE|isSuperuser)\b/;
+
+/** Persistence-role house by name. Align with design-smells persistence heuristic. */
+export function isPersistenceRoleLayerName(name) {
+  return typeof name === 'string' && /persist|repository|data.?access/i.test(name);
+}
+
+function configLayers(input) {
+  return Array.isArray(input.config?.layers) ? input.config.layers : [];
+}
+
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, ' ');
+}
+
+function readTextLimited(absPath) {
+  try {
+    const st = fs.statSync(absPath);
+    if (!st.isFile() || st.size === 0 || st.size > MAX_FILE_BYTES) return null;
+    return fs.readFileSync(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRel(root, filePath) {
+  const abs = path.isAbsolute(filePath) ? filePath : path.join(root, filePath);
+  let rel = path.relative(root, abs).split(path.sep).join('/');
+  if (rel.startsWith('./')) rel = rel.slice(2);
+  return { abs, rel };
+}
+
+function hasSqliteShortcut(source) {
+  return SQLITE_IMPORT_RE.test(source);
+}
+
+function hasJsonFileShortcut(source) {
+  if (JSON_DB_IMPORT_RE.test(source)) return true;
+  return JSON_DB_PATH_RE.test(source) && FS_OR_JSON_RE.test(source);
+}
+
+function hasAdminLiteral(source) {
+  if (HARDCODED_ADMIN_RE.test(source) || GOD_IDENT_RE.test(source)) return true;
+  return PRIVILEGE_LITERAL_RE.test(source) && PRIVILEGE_CONTEXT_RE.test(source);
+}
+
+function layerNameFor(root, rel, config) {
+  try {
+    return layerForFile(root, rel, config?.layers ?? []) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function layerByName(config, name) {
+  return configLayers({ config }).find((layer) => layer.name === name) ?? null;
+}
+
+function isTrustPolicyLayer(layer) {
+  const tag = layer?.trustBoundary;
+  return tag === 'auth' || tag === 'admin';
+}
+
+function composeAsk(kinds) {
+  if (kinds.length === 1) {
+    if (kinds[0] === PROTOTYPE_KIND.SQLITE) return PROTOTYPE_SQLITE_ASK;
+    if (kinds[0] === PROTOTYPE_KIND.JSON_FILE) return PROTOTYPE_JSON_ASK;
+    return PROTOTYPE_ADMIN_ASK;
+  }
+  return PROTOTYPE_PACK_ASK;
+}
+
+function composeNext(kinds) {
+  const persist = kinds.includes(PROTOTYPE_KIND.SQLITE) || kinds.includes(PROTOTYPE_KIND.JSON_FILE);
+  const admin = kinds.includes(PROTOTYPE_KIND.ADMIN);
+  if (persist && admin) return PROTOTYPE_PACK_NEXT;
+  if (admin) return PROTOTYPE_ADMIN_NEXT;
+  return PROTOTYPE_PERSISTENCE_NEXT;
+}
+
+/**
+ * Soft residual when prototype stores or privilege literals are standing in
+ * for a declared Persistence / Domain (or auth) house. Never flips valid.
+ *
+ * @param {{ root?: string, config?: object, coverage?: object, files?: readonly string[] }} [input]
+ * @returns {{ kinds: string[], ask: string, nextAction: string, evidence: string[], persistenceLayers: string[], domainLayers: string[] } | null}
+ */
+export function collectPrototypeShortcutsResidual(input = {}) {
+  const declared = configLayers(input);
+  const persistenceLayers = declared.filter((layer) => isPersistenceRoleLayerName(layer.name));
+  const domainLayers = declared.filter((layer) =>
+    isDomainRoleLayerName(layer.name, layer.intentPrefixes ?? [])
+  );
+  const trustPolicyLayers = declared.filter((layer) => isTrustPolicyLayer(layer));
+  const persistEligible = persistenceLayers.length > 0;
+  const adminEligible = domainLayers.length > 0 || trustPolicyLayers.length > 0;
+  if (!persistEligible && !adminEligible) return null;
+
+  const root = typeof input.root === 'string' ? input.root : '';
+  const files = Array.isArray(input.files) ? input.files : [];
+  if (files.length === 0) return null;
+
+  const persistNames = new Set(persistenceLayers.map((layer) => layer.name));
+  const domainNames = new Set(domainLayers.map((layer) => layer.name));
+
+  const sqliteHits = [];
+  const jsonHits = [];
+  const adminHits = [];
+  let scanned = 0;
+
+  for (const file of files) {
+    if (scanned >= MAX_SCAN_FILES) break;
+    const { abs, rel } = normalizeRel(root, file);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!SOURCE_EXT.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    if (isNonProductionPilotPath(rel)) continue;
+    const source = readTextLimited(abs);
+    if (source == null) continue;
+    scanned += 1;
+    const code = stripComments(source);
+    const layer = layerNameFor(root, rel, input.config);
+    const inPersistence = Boolean(layer && persistNames.has(layer));
+    const policyHome =
+      Boolean(layer && domainNames.has(layer)) || isTrustPolicyLayer(layerByName(input.config, layer));
+
+    if (persistEligible && !inPersistence) {
+      if (hasSqliteShortcut(code)) sqliteHits.push(rel);
+      if (hasJsonFileShortcut(code)) jsonHits.push(rel);
+    }
+    if (adminEligible && !policyHome && hasAdminLiteral(code)) adminHits.push(rel);
+  }
+
+  const kinds = [];
+  const evidence = [];
+  if (persistEligible && sqliteHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.SQLITE);
+    evidence.push(...sqliteHits);
+  }
+  if (persistEligible && jsonHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.JSON_FILE);
+    evidence.push(...jsonHits);
+  }
+  if (adminEligible && adminHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.ADMIN);
+    evidence.push(...adminHits);
+  }
+  if (kinds.length === 0) return null;
+
+  const uniqueEvidence = [...new Set(evidence)].slice(0, 12);
+  return {
+    kinds,
+    ask: composeAsk(kinds),
+    nextAction: composeNext(kinds),
+    evidence: uniqueEvidence,
+    persistenceLayers: persistenceLayers.map((layer) => layer.name),
+    domainLayers: domainLayers.map((layer) => layer.name),
+  };
+}

package/bin/lib/remediation.mjs

@@ -220,6 +220,10 @@ export function deterministicNextAction(violation) {
             return typeof violation.file === 'string' && violation.file.length > 0
                 ? `Add 1–2 short phrases to invariants[] in ${violation.file}, then run ark-check --doctor. Starters show the shape.`
                 : 'Add 1–2 short phrases to invariants[] in arkrules/<Domain>.json, then run ark-check --doctor. Starters show the shape.';
+        case 'INVARIANT_TESTS_PATH_MISSING':
+            return 'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run. Adopted mode fails closed until that path is present.';
+        case 'INVARIANT_COVERAGE_ROOTS_MISSING':
+            return 'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run. An enforced invariant fails closed until that path is present.';
         case 'ARKRULE_STRUCTURE':
         case 'ARKRULE_INVARIANT':
         case 'INVARIANT_UNCOVERED':
@@ -364,6 +368,7 @@ export function classifyRemediation(violation) {
         ruleId === 'ARKRULE_INVARIANT' ||
         ruleId === 'INVARIANT_UNCOVERED' ||
         ruleId === 'INVARIANT_COVERAGE_OUTSIDE_ROOTS' ||
+        ruleId === 'INVARIANT_COVERAGE_ROOTS_MISSING' ||
         (typeof ruleId === 'string' && ruleId.startsWith('ARKRULE_'))) {
         return {
             class: 'judgment',
@@ -494,6 +499,12 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'The covering test lives where the project says its runner does not go. Move it, or declare that root in coverage.coverageRoots.';
             break;
+        case 'INVARIANT_COVERAGE_ROOTS_MISSING':
+            enriched.fixClass = 'review-contract';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'An invariant is enforced, but the project never said where tests run. Add coverage.coverageRoots so coverage cannot tick a test no runner uses.';
+            break;
         case 'ARKRULE_STRUCTURE':
         case 'ARKRULE_INVARIANT':
         case 'INVARIANT_UNCOVERED':

package/bin/lib/start-preview.mjs

@@ -3,7 +3,12 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { arkCommand, buildArchitectureRecommendation, START_APPLY_REFUSE_FOOTER } from '../ark-shared.mjs';
+import {
+  arkCommand,
+  arkPackageRecoveryCommand,
+  buildArchitectureRecommendation,
+  START_APPLY_REFUSE_FOOTER,
+} from '../ark-shared.mjs';
 import { withProjectedGovernedCoverage } from './projected-governed-coverage.mjs';
 import { ARKORDER_FIRST_CONTACT_NEXT, ARKORDER_ONE_BREATH } from './ark-order-doctor.mjs';
 import { compactAgentInstructions, instructionRule, mcpJson } from './ci-and-commands.mjs';
@@ -135,6 +140,20 @@ function commands(root, args, helpers) {
   return result;
 }
 
+/**
+ * Red next-step when post-apply package install fails.
+ * Host files may already be written; local bins may be missing.
+ */
+export function formatStartPackageInstallFailure({ exitStatus, installCommand }) {
+  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
+  return [
+    `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`,
+    `  ${installCommand}`,
+    `  ${doctor}`,
+    '`arkgate-check` is a command in the arkgate package — not its own npm package.',
+  ].join('\n');
+}
+
 /**
  * @param {object} preview
  * @param {{ applying?: boolean }} [options] when applying=true, do not claim “no files were changed”

package/dist/{configTypes-Dt3DpVbd.d.ts → configTypes-VD0qcubY.d.ts}

@@ -85,7 +85,8 @@ type ArkConfigCoverage = {
      * tests. ArkGate never runs anything: this is a second declaration to compare
      * the coverage scan against, so a covering test found outside them is reported
      * (INVARIANT_COVERAGE_OUTSIDE_ROOTS) instead of silently certifying the
-     * invariant. Absence means no declaration and no such claim.
+     * invariant. Absence is silent unless any catalogued invariant is enforced —
+     * then missing roots fail closed (INVARIANT_COVERAGE_ROOTS_MISSING).
      */
     coverageRoots?: string[];
 };

package/dist/{diagnosticCatalog-BEg85XlE.d.ts → diagnosticCatalog-DVABouBV.d.ts}

@@ -1,5 +1,5 @@
-import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-CN9tVMPz.js';
-import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-Dt3DpVbd.js';
+import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-D5GT5ZT8.js';
+import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-VD0qcubY.js';
 
 /** Versioned public result contract types + JSON Schema (adapter envelope). */
 /**
@@ -392,7 +392,7 @@ declare function createAdapterResult(input: {
 }): CurrentAdapterResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.15";
+declare const version = "4.8.17";
 
 /**
  * AI Code Gate (basic).
@@ -1746,6 +1746,12 @@ type InvariantCoverageEvidence = {
      * there is nothing to compare against, and silence is honest.
      */
     outsideDeclaredRoots?: boolean;
+    /**
+     * True when `coverage.coverageRoots` was non-empty for this evaluation.
+     * `false` when the project declared nothing. Omitted on hand-built evidence
+     * so existing promote fixtures stay valid; the evaluator always sets it.
+     */
+    coverageRootsDeclared?: boolean;
 };
 type InvariantUncoveredKind = 'never-had-tests' | 'tests-disappeared';
 type InvariantCoverageRuleId = 'INVARIANT_UNCOVERED' | 'INVARIANT_COVERAGE_OUTSIDE_ROOTS';
@@ -1965,6 +1971,12 @@ type PolicyDeltaAcknowledgement = {
     candidatePolicyHash: string;
     findingIds: readonly string[];
     reason: string;
+    /**
+     * Relative decision-note path under a conventional home (`docs/adr/`,
+     * `docs/decisions/`, or the AP01 single-file homes). Tooling checks the file.
+     * Hash matching does not require it.
+     */
+    adrPath?: string;
 };
 type ClassifyArkPolicyDeltaOptions = {
     baseArkRules?: EffectiveArkRules;
@@ -2015,6 +2027,21 @@ type AnalysisResult = {
 type AnalyzeResolvedProjectInput = {
     contract: AnalysisContract;
     facts: unknown;
+    /**
+     * D0 adopted or --require-gates / --strict-merge. When true, a missing
+     * domain-invariant tests path fails closed. Omitted stays silent.
+     */
+    adopted?: boolean;
+    /**
+     * Tooling FS check for the declared tests path. `false` means empty on disk.
+     * Omitted: a non-empty config declaration is enough.
+     */
+    invariantTestsPathPresent?: boolean;
+    /**
+     * Tooling FS check for declared `coverage.coverageRoots`. `false` means
+     * missing or empty on disk. Omitted: a non-empty config declaration is enough.
+     */
+    coverageRootsPresent?: boolean;
     /**
      * AR10 — Tooling-supplied contents for invariant coverage evidence.
      * When omitted and the Effective Contract has invariants, coverage is partial