arkgate 3.0.5 → 3.2.0

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

@@ -0,0 +1,161 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { analyzePolicyDelta } from './analysis-engine.mjs';
+
+function readJsonFile(filePath, label) {
+  if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `${label} is not valid JSON (${filePath}): ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+function runGit(cwd, args) {
+  return spawnSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function safeRef(value) {
+  return (
+    typeof value === 'string' &&
+    /^[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/.test(value) &&
+    !value.includes('..')
+  );
+}
+
+export function normalizePolicyBaseRef(value) {
+  const ref = typeof value === 'string' ? value.trim() : '';
+  return /^0{40,64}$/.test(ref) ? '' : ref;
+}
+
+function repositoryRoot(root) {
+  const result = runGit(root, ['rev-parse', '--show-toplevel']);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function discoverLocalBaseRef(root) {
+  const top = repositoryRoot(root);
+  if (!top) return null;
+  const remoteHead = runGit(top, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  const candidates = [
+    remoteHead.status === 0 ? remoteHead.stdout.trim() : null,
+    'origin/main',
+    'origin/master',
+  ].filter(Boolean);
+  const current = runGit(top, ['branch', '--show-current']);
+  const currentBranch = current.status === 0 ? current.stdout.trim() : '';
+
+  for (const candidate of candidates) {
+    if (!safeRef(candidate)) continue;
+    const exists = runGit(top, ['rev-parse', '--verify', `${candidate}^{commit}`]);
+    if (exists.status !== 0) continue;
+    if (currentBranch && candidate === `origin/${currentBranch}`) return null;
+    const mergeBase = runGit(top, ['merge-base', 'HEAD', candidate]);
+    if (mergeBase.status === 0 && safeRef(mergeBase.stdout.trim())) return mergeBase.stdout.trim();
+  }
+  return null;
+}
+
+function configPathInRepository(root, configPath, top) {
+  const requested = path.isAbsolute(configPath) ? configPath : path.resolve(root, configPath);
+  const absolute = fs.realpathSync(requested);
+  const canonicalTop = fs.realpathSync(top);
+  const relative = path.relative(canonicalTop, absolute).split(path.sep).join('/');
+  if (!relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative)) {
+    throw new Error(`Policy config must be inside the Git repository: ${absolute}`);
+  }
+  return relative;
+}
+
+export function resolvePolicyBaseConfig({
+  root,
+  configPath,
+  basePath,
+  baseRef,
+  env = process.env,
+}) {
+  if (basePath) {
+    const absolute = path.isAbsolute(basePath) ? basePath : path.resolve(root, basePath);
+    return { config: readJsonFile(absolute, 'Policy base'), source: absolute, ref: null };
+  }
+
+  const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
+  const githubBase = typeof env.GITHUB_BASE_REF === 'string' ? env.GITHUB_BASE_REF.trim() : '';
+  const requestedRef = baseRef || envRef || (githubBase ? `origin/${githubBase}` : '');
+  const ref = requestedRef || discoverLocalBaseRef(root);
+  if (!ref) return null;
+  if (!safeRef(ref)) throw new Error(`Unsafe policy base ref: ${ref}`);
+
+  const top = repositoryRoot(root);
+  if (!top) {
+    // GitHub and ARK_POLICY_BASE_REF describe the process workspace, which may
+    // be different from an explicitly checked nested/temporary project root.
+    // Only the CLI flag is an unambiguous request to resolve this exact root.
+    if (baseRef) throw new Error(`Cannot resolve policy base ref outside a Git repository: ${ref}`);
+    return null;
+  }
+  const relativeConfig = configPathInRepository(root, configPath, top);
+  const result = runGit(top, ['show', `${ref}:${relativeConfig}`]);
+  if (result.status !== 0) {
+    const refExists = runGit(top, ['rev-parse', '--verify', `${ref}^{commit}`]);
+    // A newly adopted contract has no predecessor to weaken. CI-provided and
+    // auto-discovered bases may therefore omit the config; an explicit CLI ref
+    // remains fail-closed because the caller asked to compare that exact input.
+    if (refExists.status === 0 && !baseRef) return null;
+    if (requestedRef) {
+      throw new Error(
+        `Cannot read policy base ${ref}:${relativeConfig}: ${result.stderr.trim() || 'git show failed'}`
+      );
+    }
+    return null;
+  }
+  try {
+    return {
+      config: JSON.parse(result.stdout),
+      source: `git:${ref}:${relativeConfig}`,
+      ref,
+    };
+  } catch (error) {
+    throw new Error(
+      `Policy base ${ref}:${relativeConfig} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+export function readPolicyAcknowledgement(root, acknowledgementPath) {
+  if (!acknowledgementPath) return undefined;
+  const absolute = path.isAbsolute(acknowledgementPath)
+    ? acknowledgementPath
+    : path.resolve(root, acknowledgementPath);
+  return readJsonFile(absolute, 'Policy acknowledgement');
+}
+
+export function analyzePolicyTransition({
+  root,
+  configPath,
+  candidateConfig,
+  strictMerge,
+  basePath,
+  baseRef,
+  acknowledgementPath,
+}) {
+  if (!strictMerge && !basePath && !baseRef && !acknowledgementPath) return undefined;
+  const base = resolvePolicyBaseConfig({ root, configPath, basePath, baseRef });
+  if (!base && (basePath || baseRef || acknowledgementPath)) {
+    throw new Error('Policy delta was requested but no policy base could be resolved.');
+  }
+  if (!base) return undefined;
+  return analyzePolicyDelta({
+    baseConfig: base.config,
+    candidateConfig,
+    acknowledgement: readPolicyAcknowledgement(root, acknowledgementPath),
+    baseSource: base.source,
+    candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
+  });
+}

package/bin/lib/prepare-change.mjs

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadArchitectureChangeMap, loadContract, preflightChange } from './analysis-engine.mjs';
+import { createAdapterResult } from './adapter-contract.mjs';
+import { collectGovernedFiles, isGovernableSourceFile, normalize } from './scan-files.mjs';
+import { isScanExcludedRelative, layerForRelativePath } from '../ark-shared.mjs';
+
+function candidatePath(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('Every change requires a non-empty project-relative path.');
+  }
+  const portable = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path.posix.isAbsolute(portable) || /^[A-Za-z]:\//.test(portable)) {
+    throw new Error(`Change path must be project-relative: ${value}`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.includes('\0')) {
+    throw new Error(`Change path escapes the project root: ${value}`);
+  }
+  return normalized;
+}
+
+function isIncluded(relativePath, include) {
+  return (include ?? []).some((entry) => {
+    const root = String(entry).replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+    return root === '.' || relativePath === root || relativePath.startsWith(`${root}/`);
+  });
+}
+
+function assertGovernedSource(config, relativePath) {
+  if (!isGovernableSourceFile(path.basename(relativePath))) {
+    throw new Error(`Atomic preflight only accepts governed production source files: ${relativePath}`);
+  }
+  if (!isIncluded(relativePath, config.include) || isScanExcludedRelative(relativePath, config)) {
+    throw new Error(`Change path is outside the configured source scope: ${relativePath}`);
+  }
+  if (!layerForRelativePath(relativePath, config.layers)) {
+    throw new Error(`Change path is not assigned to an architecture layer: ${relativePath}`);
+  }
+}
+
+function assertInsideProject(root, relativePath) {
+  const canonicalRoot = fs.realpathSync(root);
+  let existing = path.join(root, relativePath);
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    existing = parent;
+  }
+  const canonicalExisting = fs.realpathSync(existing);
+  const relative = path.relative(canonicalRoot, canonicalExisting);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Change path resolves outside the project root: ${relativePath}`);
+  }
+}
+
+export function normalizeChangeSet(input) {
+  if (!Array.isArray(input)) throw new Error('changes must be an array.');
+  return input.map((change, index) => {
+    if (!change || typeof change !== 'object' || Array.isArray(change)) {
+      throw new Error(`changes[${index}] must be an object.`);
+    }
+    const normalizedPath = candidatePath(change.path);
+    if (change.delete === true && change.content === undefined) {
+      return { path: normalizedPath, delete: true };
+    }
+    if (typeof change.content === 'string' && change.delete === undefined) {
+      return { path: normalizedPath, content: change.content };
+    }
+    throw new Error(
+      `changes[${index}] must contain either content (string) or delete: true, but not both.`
+    );
+  });
+}
+
+function baseFilesForChange(root, config, changes) {
+  const byPath = new Map(
+    collectGovernedFiles(root, config).map((absolute) => [
+      normalize(path.relative(root, absolute)),
+      { path: normalize(path.relative(root, absolute)), content: fs.readFileSync(absolute, 'utf8') },
+    ])
+  );
+  for (const change of changes) {
+    if (byPath.has(change.path) || !isGovernableSourceFile(path.basename(change.path))) continue;
+    const absolute = path.join(root, change.path);
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) continue;
+    byPath.set(change.path, { path: change.path, content: fs.readFileSync(absolute, 'utf8') });
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function prepareChangeFromRoot({
+  root,
+  config,
+  configSource,
+  changes,
+  changeMap,
+  changeMapSource,
+  compilerOptions,
+}) {
+  const normalizedChanges = normalizeChangeSet(changes);
+  for (const change of normalizedChanges) {
+    assertInsideProject(root, change.path);
+    assertGovernedSource(config, change.path);
+  }
+  const contract = loadContract(config, configSource ?? path.join(root, 'ark.config.json'));
+  const loadedChangeMap =
+    changeMap === undefined
+      ? undefined
+      : loadArchitectureChangeMap(changeMap, contract.config, changeMapSource);
+  const result = preflightChange({
+    contract,
+    files: baseFilesForChange(root, config, normalizedChanges),
+    changes: normalizedChanges,
+    ...(loadedChangeMap ? { changeMap: loadedChangeMap } : {}),
+    ...(compilerOptions ? { compilerOptions } : {}),
+  });
+  return {
+    ...createAdapterResult({
+      valid: result.valid,
+      violations: result.violations,
+      warnings: result.warnings,
+    }),
+    ...result,
+  };
+}
+
+export function renderChangePreflight(result) {
+  const convergence = result.convergence;
+  if (result.valid) {
+    console.log(`✔ Atomic preflight passed for ${result.changes.length} change(s).`);
+    console.log(`  candidate ${result.candidateTreeHash} · policy ${result.policyHash}`);
+  } else {
+    const structuralFindings = convergence
+      ? convergence.summary.missing + convergence.summary.contradictory + convergence.summary.unplanned
+      : 0;
+    console.error(
+      `Atomic preflight rejected ${result.violations.length + structuralFindings} finding(s):`
+    );
+    for (const finding of result.diagnostics.filter(({ severity }) => severity === 'error')) {
+      console.error(
+        `  - ${finding.ruleId} ${finding.location.file}:${finding.location.line} — ${finding.message}`
+      );
+      console.error(`    Next action: ${finding.nextAction}`);
+    }
+    for (const finding of convergence?.findings ?? []) {
+      if (finding.classification !== 'satisfied') {
+        console.error(`  - ${finding.id} — ${finding.message}`);
+        console.error(`    Next action: ${finding.nextAction}`);
+      }
+    }
+    console.error('No project file was written. Fix the complete change set and preflight again.');
+  }
+  if (convergence) {
+    const { satisfied, missing, contradictory, unplanned } = convergence.summary;
+    const write = convergence.structurallyConverged ? console.log : console.error;
+    write(
+      `Structural convergence: ${convergence.structurallyConverged ? 'passed' : 'failed'} · satisfied ${satisfied} · missing ${missing} · contradictory ${contradictory} · unplanned ${unplanned}.`
+    );
+    write('Behavioral completion: not evaluated; run the feature acceptance tests separately.');
+  }
+}
+
+export function readChangeSetFile(root, requestPath) {
+  const absolute = path.isAbsolute(requestPath) ? requestPath : path.join(root, requestPath);
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `Cannot read atomic change set ${absolute}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  return Array.isArray(parsed) ? parsed : parsed?.changes;
+}
+
+export function readChangeMapFile(root, requestPath) {
+  const absolute = path.isAbsolute(requestPath) ? requestPath : path.join(root, requestPath);
+  try {
+    return { source: absolute, input: JSON.parse(fs.readFileSync(absolute, 'utf8')) };
+  } catch (error) {
+    throw new Error(
+      `Cannot read architecture change map ${absolute}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}

package/bin/lib/remediation.mjs

@@ -41,6 +41,29 @@ export const KNOWN_FIX_CLASSES = [
     'break-cycle',
     'review-contract',
 ];
+/** One deterministic re-entry action shared by human and machine denial surfaces. */
+export function deterministicNextAction(violation) {
+    switch (violation.ruleId) {
+        case 'LAYER_IMPORT_VIOLATION':
+            if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
+                return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
+            }
+            if (violation.peerIsolation) {
+                return 'Extract the shared dependency to a shared layer, then preflight again.';
+            }
+            return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+        case 'FORBIDDEN_GLOBAL':
+            return `Inject ${violation.target ?? 'the capability'} through a port, then preflight again.`;
+        case 'CIRCULAR_DEPENDENCY':
+            return 'Extract the shared dependency into a third module, then preflight again.';
+        case 'RAW_EVENT_PUBLISH':
+            return 'Publish through a registered intent creator, then run Ark again.';
+        case 'PUBLISH_MISSING_SOURCE':
+            return 'Add metadata.source to the publish call, then run Ark again.';
+        default:
+            return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
+    }
+}
 /**
  * Co-pilot work classifier — the TRUST BOUNDARY for auto-apply.
  * Biased toward 'judgment': false mechanical-safe is worse than an extra human approval.
@@ -214,5 +237,6 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Read the violation message and the layer rules in ark.config.json, then adjust imports or move code to the correct layer.';
     }
+    enriched.nextAction = deterministicNextAction(violation);
     return enriched;
 }

package/bin/lib/violations.mjs

@@ -12,6 +12,7 @@ const color = {
 
 /** Canonical: src/domain/baselineKey.ts → bin/lib/baseline-key.mjs (R4). */
 import { baselineKey, baselineOccurrenceKeys } from './baseline-key.mjs';
+import { toAdapterDiagnostic } from './adapter-contract.mjs';
 export { baselineKey, baselineOccurrenceKeys };
 
 export function readBaseline(root, baselinePath) {
@@ -56,8 +57,7 @@ export function printViolation(violation) {
     console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
   }
   console.error(`  ${violation.message}`);
-  const hint = FIX_HINTS[violation.ruleId];
-  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
+  console.error(`  ${color.dim(`Next action: ${toAdapterDiagnostic(violation).nextAction}`)}`);
   console.error('');
 }
 

package/bin/lib/write-path-capabilities.mjs

@@ -25,6 +25,66 @@ export const WRITE_CAPABILITY_NAMES = [
   'repair-payload',
 ];
 
+function boundaryState({ supported, evidence, active, bypassable, hard = false, extra = {} }) {
+  return {
+    supported,
+    installed: evidence.length > 0,
+    active,
+    bypassable,
+    hard,
+    evidence: [...evidence],
+    ...extra,
+  };
+}
+
+function operationCovered(profile, operation) {
+  if (!profile || typeof operation !== 'string') return false;
+  const normalized = operation.trim().toLowerCase();
+  return profile.hookOperations.some((candidate) => candidate.toLowerCase() === normalized);
+}
+
+function buildEnforcementLadder(activeHost, support, evidence, attempt) {
+  const localInstalled = evidence['hard-write'].length > 0;
+  const observedPreTool = attempt?.boundary === 'pre-tool';
+  const covered = observedPreTool && operationCovered(support, attempt.operation);
+  const hard = Boolean(
+    support?.capabilities['hard-write'] && (localInstalled || observedPreTool) && covered
+  );
+  const inferredActive = (installed) => (installed ? 'unverified' : false);
+  return {
+    schemaVersion: '1.0',
+    activeHost,
+    localWrite: boundaryState({
+      supported: Boolean(support?.capabilities['hard-write']),
+      evidence: evidence['hard-write'],
+      active: observedPreTool ? covered : inferredActive(localInstalled),
+      bypassable: !hard,
+      hard,
+      extra: {
+        installed: localInstalled || observedPreTool,
+        completePatch: Boolean(covered && attempt?.completePatch),
+        coverage: covered && attempt?.completePatch ? 'complete-patch' : support?.hookSurface ?? null,
+        ...(observedPreTool
+          ? { operation: attempt.operation, operationCovered: covered }
+          : { operationCovered: 'unverified' }),
+      },
+    }),
+    advisoryMcp: boundaryState({
+      supported: Boolean(support?.capabilities['advisory-write']),
+      evidence: evidence['advisory-write'],
+      active: inferredActive(evidence['advisory-write'].length > 0),
+      bypassable: true,
+    }),
+    ciMerge: boundaryState({
+      supported: true,
+      evidence: evidence['merge-gate'],
+      active: inferredActive(evidence['merge-gate'].length > 0),
+      bypassable: 'unknown',
+      extra: { requiredStatus: 'unverified' },
+    }),
+  };
+}
+
 const KNOWN_HOSTS = HOST_SUPPORT_HOSTS;
 
 function unique(values) {
@@ -164,7 +224,7 @@ export function detectWritePathInventory(root) {
   };
 }
 
-export function buildWritePathCapabilityModel(root, explicitHost) {
+export function buildWritePathCapabilityModel(root, explicitHost, attempt) {
   const inventory = detectWritePathInventory(root);
   const detectedHost = explicitHost ?? detectActiveAgentHost();
   const activeHost = KNOWN_HOSTS.includes(detectedHost) ? detectedHost : 'unknown';
@@ -183,6 +243,12 @@ export function buildWritePathCapabilityModel(root, explicitHost) {
     support: getHostSupportProfile(activeHost),
     capabilities: capabilityMap(capabilityEvidence),
     capabilityEvidence,
+    enforcementLadder: buildEnforcementLadder(
+      activeHost,
+      getHostSupportProfile(activeHost),
+      capabilityEvidence,
+      attempt
+    ),
     inventory,
   };
 }

package/bin/lib/write-path-detect.mjs

@@ -15,9 +15,9 @@ function installToolsForHost(activeHost) {
     : activeHost;
 }
 
-export function detectWritePathCapabilities(root, explicitHost) {
-  const model = buildWritePathCapabilityModel(root, explicitHost);
-  const { activeHost, support, capabilities, capabilityEvidence, inventory } = model;
+export function detectWritePathCapabilities(root, explicitHost, attempt) {
+  const model = buildWritePathCapabilityModel(root, explicitHost, attempt);
+  const { activeHost, support, capabilities, capabilityEvidence, enforcementLadder, inventory } = model;
   const hardWrite = capabilities['hard-write'];
   const advisoryWrite = capabilities['advisory-write'];
   const repairPayload = capabilities['repair-payload'];
@@ -98,6 +98,7 @@ export function detectWritePathCapabilities(root, explicitHost) {
     supportSummary: formatHostSupportSummary(support),
     capabilities,
     capabilityEvidence,
+    enforcementLadder,
     inventory,
     // Compatibility projection for existing doctor/API consumers.
     mode,