arkgate 4.8.22 → 4.8.24

package/bin/lib/prepare-change.mjs

@@ -3,17 +3,31 @@ import path from 'node:path';
 import {
   loadArchitectureChangeMap,
   loadContract,
-  preflightResolvedChange,
+  preflightTrustedResolvedChange,
 } from './analysis-engine.mjs';
 import { createAdapterResult } from './adapter-contract.mjs';
 import { isGovernableSourceFile } from './scan-files.mjs';
 import {
   canonicalizeCandidateChanges,
+  createResolverIngestCache,
   resolveCandidateFacts,
 } from './resolved-candidate-facts.mjs';
 import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { isScanExcludedRelative } from '../ark-shared.mjs';
 import { classifyChangeSet, evaluateTeamGate } from './team-parliament.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import {
+  coverageOptionsFromConfig,
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
+import { catalogHasEnforcedInvariant } from './invariant-coverage.mjs';
+import {
+  declaredCoverageRootsPresent,
+  declaredInvariantTestsPathPresent,
+  scanDemandsInvariantTestsPath,
+} from './invariant-tests-path.mjs';
+import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
 
 function candidatePath(value) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -88,6 +102,73 @@ export function normalizeChangeSet(input) {
   });
 }
 
+function overlayContents(contents, overlay) {
+  const out = { ...(contents ?? {}) };
+  for (const change of overlay) {
+    if (change.delete === true) delete out[change.path];
+    else out[change.path] = change.content;
+  }
+  return out;
+}
+
+/**
+ * ArkRules engine inputs for base (disk) and candidate (disk + in-memory overlay):
+ * invariant coverage contents and structural file hints, loaded exactly the way
+ * architecture-scan loads them for ark-check. Undefined when ArkRules is off.
+ */
+function arkRulesAnalysisInputs({ root, config, arkRules, baseFacts, candidateFacts, overlay }) {
+  const structure = arkRules?.structure ?? [];
+  const invariants = arkRules?.invariants ?? [];
+  if (structure.length === 0 && invariants.length === 0) return {};
+  const adopted = scanDemandsInvariantTestsPath(root, {});
+  const shared = {
+    ...(adopted ? { adopted: true } : {}),
+    ...(adopted && declaredInvariantTestsPathPresent(root, config.coverage) === false
+      ? { invariantTestsPathPresent: false }
+      : {}),
+    ...(catalogHasEnforcedInvariant(invariants) &&
+    declaredCoverageRootsPresent(root, config.coverage) === false
+      ? { coverageRootsPresent: false }
+      : {}),
+  };
+  const baseCoverage =
+    invariants.length > 0
+      ? loadInvariantCoverageInputs(root, baseFacts, {
+          invariantIds: invariantIdsFromCatalog(arkRules),
+          ...coverageOptionsFromConfig(config),
+        })
+      : undefined;
+  const candidateCoverage = baseCoverage
+    ? {
+        ...baseCoverage,
+        fileContents: overlayContents(baseCoverage.fileContents, overlay),
+        testFiles: (baseCoverage.testFiles ?? []).filter(
+          (file) => !overlay.some((change) => change.delete === true && change.path === file)
+        ),
+      }
+    : undefined;
+  const baseHints = loadArkRuleFileHints(root, baseFacts, arkRules, baseCoverage?.fileContents);
+  // Candidate hints must read the overlay, never the stale on-disk text of a changed file.
+  const candidateHints = loadArkRuleFileHints(
+    root,
+    candidateFacts,
+    arkRules,
+    overlayContents(candidateCoverage?.fileContents ?? {}, overlay)
+  );
+  return {
+    baseAnalysisInputs: {
+      ...shared,
+      ...(baseCoverage ? { coverageInputs: baseCoverage } : {}),
+      ...(baseHints ? { fileHints: baseHints } : {}),
+    },
+    candidateAnalysisInputs: {
+      ...shared,
+      ...(candidateCoverage ? { coverageInputs: candidateCoverage } : {}),
+      ...(candidateHints ? { fileHints: candidateHints } : {}),
+    },
+  };
+}
+
 export function prepareChangeFromRoot({
   root,
   config,
@@ -115,10 +196,22 @@ export function prepareChangeFromRoot({
   for (const change of normalizedChanges) {
     assertInsideProject(root, change.path);
   }
-  const contract = loadContract(
-    effectiveConfig,
-    configSource ?? path.join(root, 'ark.config.json')
-  );
+  const contractSource = configSource ?? path.join(root, 'ark.config.json');
+  // Same Effective Contract as ark-check: ArkRules ride policyHash and the verdict,
+  // and a broken reference fails closed instead of silently dropping the catalog.
+  const arkRulesLoad = loadEffectiveArkRulesFromDisk(root, effectiveConfig);
+  if (arkRulesLoad.errors.length > 0) {
+    const message = arkRulesLoad.errors
+      .map((issue) => (typeof issue === 'string' ? issue : `- ${issue.path}: ${issue.message}`))
+      .join('\n');
+    const error = new Error(`Invalid Effective Contract (${contractSource}):\n${message}`);
+    error.code = 'ARKRULES_LOAD_FAILED';
+    error.issues = arkRulesLoad.errors;
+    throw error;
+  }
+  const contract = loadContract(effectiveConfig, contractSource, {
+    arkRules: arkRulesLoad.arkRules,
+  });
   const loadedChangeMap =
     changeMap === undefined
       ? undefined
@@ -129,24 +222,45 @@ export function prepareChangeFromRoot({
     changes: normalizedChanges,
   });
   for (const change of canonicalChanges) assertGovernedSource(effectiveConfig, change.path);
+  // Files the overlay does not touch are parsed once for both trees.
+  const ingestCache = createResolverIngestCache(contract.config);
   const baseFacts = resolveCandidateFacts({
     root,
     config: contract.config,
     ts,
+    ingestCache,
     ...(tsconfig ? { tsconfig } : {}),
   });
   const candidateFacts = resolveCandidateFacts({
     root,
     config: contract.config,
     ts,
+    ingestCache,
     changes: normalizedOverlayChanges,
     ...(tsconfig ? { tsconfig } : {}),
   });
-  const result = preflightResolvedChange({
+  ingestCache.records.clear();
+  const { baseAnalysisInputs, candidateAnalysisInputs } = arkRulesAnalysisInputs({
+    root,
+    config: effectiveConfig,
+    arkRules: arkRulesLoad.arkRules,
+    baseFacts,
+    candidateFacts,
+    overlay: canonicalizeCandidateChanges({
+      root,
+      config: contract.config,
+      changes: normalizedOverlayChanges,
+    }),
+  });
+  // Both fact sets were created (validated, frozen) by this bundle instance just
+  // above: skip re-validating two whole-project copies of each.
+  const result = preflightTrustedResolvedChange({
     contract,
     baseFacts,
     candidateFacts,
     changes: canonicalChanges,
+    ...(baseAnalysisInputs ? { baseAnalysisInputs } : {}),
+    ...(candidateAnalysisInputs ? { candidateAnalysisInputs } : {}),
     ...(loadedChangeMap ? { changeMap: loadedChangeMap } : {}),
   });
   const completeness =

package/bin/lib/prepare-write.mjs

@@ -41,6 +41,7 @@ export function buildJudgmentBrief(violations) {
       targetTypeOnlyExports: v.targetTypeOnlyExports,
       namedBindingsTypeOnly: v.namedBindingsTypeOnly,
       peerIsolation: v.peerIsolation ?? v.details?.peerIsolation,
+      reasonId: v.reasonId ?? v.details?.reasonId,
       edgeKind: v.edgeKind ?? v.details?.importKind,
       fromLayer: v.fromLayer,
       toLayer: v.toLayer,

package/bin/lib/presets.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   applyFrameworkLayoutOverlays,
+  cloneArchetypeForLayer,
   createElevenLayerConfig,
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   discoverRepoUnits,
@@ -371,11 +372,8 @@ export function buildArkRulesTemplateForLayer(layerName, role = resolveLayerSens
     const sourcePath = path.join(ARKRULES_TEMPLATES_DIR, archetype);
     if (fs.existsSync(sourcePath)) {
       try {
-        const parsed = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
-        return {
-          ...parsed,
-          layer: layerName,
-        };
+        // Unique ids across arkrules/*.json so `--promote <id> --apply` works on the starter.
+        return cloneArchetypeForLayer(JSON.parse(fs.readFileSync(sourcePath, 'utf8')), layerName);
       } catch {
         // Fall through to generic mold.
       }

package/bin/lib/remediation.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/remediation.mjs). Zero Node I/O.
  */
 
+import { sliceReasonHint } from './diagnostic-catalog.mjs';
 export const REMEDIATION_CLASSES = [
     'mechanical-safe',
     'judgment',
@@ -67,7 +68,15 @@ export function classifyLayerImportKind(target, extra) {
         return 'unknown';
     return 'unknown';
 }
+/** The reason's fix, plus its advisory note only when this finding is a warning. */
+function sliceHintAction(hint, violation) {
+    return violation.failsStrict === false && hint.advisoryNote ? `${hint.fix} ${hint.advisoryNote}` : hint.fix;
+}
 export function layerImportNextAction(violation) {
+    // A nested-wall reason has its own fix. It wins over the generic peer text.
+    const hint = sliceReasonHint(typeof violation.reasonId === 'string' ? violation.reasonId : undefined);
+    if (hint)
+        return `${sliceHintAction(hint, violation)} Then preflight again.`;
     if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
         return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
     }
@@ -198,6 +207,11 @@ export function deterministicNextAction(violation) {
     switch (violation.ruleId) {
         case 'LAYER_IMPORT_VIOLATION':
             return layerImportNextAction(violation);
+        case 'CONFIG_CHILD_SLICES_VERSION':
+            // The finding already names the pinned file and the version to bump to.
+            return typeof violation.nextAction === 'string' && violation.nextAction.length > 0
+                ? violation.nextAction
+                : 'Bump the pinned arkgate named in the finding to the version it gives, then run Ark again.';
         case 'FORBIDDEN_GLOBAL':
             return `Inject ${violation.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
         case 'CAPABILITY_VIOLATION':
@@ -423,11 +437,13 @@ export function enrichViolationWithFixClass(violation) {
                         ? 'The imported module only exports types — use `import type` and place the type in a layer both sides may share.'
                         : 'This is a type-only import — move the type to a layer both sides may share, or relocate the file to match its role.';
             }
-            else if (violation.peerIsolation) {
+            else if (violation.peerIsolation || sliceReasonHint(violation.reasonId)) {
+                const hint = sliceReasonHint(violation.reasonId);
                 enriched.fixClass = 'cross-slice-boundary';
                 enriched.effort = 'medium';
-                enriched.enthusiastHint =
-                    'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
+                enriched.enthusiastHint = hint
+                    ? `${hint.why} ${sliceHintAction(hint, violation)}`
+                    : 'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
             }
             else {
                 const kind = classifyLayerImportKind(typeof violation.target === 'string' ? violation.target : '', {
@@ -539,6 +555,7 @@ export function enrichViolationWithFixClass(violation) {
         case 'ARKORDER_XI_TTL':
         case 'ARKORDER_STALE_SIGMA':
         case 'ARKORDER_UNVALVED_RELEASE':
+        case 'ARKORDER_STALE_PROPOSAL':
             enriched.fixClass = 'arkorder-usage';
             enriched.effort = 'medium';
             enriched.enthusiastHint =
@@ -560,7 +577,9 @@ export function enrichViolationWithFixClass(violation) {
                                                 ? 'Refresh σ. ξ does not expire.'
                                                 : violation.ruleId === 'ARKORDER_UNVALVED_RELEASE'
                                                     ? 'The choice is already frozen. proposeRelease then apply — do not call release() again with a different value.'
-                                                    : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
+                                                    : violation.ruleId === 'ARKORDER_STALE_PROPOSAL'
+                                                        ? 'That proposal was computed against an older pattern. Propose again, review the new blast radius, then apply.'
+                                                        : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
             break;
         default:
             enriched.fixClass = 'review-contract';