arkgate 4.8.0 → 4.8.2

package/bin/lib/architecture-scan.mjs

@@ -11,7 +11,10 @@ import {
 import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { resolveCandidateFacts } from './resolved-candidate-facts.mjs';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
-import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
 import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
 
 /** Resolve canonical facts and optionally retain filesystem probes for resident invalidation. */
@@ -67,7 +70,9 @@ export function resolveArchitectureSnapshot({
   });
   const hasInvariants = (arkRulesLoad.arkRules?.invariants?.length ?? 0) > 0;
   const coverageInputs = hasInvariants
-    ? loadInvariantCoverageInputs(root, facts)
+    ? loadInvariantCoverageInputs(root, facts, {
+        invariantIds: invariantIdsFromCatalog(arkRulesLoad.arkRules),
+      })
     : undefined;
   // AR07: Tooling fileHints for orchestration-only / thin-adapter (reuse coverage contents when present).
   const fileHints = loadArkRuleFileHints(

package/bin/lib/invariant-coverage-io.mjs

@@ -62,16 +62,42 @@ function matchSimpleGlob(glob, file) {
   return new RegExp(`^${out}$`).test(target);
 }
 
+/**
+ * Declared invariant ids from an Effective catalog. Empty when the extra is off.
+ * @param {{ invariants?: Array<{ id?: unknown }> } | null | undefined} arkRules
+ * @returns {string[]}
+ */
+export function invariantIdsFromCatalog(arkRules) {
+  return (arkRules?.invariants ?? [])
+    .map((inv) => inv?.id)
+    .filter((id) => typeof id === 'string' && id.length > 0);
+}
+
 /**
  * @param {string} root
  * @param {{ files?: Array<{ path: string }> }} facts
- * @param {{ testGlobs?: string[] }} [opts]
- * @returns {{ fileContents: Record<string, string>, testFiles: string[], testGlobsMissing: boolean }}
+ * @param {{ testGlobs?: string[], invariantIds?: string[] }} [opts]
+ * @returns {{
+ *   fileContents: Record<string, string>,
+ *   testFiles: string[],
+ *   testGlobsMissing: boolean,
+ *   coverageBudgetExhausted: boolean,
+ * }}
  */
 export function loadInvariantCoverageInputs(root, facts, opts = {}) {
   const fileContents = {};
   const testFiles = [];
   const seen = new Set();
+  // Declared invariant ids. When present, a test file is RETAINED only if it
+  // mentions one: scanning is cheap (hundreds of small files), retaining is
+  // what costs memory. Without this the budget goes to whichever N tests the
+  // walk reaches first — an arbitrary order — so coverage is wrong on any repo
+  // with more test files than budget. Measured: 707 tests against a cap of 400.
+  const invariantIds = Array.isArray(opts.invariantIds)
+    ? opts.invariantIds.filter((id) => typeof id === 'string' && id.length > 0)
+    : [];
+  const mentionsInvariant = (content) =>
+    invariantIds.length === 0 || invariantIds.some((id) => content.includes(id));
   const testGlobs = Array.isArray(opts.testGlobs)
     ? opts.testGlobs.filter((g) => typeof g === 'string' && g.length > 0)
     : [];
@@ -93,40 +119,51 @@ export function loadInvariantCoverageInputs(root, facts, opts = {}) {
       const stat = fs.statSync(absolute);
       if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
       const content = fs.readFileSync(absolute, 'utf8');
+      const asTest = forceAsTest || isTestPath(rel);
+      // A test that names no invariant is evidence of nothing: scan it, drop
+      // it, and let it cost no budget.
+      if (asTest && !mentionsInvariant(content)) return;
       seen.add(rel);
       fileContents[rel] = content;
-      if (forceAsTest || isTestPath(rel)) testFiles.push(rel);
+      if (asTest) testFiles.push(rel);
     } catch {
       // skip unreadable
     }
   };
 
-  for (const file of facts?.files ?? []) {
-    if (file?.path) pushFile(file.path);
+  // Tests FIRST, then production files.
+  //
+  // The order is load-bearing, not stylistic. `pushFile` stops at
+  // MAX_COVERAGE_FILES, and a real repo has far more production files than the
+  // budget — so walking facts first consumed the whole budget and the test walk
+  // pushed nothing. Coverage then reported `testGlobsMissing: true`, which the
+  // caller renders as "never-had-tests": a claim about the USER's repo that was
+  // actually about our own budget. Measured on a 4511-file project: every
+  // invariant reported uncovered while its test sat on disk with the invariant
+  // id in the describe title. Tests are tens of files, not thousands, so giving
+  // them the head of the budget costs the production scan nothing in practice.
+  const testWalkRoots = useCustomGlobs
+    ? ['.', 'tests', 'test', 'src', '__tests__', 'spec']
+    : ['tests', 'test', 'src', '__tests__'];
+  for (const dir of testWalkRoots) {
+    const absDir = path.join(root, dir === '.' ? '' : dir);
+    if (!fs.existsSync(absDir)) continue;
+    walkTestFiles(absDir, root, (rel) => {
+      if (isTestPath(rel)) pushFile(rel, true);
+    });
   }
 
-  if (useCustomGlobs) {
-    // Walk project roots and keep files matching custom globs.
-    for (const dir of ['.', 'tests', 'test', 'src', '__tests__', 'spec']) {
-      const absDir = path.join(root, dir === '.' ? '' : dir);
-      if (!fs.existsSync(absDir)) continue;
-      walkTestFiles(absDir, root, (rel) => {
-        if (isTestPath(rel)) pushFile(rel, true);
-      });
-    }
-  } else {
-    // Walk common test roots when facts only cover production include globs.
-    for (const dir of ['tests', 'test', 'src', '__tests__']) {
-      const absDir = path.join(root, dir);
-      if (!fs.existsSync(absDir)) continue;
-      walkTestFiles(absDir, root, (rel) => {
-        if (isTestPath(rel)) pushFile(rel, true);
-      });
-    }
+  for (const file of facts?.files ?? []) {
+    if (file?.path) pushFile(file.path);
   }
 
   const testGlobsMissing = testFiles.length === 0;
-  return { fileContents, testFiles, testGlobsMissing };
+  return {
+    fileContents,
+    testFiles,
+    testGlobsMissing,
+    coverageBudgetExhausted: seen.size >= MAX_COVERAGE_FILES,
+  };
 }
 
 /**

package/bin/lib/invariant-coverage.mjs

@@ -38,6 +38,7 @@ export function evaluateInvariantCoverage(input) {
     }
     const testFiles = input.testFiles ?? [];
     const testGlobsMissing = input.testGlobsMissing === true || testFiles.length === 0;
+    const coverageBudgetExhausted = input.coverageBudgetExhausted === true;
     const coverage = [];
     const violations = [];
     for (const inv of invariants) {
@@ -83,7 +84,9 @@ export function evaluateInvariantCoverage(input) {
             violations.push({
                 ruleId: 'INVARIANT_UNCOVERED',
                 message: partial
-                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
+                    ? coverageBudgetExhausted
+                        ? `Invariant ${inv.id} coverage cannot be proven (coverage file budget exhausted); reporting partial, not covered.`
+                        : `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
                     : kind === 'tests-disappeared'
                         ? `Invariant ${inv.id} is not covered by a test title or declared symbol (tests-disappeared — suite exists).`
                         : `Invariant ${inv.id} is not covered by a test title or declared symbol (never-had-tests).`,

package/bin/lib/policy-delta-io.mjs

@@ -3,7 +3,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { analyzePolicyDelta } from './analysis-engine.mjs';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
-import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 
 function readJsonFile(filePath, label) {
@@ -175,12 +178,15 @@ export function analyzePolicyTransition({
 
   let candidateInvariantCoverage;
   if ((candidateArkRules?.invariants?.length ?? 0) > 0) {
-    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] });
+    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] }, {
+      invariantIds: invariantIdsFromCatalog(candidateArkRules),
+    });
     const evaluated = evaluateInvariantCoverage({
       arkRules: candidateArkRules,
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
+      coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     candidateInvariantCoverage = evaluated.coverage;
   }

package/bin/lib/rules-under-contract.mjs

@@ -6,7 +6,10 @@
  */
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
-import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
 import {
   EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
   composeMergePlanesHonesty,
@@ -89,13 +92,16 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const invariants = loaded.arkRules.invariants?.length ?? 0;
     const coverageInputs =
       invariants > 0
-        ? loadInvariantCoverageInputs(root, facts ?? { files: [] })
+        ? loadInvariantCoverageInputs(root, facts ?? { files: [] }, {
+            invariantIds: invariantIdsFromCatalog(loaded.arkRules),
+          })
         : { fileContents: {}, testFiles: [], testGlobsMissing: false };
     const coverage = evaluateInvariantCoverage({
       arkRules: loaded.arkRules,
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
+      coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     const covById = new Map(
       (coverage.coverage ?? []).map((row) => [row.invariantId, row])

package/dist/{diagnosticCatalog-RiKPUFRG.d.ts → diagnosticCatalog-CPzH-MLN.d.ts}

@@ -409,7 +409,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
 };
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.0";
+declare const version = "4.8.2";
 
 /**
  * AI Code Gate (basic).
@@ -1691,6 +1691,11 @@ type EvaluateInvariantCoverageInput = {
     testFiles?: readonly string[];
     /** When true, missing test files make coverage partial (never green covered). */
     testGlobsMissing?: boolean;
+    /**
+     * Tooling hit MAX_COVERAGE_FILES. Partial must not claim the repo never had tests —
+     * the suite may exist outside the scan budget.
+     */
+    coverageBudgetExhausted?: boolean;
 };
 declare function evaluateInvariantCoverage(input: EvaluateInvariantCoverageInput): {
     coverage: InvariantCoverageEvidence[];
@@ -1878,6 +1883,7 @@ type AnalyzeResolvedProjectInput = {
         fileContents: Readonly<Record<string, string>>;
         testFiles?: readonly string[];
         testGlobsMissing?: boolean;
+        coverageBudgetExhausted?: boolean;
     };
     /**
      * AR07 — Tooling-supplied orchestration/thin-adapter heuristics per file.