arkgate 3.7.0 → 3.8.0

package/bin/lib/scan-files.mjs

@@ -56,19 +56,27 @@ function isInsideRoot(root, target) {
  * while escaping links fail closed instead of reading arbitrary filesystem paths.
  */
 export function walk(dir, files = [], options = {}) {
-  const state = options.state ?? {
-    root: options.root ? fs.realpathSync(options.root) : undefined,
-    visitedDirectories: new Set(),
-    visitedFiles: new Set(),
-  };
+  let state = options.state;
+  if (!state) {
+    if (options.root) options.observeInput?.(path.resolve(options.root), 'realpath');
+    state = {
+      root: options.root ? fs.realpathSync(options.root) : undefined,
+      visitedDirectories: new Set(),
+      visitedFiles: new Set(),
+      observeInput: options.observeInput,
+    };
+  }
+  state.observeInput?.(path.resolve(dir), 'lstat');
   const lstat = fs.lstatSync(dir, { throwIfNoEntry: false });
   if (!lstat) return files;
+  state.observeInput?.(path.resolve(dir), 'realpath');
   const resolved = fs.realpathSync(dir);
   if (state.root && !isInsideRoot(state.root, resolved)) {
     throw new Error(
       `Refusing to scan symlink outside project root: ${dir} -> ${resolved}`
     );
   }
+  if (lstat.isSymbolicLink()) state.observeInput?.(path.resolve(dir), 'stat');
   const stat = lstat.isSymbolicLink()
     ? fs.statSync(dir, { throwIfNoEntry: false })
     : lstat;
@@ -87,8 +95,10 @@ export function walk(dir, files = [], options = {}) {
     return files;
   }
   if (!stat.isDirectory()) return files;
+  state.onDirectory?.(dir, resolved);
   if (state.visitedDirectories.has(resolved)) return files;
   state.visitedDirectories.add(resolved);
+  state.observeInput?.(path.resolve(dir), 'directory');
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -105,11 +115,14 @@ export function walk(dir, files = [], options = {}) {
 }
 
 /** Walk include roots then drop codegen / config.exclude (universal scan filter). */
-export function collectGovernedFiles(root, config) {
+export function collectGovernedFiles(root, config, options = {}) {
+  options.observeInput?.(path.resolve(root), 'realpath');
   const state = {
     root: fs.realpathSync(root),
     visitedDirectories: new Set(),
     visitedFiles: new Set(),
+    onDirectory: options.onDirectory,
+    observeInput: options.observeInput,
   };
   const raw = (config.include ?? []).flatMap((entry) =>
     walk(path.join(root, entry), [], { state })

package/bin/lib/snippet-analysis.mjs

@@ -0,0 +1,119 @@
+/** Fail-closed completeness evidence for one proposed source snippet. */
+import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
+
+function finding(ruleId, message, file, nextAction) {
+  return {
+    ruleId,
+    code: ruleId,
+    message,
+    ...(file ? { file, filePath: file } : {}),
+    nextAction,
+  };
+}
+
+export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
+  const observed = gate.validate(source, context);
+  const base = {
+    valid: Boolean(observed.lexicalValid ?? observed.valid),
+    violations: Array.isArray(observed.violations) ? observed.violations : [],
+  };
+  const file = context.filePath;
+
+  if (!ts || typeof ts.createSourceFile !== 'function') {
+    return {
+      mode: 'lexical-compatibility',
+      valid: false,
+      lexicalValid: false,
+      completeness: ANALYSIS_COMPLETENESS.unavailable,
+      completenessReasons: [
+        {
+          code: 'ANALYSIS_HOST_UNAVAILABLE',
+          message: 'No API-compatible TypeScript host parsed the proposed source.',
+          ...(file ? { file } : {}),
+        },
+      ],
+      violations: [
+        ...base.violations,
+        finding(
+          'ANALYSIS_HOST_UNAVAILABLE',
+          'Analysis unavailable: no API-compatible TypeScript host parsed the proposed source.',
+          file,
+          'Restore ArkGate\'s TypeScript analysis host, then validate the complete source again.'
+        ),
+      ],
+    };
+  }
+
+  try {
+    const parsed = ts.createSourceFile(
+      file || 'generated.ts',
+      source,
+      ts.ScriptTarget.Latest,
+      true
+    );
+    if (!Array.isArray(parsed.parseDiagnostics)) throw new Error('parse diagnostics unavailable');
+    const diagnosticCount = parsed.parseDiagnostics.length;
+    if (diagnosticCount > 0) {
+      return {
+        mode: 'lexical-compatibility',
+        valid: false,
+        lexicalValid: false,
+        completeness: ANALYSIS_COMPLETENESS.partial,
+        completenessReasons: [
+          {
+            code: 'ANALYSIS_PARSE_INCOMPLETE',
+            message: `The proposed source has ${diagnosticCount} parse diagnostic(s).`,
+            ...(file ? { file } : {}),
+          },
+        ],
+        violations: [
+          ...base.violations,
+          finding(
+            'ANALYSIS_PARSE_INCOMPLETE',
+            `Analysis partial: proposed source has ${diagnosticCount} parse diagnostic(s).`,
+            file,
+            'Fix the syntax until the TypeScript parser reports zero diagnostics, then validate again.'
+          ),
+        ],
+      };
+    }
+    return {
+      ...base,
+      mode: 'lexical-compatibility',
+      valid: false,
+      lexicalValid: base.valid,
+      completeness: ANALYSIS_COMPLETENESS.partial,
+      completenessReasons: [
+        {
+          code: 'LEXICAL_EVIDENCE_INCOMPLETE',
+          message:
+            'Single-file validation cannot prove project module resolution or complete candidate evidence; use ark_prepare_change for a parity-capable verdict.',
+          ...(file ? { file } : {}),
+        },
+      ],
+    };
+  } catch {
+    return {
+      mode: 'lexical-compatibility',
+      valid: false,
+      lexicalValid: false,
+      completeness: ANALYSIS_COMPLETENESS.unavailable,
+      completenessReasons: [
+        {
+          code: 'ANALYSIS_HOST_UNAVAILABLE',
+          message: 'The TypeScript host could not parse the proposed source.',
+          ...(file ? { file } : {}),
+        },
+      ],
+      violations: [
+        ...base.violations,
+        finding(
+          'ANALYSIS_HOST_UNAVAILABLE',
+          'Analysis unavailable: the TypeScript host could not parse the proposed source.',
+          file,
+          'Restore ArkGate\'s TypeScript analysis host, then validate the complete source again.'
+        ),
+      ],
+    };
+  }
+}

package/bin/lib/source-policy.mjs

@@ -12,6 +12,30 @@ export const SOURCE_POLICY_MESSAGES = {
     RAW_EVENT_PUBLISH: 'Publish through a registered intent creator; raw event objects or intent strings bypass Ark contracts and tooling.',
     PUBLISH_MISSING_SOURCE: 'Strict Ark publish calls must include metadata.source.',
 };
+export const DEFAULT_INTENT_PREFIXES = Object.freeze([
+    { layer: 'DomainModel', prefixes: ['Domain.'] },
+    { layer: 'ApplicationOrchestration', prefixes: ['Application.'] },
+    { layer: 'PersistenceAdapters', prefixes: ['Adapter.Persistence.', 'Adapter.Repository.'] },
+    { layer: 'IntegrationAdapters', prefixes: ['Adapter.Integration.', 'Adapter.External.'] },
+    { layer: 'WorkflowSagaEngine', prefixes: ['Workflow.'] },
+    { layer: 'BackgroundJobsScheduling', prefixes: ['Job.'] },
+    { layer: 'PresentationAdapters', prefixes: ['Presentation.', 'Adapter.Presentation.', 'Adapter.Api.'] },
+    { layer: 'ReportingReadModels', prefixes: ['Reporting.'] },
+    { layer: 'ExtensibilityMetadata', prefixes: ['Metadata.'] },
+    { layer: 'SecurityAuditObservability', prefixes: ['Security.', 'Audit.', 'Observability.'] },
+    { layer: 'Kernel', prefixes: ['Kernel.'] },
+]);
+/** Longest matching prefix wins; declaration order resolves an identical-prefix tie. */
+export function resolveIntentLayer(intent, layers) {
+    const candidates = layers.flatMap((layer, layerIndex) => (layer.prefixes ?? layer.intentPrefixes ?? []).map((prefix) => ({
+        layer: layer.name,
+        layerIndex,
+        prefix: prefix.endsWith('.') ? prefix : `${prefix}.`,
+    })));
+    return candidates
+        .filter(({ prefix }) => intent.startsWith(prefix))
+        .sort((left, right) => right.prefix.length - left.prefix.length || left.layerIndex - right.layerIndex)[0]?.layer;
+}
 export function looksLikeArkIntent(value) {
     return /^(Domain|Application|Adapter|Workflow|Job|Presentation|Reporting|Metadata|Security|Audit|Observability|Kernel)\.[A-Za-z0-9_.]+$/.test(value);
 }

package/bin/lib/typescript-host.mjs

@@ -2,11 +2,10 @@
  * TypeScript host resolution for architecture scan (API-compatible loader).
  */
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { usableTypescript, typescriptUsabilityHint } from '../ark-shared.mjs';
-import { __arkCheckCli } from './gate-files.mjs';
 
 export async function loadTypeScript(root) {
-  const { createRequire } = await import('node:module');
   const loaders = [];
   try {
     const req = createRequire(path.join(root, 'package.json'));
@@ -24,15 +23,15 @@ export async function loadTypeScript(root) {
   } catch {
     /* project has no package.json resolvable tree */
   }
-  // Nested under arkgate (production dependency) — must work when project has only TS7.
+  // Dedicated production fallback: a different package identity cannot dedupe to project TS7.
   try {
-    const req = createRequire(__arkCheckCli);
+    const req = createRequire(import.meta.url);
     loaders.push({
-      label: 'arkgate',
-      load: () => req('typescript'),
+      label: 'arkgate-fallback',
+      load: () => req('typescript-ark-host'),
       resolvePath: () => {
         try {
-          return req.resolve('typescript');
+          return req.resolve('typescript-ark-host');
         } catch {
           return null;
         }
@@ -41,15 +40,6 @@ export async function loadTypeScript(root) {
   } catch {
     /* ark install tree unavailable */
   }
-  loaders.push({
-    label: 'import',
-    load: async () => {
-      const m = await import('typescript');
-      return m;
-    },
-    resolvePath: () => null,
-  });
-
   let projectRejected = null;
   const triedPaths = new Set();
   for (const { label, load, resolvePath } of loaders) {
@@ -74,15 +64,22 @@ export async function loadTypeScript(root) {
           ts,
           source: label,
           version,
+          ...(resolved ? { resolvedPath: resolved } : {}),
           ...(projectRejected ? { fallbackReason: projectRejected } : {}),
         };
       }
       if (label === 'project' && mod) {
-        projectRejected = `project typescript is not API-compatible (${typescriptUsabilityHint(mod)}); using ArkGate's JS-API TypeScript fallback (TypeScript 7.0 main export is version-only). See docs/typescript-support.md.`;
+        projectRejected = `project TypeScript is not API-compatible (${typescriptUsabilityHint(mod)}); using ArkGate's physically independent TypeScript 6 JS-API host. See docs/typescript-support.md.`;
       }
     } catch {
       /* try next loader */
     }
   }
-  return null;
+  return {
+    ts: null,
+    source: 'unavailable',
+    reason:
+      'ArkGate could not load either the project TypeScript API or its independent TypeScript 6 fallback.',
+    ...(projectRejected ? { fallbackReason: projectRejected } : {}),
+  };
 }

package/bin/lib/unavailable-analysis.mjs

@@ -0,0 +1,76 @@
+/** Report TypeScript-host unavailability without a false-green architecture result. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeCoverage, runDoctor, runPlan } from './doctor-plan.mjs';
+import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
+import { summarizeParseHealth } from './parse-health.mjs';
+
+export function reportUnavailableAnalysis({
+  root,
+  config,
+  rules,
+  files,
+  args,
+  message,
+  nextAction,
+  createResult,
+}) {
+  const completeness = ANALYSIS_COMPLETENESS.unavailable;
+  const parseHealth = summarizeParseHealth();
+  const finding = {
+    ruleId: 'ANALYSIS_HOST_UNAVAILABLE',
+    message,
+    nextAction,
+    file: '<analysis-host>',
+  };
+
+  if (args.plan) {
+    const coverage = computeCoverage(root, config, files, rules);
+    runPlan(root, [], args.json, coverage.governed.percent, coverage.governed.totalFiles, {
+      config,
+      files,
+      coverage,
+      completeness,
+    });
+    process.exitCode = 2;
+    return;
+  }
+
+  if (args.doctor) {
+    const configPath = path.isAbsolute(args.config) ? args.config : path.join(root, args.config);
+    runDoctor(root, config, files, rules, [], args.json, {
+      configPath,
+      configMissing: !fs.existsSync(configPath),
+      parseHealth,
+      completeness,
+    });
+    process.exitCode = 2;
+    return;
+  }
+
+  const adapterResult = createResult({
+    valid: false,
+    completeness,
+    completenessReasons: [
+      {
+        code: finding.ruleId,
+        message: finding.message,
+        file: finding.file,
+      },
+    ],
+    mode: 'resolved-candidate-facts',
+    violations: [finding],
+  });
+  if (args.json) {
+    console.log(JSON.stringify({
+      ...adapterResult,
+      ok: false,
+      violations: [finding],
+      warnings: [],
+    }, null, 2));
+  } else {
+    console.error(message);
+    console.error(`Next action: ${nextAction}`);
+  }
+  process.exitCode = 2;
+}

package/bin/lib/upgrade-command.mjs

@@ -0,0 +1,115 @@
+/** Read-only-first `ark upgrade` orchestration. Managed identity logic lives separately. */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import {
+  applyManagedUpgrade,
+  managedUpgradeJson,
+  planManagedUpgrade,
+  renderManagedUpgrade,
+} from './managed-upgrade.mjs';
+
+function installedCli(root) {
+  const requireFromProject = createRequire(path.join(root, 'package.json'));
+  const packageJson = requireFromProject.resolve('arkgate/package.json');
+  return path.join(path.dirname(packageJson), 'bin', 'ark.mjs');
+}
+
+function previewArgs(args) {
+  const next = ['upgrade', '--root', args.root, '--no-install'];
+  if (args.tools) next.push('--tools', args.tools);
+  if (args.acceptConflicts) next.push('--accept-conflicts');
+  if (!args.strict) next.push('--no-strict');
+  if (args.json) next.push('--json');
+  return next;
+}
+
+function quote(value) {
+  const text = String(value);
+  return /^[A-Za-z0-9_./:@=-]+$/.test(text) ? text : `'${text.replace(/'/g, `'"'"'`)}'`;
+}
+
+function nextCommand(args, planDigest) {
+  const parts = ['ark', 'upgrade', '--apply', '--root', args.root];
+  if (!args.install) parts.push('--no-install');
+  if (!args.install && planDigest) parts.push('--plan-digest', planDigest);
+  if (args.tools) parts.push('--tools', args.tools);
+  if (args.acceptConflicts) parts.push('--accept-conflicts');
+  if (!args.strict) parts.push('--no-strict');
+  if (args.json) parts.push('--json');
+  return parts.map(quote).join(' ');
+}
+
+function verify(root, json, arkCheck, runArkCheck) {
+  const args = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
+  if (!json) return { exitCode: runArkCheck(args, { cwd: root }) };
+  const result = spawnSync(process.execPath, [arkCheck, ...args, '--json'], {
+    cwd: root,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return { exitCode: result.status ?? 1, stderr: result.stderr?.trim() || undefined };
+}
+
+export function runUpgradeCommand(args, dependencies) {
+  const root = args.root;
+  if (args.apply && args.install) {
+    const [command, commandArgs] = dependencies.packageInstallArgv(root);
+    if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
+    const install = spawnSync(command, commandArgs, {
+      cwd: root,
+      stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      encoding: 'utf8',
+    });
+    const exitCode = install.status ?? 1;
+    if (exitCode !== 0) {
+      if (args.json && install.stderr) console.error(install.stderr.trim());
+      console.error(
+        `Package update failed (exit ${exitCode}). Fix the install and re-run, or use ` +
+          '`ark upgrade --no-install` against the installed version.'
+      );
+      return exitCode;
+    }
+    return spawnSync(process.execPath, [installedCli(root), ...previewArgs(args)], {
+      cwd: root,
+      stdio: 'inherit',
+      encoding: 'utf8',
+    }).status ?? 1;
+  }
+
+  const plan = planManagedUpgrade(root, {
+    tools: args.tools,
+    acceptConflicts: args.acceptConflicts,
+  });
+  if (!args.apply) {
+    const command = nextCommand(args, plan.planDigest);
+    if (args.json) console.log(managedUpgradeJson(plan, { nextCommand: command }));
+    else {
+      renderManagedUpgrade(plan, {
+        next: args.install
+          ? `Update the package and recompute this preview with: ${command}`
+          : `Apply the exact preview with: ${command}`,
+      });
+    }
+    return 0;
+  }
+
+  const applied = applyManagedUpgrade(root, plan, args.planDigest);
+  if (applied.blocked) {
+    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    else renderManagedUpgrade(applied, {
+      next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
+    });
+    return 1;
+  }
+  const verification = args.strict
+    ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
+    : { mode: 'skipped', exitCode: 0 };
+  if (args.json) console.log(JSON.stringify({ ...applied, verification }, null, 2));
+  else {
+    renderManagedUpgrade(applied);
+    if (!args.strict) console.log('Architecture verification skipped (--no-strict).');
+  }
+  return verification.exitCode;
+}