arkgate 3.7.0 → 3.8.0

package/bin/lib/prepare-change.mjs

@@ -1,9 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadArchitectureChangeMap, loadContract, preflightChange } from './analysis-engine.mjs';
+import {
+  loadArchitectureChangeMap,
+  loadContract,
+  preflightResolvedChange,
+} 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';
+import { isGovernableSourceFile } from './scan-files.mjs';
+import {
+  canonicalizeCandidateChanges,
+  resolveCandidateFacts,
+} from './resolved-candidate-facts.mjs';
+import { effectiveAnalysisConfig } from './analysis-policy.mjs';
+import { isScanExcludedRelative } from '../ark-shared.mjs';
 
 function candidatePath(value) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -27,16 +36,21 @@ function isIncluded(relativePath, include) {
   });
 }
 
+export function isCandidateSourceInScope(config, relativePath) {
+  return (
+    isGovernableSourceFile(path.basename(relativePath)) &&
+    isIncluded(relativePath, config.include) &&
+    !isScanExcludedRelative(relativePath, config)
+  );
+}
+
 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)) {
+  if (!isCandidateSourceInScope(config, relativePath)) {
     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) {
@@ -73,22 +87,6 @@ export function normalizeChangeSet(input) {
   });
 }
 
-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,
@@ -96,33 +94,65 @@ export function prepareChangeFromRoot({
   changes,
   changeMap,
   changeMapSource,
-  compilerOptions,
+  ts,
+  tsconfig,
+  manifest,
+  overlayChanges,
 }) {
   const normalizedChanges = normalizeChangeSet(changes);
+  const normalizedOverlayChanges =
+    overlayChanges === undefined ? normalizedChanges : normalizeChangeSet(overlayChanges);
+  const effectiveConfig = effectiveAnalysisConfig(config, manifest);
   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 contract = loadContract(
+    effectiveConfig,
+    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),
+  const canonicalChanges = canonicalizeCandidateChanges({
+    root,
+    config: contract.config,
     changes: normalizedChanges,
+  });
+  for (const change of canonicalChanges) assertGovernedSource(effectiveConfig, change.path);
+  const baseFacts = resolveCandidateFacts({
+    root,
+    config: contract.config,
+    ts,
+    ...(tsconfig ? { tsconfig } : {}),
+  });
+  const candidateFacts = resolveCandidateFacts({
+    root,
+    config: contract.config,
+    ts,
+    changes: normalizedOverlayChanges,
+    ...(tsconfig ? { tsconfig } : {}),
+  });
+  const result = preflightResolvedChange({
+    contract,
+    baseFacts,
+    candidateFacts,
+    changes: canonicalChanges,
     ...(loadedChangeMap ? { changeMap: loadedChangeMap } : {}),
-    ...(compilerOptions ? { compilerOptions } : {}),
   });
-  return {
-    ...createAdapterResult({
-      valid: result.valid,
-      violations: result.violations,
-      warnings: result.warnings,
-    }),
-    ...result,
-  };
+  const completeness =
+    result.baseCompleteness === 'unavailable' || result.candidateCompleteness === 'unavailable'
+      ? 'unavailable'
+      : result.baseCompleteness === 'partial' || result.candidateCompleteness === 'partial'
+        ? 'partial'
+        : 'complete';
+  const { diagnostics } = createAdapterResult({
+    valid: result.valid,
+    completeness,
+    violations: result.violations,
+    warnings: result.warnings,
+  });
+  return { ...result, diagnostics };
 }
 
 export function renderChangePreflight(result) {

package/bin/lib/prepare-write.mjs

@@ -73,7 +73,7 @@ export function buildJudgmentBrief(violations) {
  *   placement: object,
  *   root: string,
  *   ts: object,
- *   validate: (source: string) => { valid: boolean, violations?: any[] },
+ *   validate: (source: string) => { valid: boolean, completeness?: string, violations?: any[] },
  *   resolveTargetAbs?: Function,
  * }} opts
  */
@@ -117,7 +117,13 @@ export function composePrepareWrite(opts) {
     ...(placement?.description ? { description: placement.description } : {}),
     // Q03: pass through golden pattern from ark_place (advisory; absent is normal).
     ...(placement?.goldenPattern ? { goldenPattern: placement.goldenPattern } : {}),
+    mode: gate.mode,
     valid: gate.valid,
+    lexicalValid: gate.lexicalValid,
+    ...(gate.completeness ? { completeness: gate.completeness } : {}),
+    ...(Array.isArray(gate.completenessReasons)
+      ? { completenessReasons: gate.completenessReasons }
+      : {}),
     violations: gate.violations,
     ...(gate.autoPatch ? { autoPatch: gate.autoPatch } : {}),
     ...(judgment ? { judgmentBrief: judgment } : {}),

package/bin/lib/resident-doctor-client.mjs

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  RESIDENT_HOOK_PROTOCOL_VERSION,
+  requestResidentHook,
+  residentDoctorEnvironment,
+  residentHookEndpoint,
+} from './resident-hook.mjs';
+
+const arkMcpLauncher = fileURLToPath(new URL('../ark-mcp.mjs', import.meta.url));
+
+/** Try the opt-in resident doctor and let the caller continue through the cold fallback. */
+export async function tryResidentDoctor(args) {
+  if (!args.resident) return false;
+  if (!args.doctor || !args.json) throw new Error('--resident requires --doctor --json.');
+  const endpoint = residentHookEndpoint({
+    root: args.root,
+    config: args.config,
+    manifest: args.manifest,
+    tsconfig: args.tsconfig,
+    launcher: arkMcpLauncher,
+  });
+  const configuredTimeout = Number(process.env.ARK_RESIDENT_DOCTOR_TIMEOUT_MS);
+  const response = await requestResidentHook({
+    socket: endpoint.socket,
+    timeoutMs:
+      Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : 500,
+    request: {
+      protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION,
+      kind: 'doctor',
+      root: path.resolve(args.root),
+      config: args.config,
+      manifest: args.manifest ?? null,
+      tsconfig: args.tsconfig ?? null,
+      environment: residentDoctorEnvironment(),
+    },
+  });
+  if (
+    !response ||
+    response.fallback === true ||
+    !Number.isInteger(response.status) ||
+    typeof response.stdout !== 'string' ||
+    typeof response.stderr !== 'string'
+  ) {
+    if (process.env.ARK_RESIDENT_DOCTOR_REQUIRED === '1') {
+      throw new Error('Resident doctor was required but unavailable.');
+    }
+    return false;
+  }
+  if (response.stdout) process.stdout.write(response.stdout);
+  if (response.stderr) process.stderr.write(response.stderr);
+  process.exitCode = response.status;
+  return true;
+}

package/bin/lib/resident-hook.mjs

@@ -0,0 +1,247 @@
+/** Z07 transport only; ark-mcp-runtime owns every hook decision. */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+export const RESIDENT_HOOK_PROTOCOL_VERSION = 1;
+const RESIDENT_DOCTOR_ENV = [
+  'ARK_ACTIVE_HOST',
+  'ARK_DOCTOR_GITHUB',
+  'CODEX_HOME',
+  'CODEX_CI',
+  'CODEX_SANDBOX',
+  'CODEX_SESSION_ID',
+  'CODEX_THREAD_ID',
+  'CLAUDE_CODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_PROJECT_DIR',
+  'CLAUDECODE',
+  'CURSOR_AGENT',
+  'CURSOR_AGENT_CLI',
+  'CURSOR_TRACE_ID',
+  'GH_HOST',
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+  'GROK_BUILD',
+  'GROK_AGENT',
+  'GROK_SESSION_ID',
+  'GROK_WORKSPACE_ROOT',
+  'HOME',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'PATH',
+  'USERPROFILE',
+  'XAI_GROK',
+];
+
+export function residentDoctorEnvironment(env = process.env) {
+  const hash = createHash('sha256');
+  for (const name of RESIDENT_DOCTOR_ENV) {
+    hash.update(name).update('\0').update(env[name] ?? '').update('\0');
+  }
+  return { digest: `sha256:${hash.digest('hex')}` };
+}
+
+function residentRuntimeIdentity(launcher) {
+  const hash = createHash('sha256');
+  const packageRoot = path.dirname(path.dirname(launcher));
+  const files = [path.join(packageRoot, 'package.json')];
+  const visit = (directory) => {
+    try {
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) visit(absolute);
+        else if (/\.(?:[cm]?js|json)$/.test(entry.name)) files.push(absolute);
+      }
+    } catch { files.push(directory); }
+  };
+  visit(path.join(packageRoot, 'bin'));
+  visit(path.join(packageRoot, 'dist'));
+  for (const file of [...new Set(files)].sort()) {
+    hash.update(path.relative(packageRoot, file)).update('\0');
+    try { hash.update(fs.readFileSync(file)); } catch { hash.update('missing'); }
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+export function residentHookEndpoint({ root, config, manifest, tsconfig, launcher }) {
+  let realRoot;
+  try { realRoot = fs.realpathSync(root); } catch { realRoot = path.resolve(root); }
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
+  const directory = path.join(os.tmpdir(), `arkgate-${uid}`);
+  const digest = createHash('sha256').update(JSON.stringify({
+    root: realRoot,
+    config: path.resolve(root, config),
+    manifest: manifest ? path.resolve(root, manifest) : null,
+    tsconfig: tsconfig ? path.resolve(root, tsconfig) : null,
+    launcher: path.resolve(launcher),
+    executable: process.execPath,
+    protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION,
+    runtimeIdentity: residentRuntimeIdentity(path.resolve(launcher)),
+  })).digest('hex').slice(0, 24);
+  return {
+    directory,
+    socket: process.platform === 'win32'
+      ? `\\\\.\\pipe\\arkgate-z07-${uid}-${digest}`
+      : path.join(directory, `${digest}.sock`),
+  };
+}
+
+export function residentEnvironmentIdentity(paths, tokens = []) {
+  const hash = createHash('sha256');
+  for (const token of [...tokens].map(String).sort()) hash.update('token\0').update(token).update('\0');
+  for (const file of [...new Set(paths.map((entry) => path.resolve(entry)))].sort()) {
+    hash.update('path\0').update(file).update('\0');
+    try {
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) {
+        hash.update('link\0').update(fs.readlinkSync(file)).update('\0');
+        hash.update(fs.realpathSync(file)).update('\0');
+        const target = fs.statSync(file);
+        if (target.isFile()) hash.update('target-file\0').update(fs.readFileSync(file));
+        else hash.update('target-other\0');
+      }
+      else if (stat.isFile()) hash.update('file\0').update(fs.readFileSync(file));
+      else hash.update('other\0');
+    } catch { hash.update('missing\0'); }
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+function inputState(file) { // Stryker disable StringLiteral: opaque state tags have no public meaning
+  const stat = fs.lstatSync(file, { bigint: true, throwIfNoEntry: false });
+  if (!stat) return 'missing';
+  const metadata = [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeNs, stat.ctimeNs]
+    .map(String)
+    .join(':');
+  if (stat.isSymbolicLink()) {
+    const target = fs.realpathSync(file);
+    const targetStat = fs.statSync(file, { bigint: true });
+    return `link:${metadata}:${fs.readlinkSync(file)}:${target}:${[
+      targetStat.dev,
+      targetStat.ino,
+      targetStat.mode,
+      targetStat.size,
+      targetStat.mtimeNs,
+      targetStat.ctimeNs,
+    ].map(String).join(':')}`;
+  }
+  if (stat.isDirectory()) {
+    const entries = fs.readdirSync(file, { withFileTypes: true })
+      .map((entry) => `${entry.name}:${entry.isDirectory() ? 'd' : entry.isFile() ? 'f' : 'o'}`)
+      .sort();
+    return `dir:${metadata}:${entries.join('\0')}`;
+  }
+  return `${stat.isFile() ? 'file' : 'other'}:${metadata}`;
+} // Stryker restore StringLiteral
+
+/** Process-local, metadata-based invalidation ledger; never a persisted result cache. */
+export function createResidentInputLedger(paths) {
+  const normalized = [...new Set(paths.map((entry) => path.resolve(entry)))].sort();
+  const states = new Map(normalized.map((file) => [file, inputState(file)]));
+  return {
+    paths: normalized,
+    matches(candidatePaths = normalized) {
+      try {
+        const candidate = [...new Set(candidatePaths.map((entry) => path.resolve(entry)))].sort();
+        return (
+          candidate.length === normalized.length &&
+          candidate.every((file, index) =>
+            file === normalized[index] && inputState(file) === states.get(file)
+          )
+        );
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+export function requestResidentHook({ socket, request, timeoutMs = 75 }) {
+  return new Promise((resolve) => {
+    let done = false;
+    let buffered = '';
+    const client = net.createConnection(socket);
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      client.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    client.setEncoding('utf8');
+    client.once('connect', () => client.write(`${JSON.stringify(request)}\n`));
+    client.on('data', (chunk) => {
+      buffered += chunk;
+      if (buffered.length > 24 * 1024 * 1024) return finish(null);
+      const newline = buffered.indexOf('\n');
+      if (newline < 0) return;
+      try {
+        const parsed = JSON.parse(buffered.slice(0, newline));
+        finish(parsed?.protocolVersion === RESIDENT_HOOK_PROTOCOL_VERSION ? parsed : null);
+      } catch { finish(null); }
+    });
+    client.once('error', () => finish(null));
+    client.once('end', () => finish(null));
+  });
+}
+
+function secureDirectory(directory) {
+  if (process.platform === 'win32') return true;
+  try {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) return false;
+    fs.chmodSync(directory, 0o700);
+    return true;
+  } catch { return false; }
+}
+
+export async function startResidentHookServer({ endpoint, handle }) {
+  if (!secureDirectory(endpoint.directory)) return null;
+  const server = net.createServer((client) => {
+    client.setEncoding('utf8');
+    let buffered = '';
+    let handled = false;
+    client.on('data', async (chunk) => {
+      if (handled) return;
+      buffered += chunk;
+      if (buffered.length > 12 * 1024 * 1024) return client.destroy();
+      const newline = buffered.indexOf('\n');
+      if (newline < 0) return;
+      handled = true;
+      let response;
+      try { response = await handle(JSON.parse(buffered.slice(0, newline))); }
+      catch { response = { protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION, fallback: true }; }
+      if (!client.destroyed) client.end(`${JSON.stringify(response)}\n`);
+    });
+  });
+  const listening = await new Promise((resolve) => {
+    const failed = () => resolve(false);
+    server.once('error', failed);
+    server.listen(endpoint.socket, () => {
+      server.off('error', failed);
+      resolve(true);
+    });
+  });
+  if (!listening) {
+    try { server.close(); } catch { /* The endpoint is already owned. */ }
+    return null;
+  }
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try { server.close(); } catch { /* Already closed. */ }
+    if (process.platform !== 'win32') {
+      try { fs.unlinkSync(endpoint.socket); } catch { /* Exact endpoint already absent. */ }
+    }
+  };
+  return { cleanup };
+}