@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/cli.js

@@ -0,0 +1,1299 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  CLI_NAME,
+  CAPABILITY_PROFILE_FILENAME,
+  DEFAULT_ANALYSIS_LOG_PATH,
+  DEFAULT_AI_SCORECARD_PATH,
+  DEFAULT_BENCHMARK_CONFIG_PATH,
+  DEFAULT_BENCHMARK_REPORT_PATH,
+  DEFAULT_CONFORMANCE_REPORT_PATH,
+  DEPLOYMENT_PROFILE_FILENAME,
+  DEFAULT_GOVERNANCE_DIRECTORY,
+  DEFAULT_KNOWLEDGE_MANIFEST_PATH,
+  DEFAULT_MANIFEST_PATH,
+  DEFAULT_EVALUATION_REPORT_PATH,
+  DEFAULT_METRICS_PATH,
+  QUALIFICATION_RECORD_FILENAME,
+  DEFAULT_VERSION_ANALYSIS_PATH,
+  DEFAULT_REPOSITORY_IMPACT_EVIDENCE_PATH,
+  DEFAULT_UPGRADE_DECISION_PATH,
+  DEFAULT_REPOSITORY_IMPACT_PATH,
+  DEFAULT_REPOSITORY_IMPACT_REPORT_PATH,
+  DEFAULT_MIGRATION_CHECKLIST_PATH,
+  DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH,
+  DEFAULT_USAGE_INDEX_PATH,
+  PRODUCT_NAME,
+  VERSION
+} from './constants.js';
+import { resolveArtifactRootChain } from './artifact-root-compatibility.js';
+import { resolveIdentityEnvironment } from './environment-compatibility.js';
+import {
+  buildAiScorecard,
+  serializeAiScorecard,
+  writeAiScorecard
+} from './ai-scorecard.js';
+import {
+  analyzeDependencyAiContext,
+  buildVersionAnalysisPrompt
+} from './ai-version-analysis.js';
+import {
+  createHttpJsonAiProvider,
+  createProviderAiRuntime
+} from './ai-runtime.js';
+import {
+  DEFAULT_AI_TIMEOUT_MS,
+  createOpenAiCompatibleProvider
+} from './openai-compatible-provider.js';
+import { isAiRuntimeDebugEnabled } from './ai-runtime-debug.js';
+import {
+  buildDependencyAiContext,
+  resolveDependencyAnalysisInputs
+} from './dependency-ai-context.js';
+import { createEvidenceSourceAdapter } from './evidence-source-adapter.js';
+import { discoverProject } from './discovery.js';
+import {
+  DEFAULT_EVALUATION_DATASET_PATH,
+  runEvaluation,
+  writeEvaluationReport
+} from './evaluation-runner.js';
+import { serializeEvaluationReport } from './evaluation-report.js';
+import {
+  loadBenchmarkConfig,
+  runBenchmark,
+  serializeBenchmarkReport,
+  writeBenchmarkReport
+} from './benchmark-runner.js';
+import { runConformance } from './conformance-runner.js';
+import {
+  serializeConformanceReport,
+  writeConformanceReport
+} from './conformance-report.js';
+import {
+  createDefaultGovernanceArtifacts,
+  serializeGovernanceArtifacts,
+  writeGovernanceArtifacts
+} from './governance-metadata.js';
+import {
+  buildMetrics,
+  loadEvaluationReportForMetrics,
+  writeMetrics
+} from './metrics-engine.js';
+import { createCliHttpRuntime } from './http/cli-http-runtime.js';
+import {
+  DEFAULT_KNOWLEDGE_CACHE_DIRECTORY,
+  createKnowledgeCache
+} from './knowledge-cache.js';
+import {
+  buildKnowledgeEvidenceBundle,
+  writeKnowledgeEvidenceBundle
+} from './knowledge-evidence-producer.js';
+import { buildKnowledgeManifest } from './knowledge-manifest-builder.js';
+import { serializeKnowledgeManifest, writeKnowledgeManifest } from './knowledge-manifest-writer.js';
+import { createKnowledgeResearchOrchestrator } from './knowledge-research.js';
+import { runImpactEvidenceGeneration } from './impact-evidence/runtime.js';
+import { writeRepositoryImpactEvidence } from './impact-evidence/writer.js';
+import { runImpactAnalysis } from './impact/runtime.js';
+import { writeRepositoryImpact } from './impact/writer.js';
+import {
+  PipelineCancellationError,
+  PipelineStageError,
+  createAnalysisStages,
+  runAnalysisPipeline
+} from './orchestration/pipeline.js';
+import { writeAnalysisFailureLog } from './orchestration/failure-log.js';
+import { createProgressReporter } from './orchestration/progress-reporter.js';
+import { writeTextArtifact } from './orchestration/text-writer.js';
+import { loadProjectManifestInput } from './project-manifest-input.js';
+import { createResearchPlan } from './research-plan.js';
+import { createNpmRegistryAdapter } from './registry/npm-registry-adapter.js';
+import { createPypiRegistryAdapter } from './registry/pypi-registry-adapter.js';
+import { renderConsoleSummary } from './renderers/console.js';
+import { buildImpactPresentationViewModel } from './renderers/impact-presentation.js';
+import { renderMarkdownReport } from './renderers/markdown.js';
+import { isPortableRelativePath } from './portable.js';
+import {
+  buildProductCompletion,
+  productCompletionExitCode
+} from './product-completion.js';
+import {
+  parseTargetSelector,
+  resolveTargetSelectors,
+  targetOccurrenceKey
+} from './target-selector.js';
+import {
+  DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH,
+  loadVersionAnalysisArtifacts
+} from './version-analysis-loader.js';
+import { buildVersionAnalysisManifest } from './version-analysis-manifest.js';
+import { serializeVersionAnalysisManifest, writeVersionAnalysisManifest } from './version-analysis-writer.js';
+import { runUsageDiscovery } from './usage/runtime.js';
+import { writeUsageIndex } from './usage/writer.js';
+import { runMigrationChecklistStage } from './migration-checklist/runtime.js';
+import { runUpgradeDecisionStage } from './upgrade-decision/runtime.js';
+import { resolveMigrationQualification } from './migration-checklist/qualification-resolution.js';
+
+const legacyInvocationWarnings = new Set();
+
+const HELP = `${PRODUCT_NAME} ${VERSION}
+
+Decide whether evaluated dependency targets should be kept, planned, or investigated.
+The default registry candidate is a fact, not an upgrade recommendation.
+
+Usage:
+  ${CLI_NAME} analyze <repository> [options]
+  ${CLI_NAME} discover [path] [options]
+  ${CLI_NAME} research [path] [options]
+  ${CLI_NAME} analyze-version [path] [options]
+  ${CLI_NAME} eval [options]
+  ${CLI_NAME} scorecard [options]
+  ${CLI_NAME} benchmark [options]
+  ${CLI_NAME} conformance [options]
+  ${CLI_NAME} governance [options]
+  ${CLI_NAME} [path] [options]
+
+Analyze options:
+      --offline         Use fresh research cache entries only; never request registries
+      --max-depth <n>   Maximum directory depth for discovery and usage scanning
+      --target <selector>
+                        Select a caller-owned target. Repeatable.
+                        Required fields: package=<canonical-id>,target=<version>
+                        Optional occurrence fields: project,manifest,type,occurrence
+                        occurrence is a stable sha256 ID shown in ambiguity guidance
+                        Example: package=npm:react,target=20.0.0
+                        Scoped example: package=npm:@scope/pkg,target=3.0.0
+      --fail-on-incomplete
+                        Exit 2 for review-required or insufficient-data outcomes.
+                        Partial provider/output/runtime results always exit 2.
+      --stdout          Print only the machine-readable product completion summary
+      --experimental-migration-checklist
+                        Generate an evidence-grounded migration checklist.
+                        Experimental. Every migration action requires human review.
+      --migration-qualification <path>
+                        Migration Planning v2 qualification record relative to the
+                        repository (default: ${DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH})
+      --progress <mode> Control analysis progress: auto, interactive, or plain
+                        auto uses interactive output on a TTY and stable plain
+                        lines otherwise. Heartbeats show real elapsed time;
+                        no percentage or ETA is inferred. (default: auto)
+
+Discover options:
+  -o, --output <path>   Project Manifest path relative to the project root
+                        (default: ${DEFAULT_MANIFEST_PATH})
+      --stdout          Print the manifest instead of writing a file
+      --no-pretty       Emit compact JSON
+      --max-depth <n>   Maximum directory depth to scan
+      --fail-on-warning Return exit code 2 when discovery has warnings
+
+Research options:
+  -o, --output <path>   Knowledge Manifest path relative to the project root
+                        (default: ${DEFAULT_KNOWLEDGE_MANIFEST_PATH})
+      --stdout          Print only the Knowledge Manifest JSON
+      --offline         Use fresh cache entries only; never request registries
+
+Analyze-version options:
+  -o, --output <path>   Version Analysis artifact path relative to the project root
+                        (default: ${DEFAULT_VERSION_ANALYSIS_PATH})
+      --package <id>    Analyze one exact canonical package ID (for example, pypi:langsmith)
+      --target <selector>
+                        Select explicit targets using the same analyze selector syntax
+      --stdout          Print only the Version Analysis JSON
+
+Eval options:
+      --dataset <path>  Golden Dataset file or directory
+                        (default: ${DEFAULT_EVALUATION_DATASET_PATH})
+  -o, --output <path>   Evaluation report path
+                        (default: ${DEFAULT_EVALUATION_REPORT_PATH})
+      --stdout          Print only the Evaluation Report JSON
+
+Scorecard options:
+      --report <path>   Evaluation Report path
+                        (default: ${DEFAULT_EVALUATION_REPORT_PATH})
+      --metrics-output <path>
+                        Metrics artifact path
+                        (default: ${DEFAULT_METRICS_PATH})
+  -o, --output <path>   AI Scorecard path
+                        (default: ${DEFAULT_AI_SCORECARD_PATH})
+      --stdout          Print only the AI Scorecard JSON
+
+Benchmark options:
+      --config <path>   Benchmark config path
+                        (default: ${DEFAULT_BENCHMARK_CONFIG_PATH})
+  -o, --output <path>   Benchmark Report path
+                        (default: ${DEFAULT_BENCHMARK_REPORT_PATH})
+      --stdout          Print only the Benchmark Report JSON
+
+Conformance options:
+  -o, --output <path>   Offline Conformance Report path
+                        (default: ${DEFAULT_CONFORMANCE_REPORT_PATH})
+      --stdout          Print only the Offline Conformance Report JSON
+
+Governance options:
+  -o, --output <path>   Directory for portable governance artifacts
+                        (default: ${DEFAULT_GOVERNANCE_DIRECTORY})
+      --stdout          Print a bundle containing the three governance artifacts
+  -h, --help            Show help
+  -v, --version         Show version
+`;
+
+function takeValue(args, index, option) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('-')) throw new Error(`${option} requires a value`);
+  return value;
+}
+
+function outputPath(root, output) {
+  if (!isPortableRelativePath(output)) throw new Error('--output must be a portable path relative to the repository root');
+  return path.resolve(root, output);
+}
+
+function compatibilityDiagnostic(io, message) {
+  (io.stderr ?? process.stderr).write(`${message}\n`);
+}
+
+function withResolvedEnvironment(io) {
+  if (io.environmentResolved) return io;
+  const env = Object.hasOwn(io, 'env') ? io.env : process.env;
+  return {
+    ...io,
+    env: resolveIdentityEnvironment(env, {
+      overrides: io.environmentOverrides,
+      diagnosticState: io.environmentDiagnosticState,
+      onDiagnostic: (message) => compatibilityDiagnostic(io, message)
+    }),
+    environmentResolved: true
+  };
+}
+
+export function parseArguments(argv) {
+  const args = [...argv];
+  const command = ['analyze', 'discover', 'research', 'analyze-version', 'eval', 'scorecard', 'benchmark', 'conformance', 'governance'].includes(args[0])
+    ? args.shift()
+    : 'discover';
+  const options = {
+    command,
+    root: '.',
+    output: command === 'analyze'
+      ? DEFAULT_REPOSITORY_IMPACT_REPORT_PATH
+      : command === 'research'
+      ? DEFAULT_KNOWLEDGE_MANIFEST_PATH
+      : command === 'analyze-version'
+        ? DEFAULT_VERSION_ANALYSIS_PATH
+        : command === 'eval'
+          ? DEFAULT_EVALUATION_REPORT_PATH
+        : command === 'scorecard'
+          ? DEFAULT_AI_SCORECARD_PATH
+        : command === 'benchmark'
+          ? DEFAULT_BENCHMARK_REPORT_PATH
+        : command === 'conformance'
+          ? DEFAULT_CONFORMANCE_REPORT_PATH
+        : command === 'governance'
+          ? DEFAULT_GOVERNANCE_DIRECTORY
+        : DEFAULT_MANIFEST_PATH,
+    dataset: DEFAULT_EVALUATION_DATASET_PATH,
+    report: DEFAULT_EVALUATION_REPORT_PATH,
+    metricsOutput: DEFAULT_METRICS_PATH,
+    config: DEFAULT_BENCHMARK_CONFIG_PATH,
+    pretty: true,
+    stdout: false,
+    failOnWarning: false,
+    failOnIncomplete: false,
+    offline: false,
+    experimentalMigrationChecklist: false,
+    targets: [],
+    progress: 'auto'
+  };
+  let rootSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--help' || argument === '-h') options.help = true;
+    else if (argument === '--version' || argument === '-v') options.version = true;
+    else if (argument === '--stdout') options.stdout = true;
+    else if (argument === '--no-pretty') options.pretty = false;
+    else if (argument === '--fail-on-warning') options.failOnWarning = true;
+    else if (argument === '--fail-on-incomplete') options.failOnIncomplete = true;
+    else if (argument === '--offline') options.offline = true;
+    else if (argument === '--target') {
+      options.targets.push(parseTargetSelector(takeValue(args, index, argument)));
+      index += 1;
+    }
+    else if (argument === '--experimental-migration-checklist') {
+      options.experimentalMigrationChecklist = true;
+    } else if (argument === '--progress') {
+      options.progress = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--migration-qualification') {
+      options.migrationQualificationPath = takeValue(args, index, argument);
+      index += 1;
+    }
+    else if (argument === '--output' || argument === '-o') {
+      options.output = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--dataset') {
+      options.dataset = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--report') {
+      options.report = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--metrics-output') {
+      options.metricsOutput = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--config') {
+      options.config = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--package') {
+      if (options.packageId !== undefined) {
+        throw new Error('--package accepts exactly one canonical package ID.');
+      }
+      options.packageId = takeValue(args, index, argument);
+      index += 1;
+    } else if (argument === '--max-depth') {
+      const raw = takeValue(args, index, argument);
+      const depth = Number(raw);
+      if (!Number.isInteger(depth) || depth < 0) throw new Error('--max-depth must be a non-negative integer');
+      options.maxDepth = depth;
+      index += 1;
+    } else if (argument.startsWith('-')) throw new Error(`Unknown option: ${argument}`);
+    else if (!rootSet && command !== 'eval' && command !== 'scorecard' && command !== 'benchmark'
+      && command !== 'conformance' && command !== 'governance') {
+      options.root = argument;
+      rootSet = true;
+    } else if (!rootSet && command === 'eval') {
+      options.dataset = argument;
+      rootSet = true;
+    } else if (!rootSet && command === 'scorecard') {
+      options.report = argument;
+      rootSet = true;
+    } else if (!rootSet && command === 'benchmark') {
+      options.config = argument;
+      rootSet = true;
+    } else if (!rootSet && command === 'conformance') {
+      throw new Error(`Unexpected argument: ${argument}`);
+    } else if (!rootSet && command === 'governance') {
+      throw new Error(`Unexpected argument: ${argument}`);
+    } else throw new Error(`Unexpected argument: ${argument}`);
+  }
+  if (!['research', 'analyze'].includes(command) && options.offline) {
+    throw new Error('--offline is only supported by research and analyze');
+  }
+  if (command !== 'analyze' && options.experimentalMigrationChecklist) {
+    throw new Error('--experimental-migration-checklist is only supported by analyze');
+  }
+  if (options.migrationQualificationPath !== undefined) {
+    if (command !== 'analyze' || !options.experimentalMigrationChecklist) {
+      throw new Error('--migration-qualification requires analyze with --experimental-migration-checklist');
+    }
+    if (!isPortableRelativePath(options.migrationQualificationPath)) {
+      throw new Error('--migration-qualification must be a portable path relative to the repository root');
+    }
+  }
+  if (command !== 'analyze' && options.progress !== 'auto') {
+    throw new Error('--progress is only supported by analyze');
+  }
+  if (!['auto', 'interactive', 'plain'].includes(options.progress)) {
+    throw new Error('--progress must be auto, interactive, or plain');
+  }
+  if (!['discover', 'analyze'].includes(command) && options.maxDepth !== undefined) {
+    throw new Error('--max-depth is only supported by discover and analyze');
+  }
+  if (command !== 'discover' && options.failOnWarning) throw new Error('--fail-on-warning is only supported by discover');
+  if (command !== 'analyze' && options.failOnIncomplete) {
+    throw new Error('--fail-on-incomplete is only supported by analyze');
+  }
+  if (!['analyze', 'analyze-version'].includes(command) && options.targets.length > 0) {
+    throw new Error('--target is only supported by analyze and analyze-version');
+  }
+  if (command !== 'discover' && !options.pretty) throw new Error('--no-pretty is only supported by discover');
+  if (command !== 'eval' && options.dataset !== DEFAULT_EVALUATION_DATASET_PATH) throw new Error('--dataset is only supported by eval');
+  if (command !== 'scorecard' && options.report !== DEFAULT_EVALUATION_REPORT_PATH) throw new Error('--report is only supported by scorecard');
+  if (command !== 'scorecard' && options.metricsOutput !== DEFAULT_METRICS_PATH) {
+    throw new Error('--metrics-output is only supported by scorecard');
+  }
+  if (command !== 'benchmark' && options.config !== DEFAULT_BENCHMARK_CONFIG_PATH) throw new Error('--config is only supported by benchmark');
+  if (command !== 'analyze-version' && options.packageId !== undefined) {
+    throw new Error('--package is only supported by analyze-version');
+  }
+  if (options.packageId !== undefined) {
+    const separator = options.packageId.indexOf(':');
+    const ecosystem = options.packageId.slice(0, separator);
+    const name = options.packageId.slice(separator + 1);
+    if (separator <= 0 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(ecosystem) || name.length === 0 || /\s/.test(name)) {
+      throw new Error('--package must be an exact canonical package ID such as npm:react or pypi:langsmith.');
+    }
+  }
+  return options;
+}
+
+async function writeProjectManifest(root, output, contents) {
+  const target = outputPath(root, output);
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, contents, 'utf8');
+  await rename(temporary, target);
+  return target;
+}
+
+function researchComponents(root, options, io) {
+  if (io.adapters) {
+    return {
+      adapters: io.adapters,
+      evidenceSourceAdapter: io.evidenceSourceAdapter ?? null
+    };
+  }
+  const clock = io.clock ?? (() => new Date());
+  const cache = createKnowledgeCache({
+    rootDirectory: path.join(root, DEFAULT_KNOWLEDGE_CACHE_DIRECTORY),
+    clock
+  });
+  const adapterOptions = { cache, clock, fetch: io.fetch, offline: options.offline };
+  return {
+    adapters: {
+      npm: createNpmRegistryAdapter(adapterOptions),
+      pypi: createPypiRegistryAdapter(adapterOptions)
+    },
+    evidenceSourceAdapter: io.evidenceSourceAdapter !== undefined
+      ? io.evidenceSourceAdapter
+      : io.defaultEvidenceEnrichment === false
+        ? null
+        : createEvidenceSourceAdapter({
+            cache,
+            clock,
+            fetch: io.fetch,
+            offline: options.offline
+          })
+  };
+}
+
+async function runResearch(options, io) {
+  const defaultEvidenceEnrichment = io.evidenceSourceAdapter !== undefined
+    || (!io.adapters && !io.fetch);
+  const runtime = options.offline || io.fetch
+    ? null
+    : (io.createHttpRuntime ?? createCliHttpRuntime)();
+  let result;
+  let primaryError;
+  try {
+    result = await executeResearch(options, {
+      ...io,
+      fetch: runtime?.fetch ?? io.fetch,
+      defaultEvidenceEnrichment
+    });
+  } catch (error) {
+    primaryError = error;
+  }
+  if (runtime) {
+    try {
+      await runtime.close();
+    } catch {
+      if (!primaryError) throw new Error('Unable to close the CLI HTTP runtime.');
+    }
+  }
+  if (primaryError) throw primaryError;
+  return result;
+}
+
+async function executeResearch(options, io) {
+  const root = path.resolve(options.root);
+  const selection = await resolveArtifactRootChain(root, [DEFAULT_MANIFEST_PATH], {
+    onDiagnostic: (message) => compatibilityDiagnostic(io, message)
+  });
+  const [projectManifestArtifact] = selection.artifacts;
+  const loaded = await loadProjectManifestInput(path.join(root, projectManifestArtifact), {
+    artifact: projectManifestArtifact
+  });
+  const plan = createResearchPlan(loaded);
+  const clock = io.clock ?? (() => new Date());
+  const components = researchComponents(root, options, io);
+  const orchestrator = createKnowledgeResearchOrchestrator({
+    adapters: components.adapters,
+    evidenceSourceAdapter: components.evidenceSourceAdapter,
+    clock,
+    concurrency: io.concurrency ?? 4
+  });
+  const result = await orchestrator.run(plan);
+  if (io.signal?.aborted) throw new PipelineCancellationError(null, io.signal.reason);
+  const manifest = (io.buildKnowledgeManifest ?? buildKnowledgeManifest)(result, {
+    policy: {
+      mode: options.offline ? 'offline' : 'online',
+      registryBases: { npm: 'https://registry.npmjs.org', pypi: 'https://pypi.org' }
+    }
+  });
+  const contents = serializeKnowledgeManifest(manifest);
+  if (options.stdout) {
+    io.stdout.write(contents);
+    return 0;
+  }
+  const manifestBytes = Buffer.from(contents, 'utf8');
+  const evidenceBundle = (io.buildKnowledgeEvidenceBundle ?? buildKnowledgeEvidenceBundle)(manifest, {
+    knowledgeManifestArtifact: options.output,
+    knowledgeManifestBytes: manifestBytes,
+    generatedAt: manifest.generatedAt,
+    enrichedEvidence: result.evidence
+  });
+  if (io.signal?.aborted) throw new PipelineCancellationError(null, io.signal.reason);
+  const target = await (io.writeKnowledgeManifest ?? writeKnowledgeManifest)(outputPath(root, options.output), manifest);
+  const evidenceTarget = await (io.writeKnowledgeEvidenceBundle ?? writeKnowledgeEvidenceBundle)(
+    outputPath(root, DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH),
+    evidenceBundle
+  );
+  io.stderr.write('✓ Loaded Project Manifest\n');
+  io.stderr.write(`✓ Planned research (${plan.packages.length} packages)\n`);
+  io.stderr.write('✓ Research complete\n');
+  io.stderr.write('✓ Knowledge Manifest validated\n');
+  io.stderr.write(`✓ Wrote:\n${target}\n`);
+  io.stderr.write(`✓ Knowledge Evidence Bundle validated\n`);
+  io.stderr.write(`✓ Wrote:\n${evidenceTarget}\n`);
+  return 0;
+}
+
+function createDefaultAiRuntime(io) {
+  const normalizedIo = withResolvedEnvironment(io);
+  const env = normalizedIo.env;
+  const providerName = env.DEPVERDICT_AI_PROVIDER ?? 'http-json';
+  if (!env.DEPVERDICT_AI_ENDPOINT) {
+    throw new Error('AI runtime is not configured. Set DEPVERDICT_AI_ENDPOINT or provide an AiRuntime.');
+  }
+  if (providerName === 'openai-compatible') {
+    const provider = createOpenAiCompatibleProvider({
+      endpoint: env.DEPVERDICT_AI_ENDPOINT,
+      model: env.DEPVERDICT_AI_MODEL,
+      authorization: env.DEPVERDICT_AI_AUTHORIZATION,
+      fetchImplementation: normalizedIo.fetch,
+      timeoutMs: configuredAiTimeoutMs(env),
+      debug: isAiRuntimeDebugEnabled(env),
+      debugWriter: normalizedIo.aiDebugWriter ?? normalizedIo.stderr ?? process.stderr
+    });
+    return createProviderAiRuntime({ provider });
+  }
+  const headers = {};
+  if (env.DEPVERDICT_AI_AUTHORIZATION) headers.authorization = env.DEPVERDICT_AI_AUTHORIZATION;
+  const provider = createHttpJsonAiProvider({
+    endpoint: env.DEPVERDICT_AI_ENDPOINT,
+    fetchImplementation: normalizedIo.fetch,
+    headers,
+    provider: providerName,
+    model: env.DEPVERDICT_AI_MODEL ?? 'unknown'
+  });
+  return createProviderAiRuntime({
+    provider,
+    promptBuilder: buildVersionAnalysisPrompt
+  });
+}
+
+function configuredAiTimeoutMs(env) {
+  const raw = env.DEPVERDICT_AI_TIMEOUT_MS;
+  if (raw === undefined) return DEFAULT_AI_TIMEOUT_MS;
+  const timeoutMs = Number(raw);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('DEPVERDICT_AI_TIMEOUT_MS must be a positive integer.');
+  }
+  return timeoutMs;
+}
+
+function failureRecoveryGuidance(stage, error) {
+  const message = error?.message ?? '';
+  const code = error?.code ?? '';
+  if (/(?:DEPVERDICT|UPGRADELENS)_AI_(?:ENDPOINT|MODEL)|AI runtime/i.test(message)) {
+    return [
+      `Stage: ${stage?.label ?? 'Version Analysis'}`,
+      'Required configuration: DEPVERDICT_AI_ENDPOINT and DEPVERDICT_AI_MODEL; authorization is optional.',
+      'Next action: configure one supported provider runtime and rerun. No credential value was printed.'
+    ];
+  }
+  if (/LINEAGE|lineage|digest mismatch|stale/i.test(`${code} ${message}`)) {
+    return [
+      `Stage: ${stage?.label ?? 'Artifact validation'}`,
+      'The input artifact chain is stale or mismatched.',
+      'Next action: rerun the upstream DepVerdict workflow to regenerate the affected artifacts.'
+    ];
+  }
+  if (code === 'ENOENT' || /ENOENT|not found|missing artifact/i.test(message)) {
+    return [
+      `Stage: ${stage?.label ?? 'Artifact loading'}`,
+      'A required upstream artifact is missing.',
+      'Next action: run `depverdict analyze <repository>` to regenerate the supported artifact chain.'
+    ];
+  }
+  return [];
+}
+
+async function executeAnalyzeVersion(options, io) {
+  io = withResolvedEnvironment(io);
+  const root = path.resolve(options.root);
+  const selection = await resolveArtifactRootChain(root, [
+    DEFAULT_MANIFEST_PATH,
+    DEFAULT_KNOWLEDGE_MANIFEST_PATH,
+    DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH
+  ], {
+    onDiagnostic: (message) => compatibilityDiagnostic(io, message)
+  });
+  const [
+    projectManifestArtifact,
+    knowledgeManifestArtifact,
+    evidenceBundleArtifact
+  ] = selection.artifacts;
+  const artifacts = await loadVersionAnalysisArtifacts({
+    projectManifest: path.join(root, projectManifestArtifact),
+    knowledgeManifest: path.join(root, knowledgeManifestArtifact),
+    evidenceBundle: path.join(root, evidenceBundleArtifact)
+  }, {
+    projectManifestArtifact,
+    knowledgeManifestArtifact,
+    evidenceBundleArtifact
+  });
+  const allInputs = resolveDependencyAnalysisInputs(artifacts);
+  let inputs = allInputs;
+  if (options.packageId !== undefined) {
+    const packageExists = artifacts.knowledgeManifest.packages.some((item) => item.id === options.packageId);
+    if (!packageExists) {
+      throw new Error(`Selected package ${options.packageId} was not found in the Knowledge Manifest; no runtime call was made.`);
+    }
+    inputs = allInputs.filter((input) => input.packageRecord.id === options.packageId);
+    if (inputs.length === 0) {
+      throw new Error(`Selected package ${options.packageId} is not eligible for Version Analysis because it has no parsed dependency occurrence; no runtime call was made.`);
+    }
+    if (inputs.length > 1) {
+      throw new Error(`Selected package ${options.packageId} matches ${inputs.length} dependency occurrences; one-dependency selection is ambiguous and no runtime call was made.`);
+    }
+  }
+  const selectedTargets = resolveTargetSelectors(inputs, options.targets ?? []);
+  const contexts = inputs.map((input) => {
+    const selected = selectedTargets.get(targetOccurrenceKey(input));
+    return buildDependencyAiContext(artifacts, {
+      input,
+      target: selected?.target ?? { policy: 'registryLatest' }
+    });
+  });
+  const needsRuntime = contexts.some((context) => context.knowledge.evidence.length > 0
+    && context.versions.analysisMode !== 'unsupportedBaseline'
+    && context.versions.targetVersion !== null);
+  const runtime = io.aiRuntime ?? (needsRuntime ? createDefaultAiRuntime(io) : null);
+  const results = [];
+  for (let index = 0; index < contexts.length; index += 1) {
+    const context = contexts[index];
+    if (io.signal?.aborted) throw new PipelineCancellationError(null, io.signal.reason);
+    try {
+      io.onProgress?.({
+        activityKind: 'WAIT_FOR_ANALYSIS_RESPONSE',
+        subject: `Waiting for analysis response: ${context.dependency.declaredName}`,
+        completed: index,
+        total: contexts.length
+      });
+    } catch {
+      // Progress callbacks are presentation-only.
+    }
+    results.push(await analyzeDependencyAiContext(context, {
+      runtime,
+      signal: io.signal
+    }));
+    if (io.signal?.aborted) throw new PipelineCancellationError(null, io.signal.reason);
+  }
+  const manifest = (io.buildVersionAnalysisManifest ?? buildVersionAnalysisManifest)({
+    input: artifacts.input,
+    contexts,
+    results,
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  const contents = serializeVersionAnalysisManifest(manifest);
+  if (options.stdout) {
+    io.stdout.write(contents);
+    return manifest;
+  }
+  const target = await (io.writeVersionAnalysisManifest ?? writeVersionAnalysisManifest)(outputPath(root, options.output), manifest);
+  io.stderr.write('✓ Loaded Project, Knowledge, and Evidence artifacts\n');
+  io.stderr.write(`✓ Built AI contexts (${contexts.length} dependencies)\n`);
+  io.stderr.write('✓ AI Version Analysis complete\n');
+  io.stderr.write('✓ Version Analysis artifact validated\n');
+  io.stderr.write(`✓ Wrote:\n${target}\n`);
+  return manifest;
+}
+
+function evaluationRuntime(options, io) {
+  if (io.aiRuntime) return {
+    runtime: io.aiRuntime,
+    model: io.model ?? { provider: 'injected', name: 'injected' }
+  };
+  const env = withResolvedEnvironment(io).env;
+  if (env.DEPVERDICT_AI_ENDPOINT) {
+    return {
+      runtime: createDefaultAiRuntime(io),
+      model: {
+        provider: env.DEPVERDICT_AI_PROVIDER ?? 'http-json',
+        name: env.DEPVERDICT_AI_MODEL ?? 'unknown'
+      }
+    };
+  }
+  return {
+    runtime: null,
+    model: { provider: 'golden-fake', name: 'golden-fake' }
+  };
+}
+
+async function executeEval(options, io) {
+  const selected = evaluationRuntime(options, io);
+  const report = await (io.runEvaluation ?? runEvaluation)({
+    datasetPath: options.dataset,
+    runtime: selected.runtime,
+    model: selected.model,
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  const contents = serializeEvaluationReport(report);
+  if (options.stdout) {
+    io.stdout.write(contents);
+    return report.summary.failed > 0 ? 2 : 0;
+  }
+  const target = await (io.writeEvaluationReport ?? writeEvaluationReport)(outputPath('.', options.output), report);
+  io.stderr.write(`✓ Loaded Golden Dataset (${report.summary.totalCases} cases)\n`);
+  io.stderr.write('✓ Evaluation complete\n');
+  io.stderr.write(`✓ Passed: ${report.summary.passed}; Failed: ${report.summary.failed}\n`);
+  io.stderr.write(`✓ Wrote:\n${target}\n`);
+  return report.summary.failed > 0 ? 2 : 0;
+}
+
+async function executeScorecard(options, io) {
+  const report = await (io.loadEvaluationReportForMetrics ?? loadEvaluationReportForMetrics)(path.resolve(options.report));
+  const metrics = (io.buildMetrics ?? buildMetrics)(report, {
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  const scorecard = (io.buildAiScorecard ?? buildAiScorecard)(metrics, {
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  if (options.stdout) {
+    io.stdout.write(serializeAiScorecard(scorecard));
+    return 0;
+  }
+  const metricsTarget = await (io.writeMetrics ?? writeMetrics)(path.resolve(options.metricsOutput), metrics);
+  const scorecardTarget = await (io.writeAiScorecard ?? writeAiScorecard)(outputPath('.', options.output), scorecard);
+  io.stderr.write(`✓ Loaded Evaluation Report (${report.summary.totalCases} cases)\n`);
+  io.stderr.write('✓ Metrics complete\n');
+  io.stderr.write(`✓ Scorecard: ${scorecard.overallScore}/100\n`);
+  io.stderr.write(`✓ Wrote metrics:\n${metricsTarget}\n`);
+  io.stderr.write(`✓ Wrote scorecard:\n${scorecardTarget}\n`);
+  return 0;
+}
+
+function benchmarkRuntimeFactory(io) {
+  return async (run, config) => {
+    if (io.benchmarkRuntimeFactory) return io.benchmarkRuntimeFactory(run, config);
+    if (run.runtime.type === 'goldenFake') return null;
+    if (run.runtime.type === 'environment') return createDefaultAiRuntime(io);
+    throw new Error(`Benchmark runtime ${run.runtime.type} is not supported by the CLI.`);
+  };
+}
+
+async function executeBenchmark(options, io) {
+  const configPath = path.resolve(options.config);
+  const config = await (io.loadBenchmarkConfig ?? loadBenchmarkConfig)(configPath);
+  const report = await (io.runBenchmark ?? runBenchmark)(config, {
+    configPath,
+    runtimeFactory: benchmarkRuntimeFactory(io),
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  const contents = serializeBenchmarkReport(report);
+  if (options.stdout) {
+    io.stdout.write(contents);
+    return 0;
+  }
+  const target = await (io.writeBenchmarkReport ?? writeBenchmarkReport)(outputPath('.', options.output), report);
+  io.stderr.write(`✓ Loaded Benchmark Config (${report.benchmark.runCount} runs)\n`);
+  io.stderr.write('✓ Benchmark complete\n');
+  io.stderr.write(`✓ Top run: ${report.ranking[0]?.runId ?? 'none'}\n`);
+  io.stderr.write(`✓ Wrote:\n${target}\n`);
+  return 0;
+}
+
+async function executeConformance(options, io) {
+  const env = withResolvedEnvironment(io).env;
+  const report = await (io.runConformance ?? runConformance)({
+    runtime: {
+      provider: env.DEPVERDICT_AI_PROVIDER ?? 'openai-compatible',
+      model: env.DEPVERDICT_AI_MODEL ?? 'offline-fixture'
+    },
+    generatedAt: io.clock ? io.clock() : new Date()
+  });
+  const contents = serializeConformanceReport(report);
+  if (options.stdout) {
+    io.stdout.write(contents);
+    return report.summary.failed > 0 ? 2 : 0;
+  }
+  const target = await (io.writeConformanceReport ?? writeConformanceReport)(
+    outputPath('.', options.output),
+    report
+  );
+  io.stderr.write(`✓ Offline conformance complete (${report.summary.total} cases)\n`);
+  io.stderr.write(`✓ Passed: ${report.summary.passed}; Failed: ${report.summary.failed}\n`);
+  io.stderr.write(`✓ Recommendation: ${report.recommendation}\n`);
+  io.stderr.write(`✓ Wrote:\n${target}\n`);
+  return report.summary.failed > 0 ? 2 : 0;
+}
+
+function governancePositiveInteger(value, fallback, name) {
+  if (value === undefined) return fallback;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+  return number;
+}
+
+async function executeGovernance(options, io) {
+  const env = withResolvedEnvironment(io).env;
+  const artifacts = (io.createDefaultGovernanceArtifacts ?? createDefaultGovernanceArtifacts)({
+    provider: env.DEPVERDICT_AI_PROVIDER ?? 'openai-compatible',
+    endpoint: env.DEPVERDICT_AI_ENDPOINT,
+    model: env.DEPVERDICT_AI_MODEL ?? 'offline-fixture',
+    timeoutSeconds: governancePositiveInteger(
+      env.DEPVERDICT_AI_TIMEOUT_SECONDS,
+      180,
+      'DEPVERDICT_AI_TIMEOUT_SECONDS'
+    ),
+    maxResponseBytes: governancePositiveInteger(
+      env.DEPVERDICT_AI_MAX_RESPONSE_BYTES,
+      1_048_576,
+      'DEPVERDICT_AI_MAX_RESPONSE_BYTES'
+    )
+  });
+  if (options.stdout) {
+    io.stdout.write(serializeGovernanceArtifacts(artifacts));
+    return 0;
+  }
+  const targets = await (io.writeGovernanceArtifacts ?? writeGovernanceArtifacts)(
+    outputPath('.', options.output),
+    artifacts
+  );
+  io.stderr.write('✓ Governance metadata validated\n');
+  io.stderr.write(`✓ Wrote ${CAPABILITY_PROFILE_FILENAME}:\n${targets.capabilityProfile}\n`);
+  io.stderr.write(`✓ Wrote ${DEPLOYMENT_PROFILE_FILENAME}:\n${targets.deploymentProfile}\n`);
+  io.stderr.write(`✓ Wrote ${QUALIFICATION_RECORD_FILENAME}:\n${targets.qualificationRecord}\n`);
+  return 0;
+}
+
+function silentStream() {
+  return Object.freeze({ write: () => true });
+}
+
+function migrationRuntimeMetadata(io) {
+  if (io.migrationRuntimeMetadata) return io.migrationRuntimeMetadata;
+  const env = withResolvedEnvironment(io).env;
+  const provider = env.DEPVERDICT_AI_PROVIDER ?? 'unknown';
+  return {
+    provider,
+    model: env.DEPVERDICT_AI_MODEL ?? 'unknown',
+    adapter: provider === 'openai-compatible' ? 'openai-compatible' : provider
+  };
+}
+
+function migrationEventListener(options, io, progress) {
+  if (!options.experimentalMigrationChecklist) return undefined;
+  return (event) => {
+    try {
+      if (event.type === 'stage:start') {
+        progress?.({
+          activityKind: 'PREPARE_MIGRATION_CONTEXTS',
+          subject: 'Prepared eligible Migration Checklist contexts',
+          completed: 0,
+          total: event.total
+        });
+      } else if (event.type === 'migration:context-start') {
+        progress?.({
+          activityKind: 'WAIT_FOR_MIGRATION_RESPONSE',
+          subject: `Waiting for migration response: ${event.packageName}`,
+          completed: event.processed,
+          total: event.total
+        });
+      } else if ([
+        'migration:context-complete',
+        'migration:abstained',
+        'migration:trust-rejected',
+        'migration:fallback'
+      ].includes(event.type)) {
+        progress?.({
+          activityKind: 'SELECT_OFFICIAL_GUIDANCE',
+          subject: `Processed migration guidance: ${event.packageName}`,
+          completed: event.processed,
+          total: event.total
+        });
+      } else if (event.type === 'migration:artifact-written') {
+        progress?.({
+          activityKind: 'WRITE_MIGRATION_ARTIFACT',
+          subject: 'Validated and wrote Migration Checklist artifact'
+        });
+      }
+    } catch {
+      // Pipeline progress remains isolated from Migration Checklist semantics.
+    }
+    try {
+      if (typeof io.migrationProgressListener === 'function') io.migrationProgressListener(event);
+    } catch {
+      // External progress observation is presentation-only.
+    }
+  };
+}
+
+export function createCliAnalysisStageRunners(options, io) {
+  const root = path.resolve(options.root);
+  const quiet = silentStream();
+  const clockOptions = io.clock ? { clock: io.clock } : {};
+  return {
+    async projectDiscovery({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const manifest = await discoverProject(root, {
+        maxDepth: options.maxDepth,
+        signal
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_PROJECT_MANIFEST',
+        subject: 'Writing Project Manifest'
+      });
+      await writeProjectManifest(root, DEFAULT_MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+      return manifest;
+    },
+    async knowledgeResearch({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      await runResearch({
+        ...options,
+        command: 'research',
+        root,
+        output: DEFAULT_KNOWLEDGE_MANIFEST_PATH,
+        stdout: false
+      }, { ...io, stdout: quiet, stderr: quiet, signal });
+      progress?.({
+        activityKind: 'WRITE_KNOWLEDGE_ARTIFACTS',
+        subject: 'Validated Knowledge Research artifacts'
+      });
+      return DEFAULT_KNOWLEDGE_MANIFEST_PATH;
+    },
+    async versionAnalysis({ progress, signal } = {}) {
+      return executeAnalyzeVersion({
+        ...options,
+        command: 'analyze-version',
+        root,
+        output: DEFAULT_VERSION_ANALYSIS_PATH,
+        stdout: false,
+        packageId: undefined
+      }, { ...io, stdout: quiet, stderr: quiet, signal, onProgress: progress });
+    },
+    async usageDiscovery({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const usageIndex = await runUsageDiscovery({
+        repositoryRoot: root,
+        maxDepth: options.maxDepth,
+        signal,
+        ...clockOptions
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_USAGE_INDEX',
+        subject: 'Writing Repository Usage Index'
+      });
+      await writeUsageIndex(path.join(root, DEFAULT_USAGE_INDEX_PATH), usageIndex);
+      return usageIndex;
+    },
+    async impactAnalysis({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const repositoryImpact = await runImpactAnalysis({
+        sources: {
+          projectManifest: path.join(root, DEFAULT_MANIFEST_PATH),
+          versionAnalysis: path.join(root, DEFAULT_VERSION_ANALYSIS_PATH),
+          usageIndex: path.join(root, DEFAULT_USAGE_INDEX_PATH)
+        },
+        ...clockOptions
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_REPOSITORY_IMPACT',
+        subject: 'Writing Repository Impact artifact'
+      });
+      await writeRepositoryImpact(path.join(root, DEFAULT_REPOSITORY_IMPACT_PATH), repositoryImpact);
+      return repositoryImpact;
+    },
+    async impactEvidence({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const impactEvidence = await runImpactEvidenceGeneration({
+        sources: {
+          projectManifest: path.join(root, DEFAULT_MANIFEST_PATH),
+          versionAnalysis: path.join(root, DEFAULT_VERSION_ANALYSIS_PATH),
+          usageIndex: path.join(root, DEFAULT_USAGE_INDEX_PATH),
+          repositoryImpact: path.join(root, DEFAULT_REPOSITORY_IMPACT_PATH)
+        },
+        ...clockOptions
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_IMPACT_EVIDENCE',
+        subject: 'Writing Repository Impact Evidence artifact'
+      });
+      await writeRepositoryImpactEvidence(
+        path.join(root, DEFAULT_REPOSITORY_IMPACT_EVIDENCE_PATH),
+        impactEvidence
+      );
+      return impactEvidence;
+    },
+    async upgradeDecision({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const decision = await (io.runUpgradeDecisionStage ?? runUpgradeDecisionStage)({
+        repositoryRoot: root,
+        artifactPath: DEFAULT_UPGRADE_DECISION_PATH,
+        onCompatibilityDiagnostic: (message) => compatibilityDiagnostic(io, message)
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_UPGRADE_DECISION',
+        subject: 'Writing deterministic Upgrade Decision artifact'
+      });
+      return decision;
+    },
+    async migrationChecklist({ progress, signal } = {}) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const onMigrationEvent = migrationEventListener(options, io, progress);
+      const runtimeMetadata = migrationRuntimeMetadata(io);
+      const resolver = io.resolveMigrationQualification ?? resolveMigrationQualification;
+      const qualificationOptions = {
+        repositoryRoot: root,
+        runtimeMetadata,
+        allowExperimental: true,
+        qualificationPath: options.migrationQualificationPath,
+        onCompatibilityDiagnostic: (message) => compatibilityDiagnostic(io, message)
+      };
+      if (Object.hasOwn(io, 'migrationQualification')) {
+        qualificationOptions.qualification = io.migrationQualification;
+      }
+      const qualificationDecision = await resolver(qualificationOptions);
+      return (io.runMigrationChecklistStage ?? runMigrationChecklistStage)({
+        repositoryRoot: root,
+        aiRuntime: io.migrationAiRuntime ?? io.aiRuntime ?? null,
+        createAiRuntime: () => createDefaultAiRuntime(io),
+        runtimeMetadata,
+        qualificationDecision,
+        allowExperimental: true,
+        generatedAt: io.clock ? io.clock() : new Date(),
+        artifactPath: DEFAULT_MIGRATION_CHECKLIST_PATH,
+        onCompatibilityDiagnostic: (message) => compatibilityDiagnostic(io, message),
+        onEvent: onMigrationEvent,
+        signal
+      });
+    },
+    async markdownReport({ artifacts, progress, signal }) {
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      const viewModel = buildImpactPresentationViewModel({
+        projectManifest: artifacts.projectDiscovery,
+        versionAnalysis: artifacts.versionAnalysis,
+        repositoryImpact: artifacts.impactAnalysis,
+        impactEvidence: artifacts.impactEvidence
+      });
+      const completion = buildProductCompletion({
+        upgradeDecision: artifacts.upgradeDecision,
+        versionAnalysis: artifacts.versionAnalysis,
+        migrationChecklistViewModel: artifacts.migrationChecklist?.viewModel,
+        artifactPaths: {
+          report: options.output,
+          upgradeDecision: DEFAULT_UPGRADE_DECISION_PATH,
+          migrationChecklist: artifacts.migrationChecklist?.artifactPath ?? null
+        }
+      });
+      const contents = renderMarkdownReport({
+        viewModel,
+        upgradeDecision: artifacts.upgradeDecision,
+        migrationChecklistViewModel: artifacts.migrationChecklist?.viewModel,
+        completion
+      });
+      if (signal?.aborted) throw new PipelineCancellationError(null, signal.reason);
+      progress?.({
+        activityKind: 'WRITE_MARKDOWN_REPORT',
+        subject: 'Writing Markdown report'
+      });
+      const target = await (io.writeMarkdownReport ?? writeTextArtifact)(
+        outputPath(root, options.output),
+        contents
+      );
+      return Object.freeze({
+        target,
+        viewModel,
+        completion,
+        migrationChecklistViewModel: artifacts.migrationChecklist?.viewModel ?? null
+      });
+    }
+  };
+}
+
+export async function executeAnalyze(options, io) {
+  io = withResolvedEnvironment(io);
+  const root = path.resolve(options.root);
+  const runners = {
+    ...createCliAnalysisStageRunners(options, io),
+    ...io.analysisStageRunners
+  };
+  const env = io.env ?? process.env;
+  const progressReporter = io.progressReporter ?? createProgressReporter(io.stderr, {
+    mode: options.progress,
+    noColor: Object.hasOwn(env, 'NO_COLOR')
+  });
+  const abortController = io.signal ? null : (io.abortController ?? new AbortController());
+  const signal = io.signal ?? abortController.signal;
+  const signalHost = io.signalHost ?? process;
+  const installSignalHandler = !io.signal && io.handleSignals !== false
+    && typeof signalHost?.once === 'function';
+  const onSigint = () => {
+    if (!abortController.signal.aborted) {
+      abortController.abort(new Error('User requested cancellation.'));
+    }
+  };
+  if (installSignalHandler) signalHost.once('SIGINT', onSigint);
+  const progressOptions = {};
+  if (io.progressMonotonicClock) progressOptions.monotonicClock = io.progressMonotonicClock;
+  if (io.progressWallClock) progressOptions.wallClock = io.progressWallClock;
+  if (io.progressScheduler) progressOptions.scheduler = io.progressScheduler;
+  if (io.heartbeatIntervalMs !== undefined) {
+    progressOptions.heartbeatIntervalMs = io.heartbeatIntervalMs;
+  }
+  let result;
+  try {
+    result = await (io.runAnalysisPipeline ?? runAnalysisPipeline)({
+      repositoryRoot: root,
+      runners,
+      progressReporter,
+      progressListener: io.progressListener,
+      progressOptions,
+      signal,
+      stages: createAnalysisStages({
+        migrationChecklist: options.experimentalMigrationChecklist
+      })
+    });
+  } catch (error) {
+    if (error instanceof PipelineCancellationError || signal.aborted) {
+      io.stderr.write(
+        `\n${PRODUCT_NAME} product outcome: CANCELLED\n`
+        + 'Next action: rerun when you are ready; no successful completion was published.\n'
+      );
+      return 130;
+    }
+    if (!(error instanceof PipelineStageError)) throw error;
+    let logTarget;
+    try {
+      logTarget = await (io.writeAnalysisFailureLog ?? writeAnalysisFailureLog)(root, error);
+    } catch {
+      io.stderr.write(
+        `\n${PRODUCT_NAME} product outcome: FAILED\n${error.stage.label} failed.\n\n`
+        + 'Unable to write analysis log.\n'
+      );
+      return 1;
+    }
+    const displayLog = path.relative(root, logTarget).split(path.sep).join('/');
+    const decision = error.cause?.decision;
+    if (decision) {
+      const lines = [
+        '',
+        `${PRODUCT_NAME} product outcome: FAILED`,
+        `${error.stage.label} failed.`,
+        '',
+        `Qualification status: ${decision.status}`,
+        `Reason: ${decision.reasonCode}`,
+        `Qualification source: ${decision.sourceKind}`,
+        `Expected runtime: ${decision.runtimeIdentity.provider} / ${decision.runtimeIdentity.model} / ${decision.runtimeIdentity.adapter}`
+      ];
+      if (decision.sourcePath) lines.push(`Qualification path: ${decision.sourcePath}`);
+      if (decision.recordRuntimeIdentity) {
+        lines.push(
+          `Record runtime: ${decision.recordRuntimeIdentity.provider} / ${decision.recordRuntimeIdentity.model} / ${decision.recordRuntimeIdentity.adapter}`
+        );
+      }
+      lines.push(`Next action: ${decision.nextAction}`, '', 'See:', displayLog || DEFAULT_ANALYSIS_LOG_PATH);
+      io.stderr.write(`${lines.join('\n')}\n`);
+    } else {
+      const guidance = failureRecoveryGuidance(error.stage, error.cause);
+      const guidanceText = guidance.length > 0 ? `\n${guidance.join('\n')}\n` : '';
+      io.stderr.write(
+        `\n${PRODUCT_NAME} product outcome: FAILED\n${error.stage.label} failed.\n`
+        + `${guidanceText}\nSee:\n`
+        + `${displayLog || DEFAULT_ANALYSIS_LOG_PATH}\n`
+      );
+    }
+    return 1;
+  } finally {
+    if (installSignalHandler) signalHost.removeListener?.('SIGINT', onSigint);
+  }
+
+  const completion = result.artifacts.markdownReport.completion;
+  if (options.stdout) {
+    io.stdout.write(`${JSON.stringify(completion, null, 2)}\n`);
+  } else {
+    io.stdout.write(renderConsoleSummary({
+      viewModel: result.artifacts.markdownReport.viewModel,
+      completion,
+      reportPath: options.output,
+      upgradeDecision: result.artifacts.upgradeDecision,
+      upgradeDecisionPath: DEFAULT_UPGRADE_DECISION_PATH,
+      migrationChecklistViewModel: result.artifacts.migrationChecklist?.viewModel,
+      migrationChecklistPath: result.artifacts.migrationChecklist?.artifactPath
+    }));
+  }
+  return productCompletionExitCode(completion, { strict: options.failOnIncomplete });
+}
+
+export async function runCli(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const invocationName = io.invocationName ?? CLI_NAME;
+  const deprecationState = io.deprecationState ?? legacyInvocationWarnings;
+  if (invocationName === 'upgradelens' && !deprecationState.has('legacy-cli')) {
+    deprecationState.add('legacy-cli');
+    stderr.write(
+      'The `upgradelens` command is deprecated and will be removed after the '
+      + '0.6.x preview compatibility window. Use `depverdict` instead.\n'
+    );
+  }
+  try {
+    const options = parseArguments(argv);
+    if (options.help) {
+      stdout.write(HELP);
+      return 0;
+    }
+    if (options.version) {
+      stdout.write(`${VERSION}\n`);
+      return 0;
+    }
+    const commandIo = [
+      'analyze',
+      'analyze-version',
+      'eval',
+      'benchmark',
+      'conformance',
+      'governance'
+    ].includes(options.command)
+      ? withResolvedEnvironment({ ...io, stdout, stderr })
+      : { ...io, stdout, stderr };
+    if (options.command === 'analyze') return await executeAnalyze(options, commandIo);
+    if (options.command === 'research') return await runResearch(options, { ...io, stdout, stderr });
+    if (options.command === 'analyze-version') {
+      await executeAnalyzeVersion(options, commandIo);
+      return 0;
+    }
+    if (options.command === 'eval') return await executeEval(options, commandIo);
+    if (options.command === 'scorecard') return await executeScorecard(options, { ...io, stdout, stderr });
+    if (options.command === 'benchmark') return await executeBenchmark(options, commandIo);
+    if (options.command === 'conformance') return await executeConformance(options, commandIo);
+    if (options.command === 'governance') return await executeGovernance(options, commandIo);
+
+    const manifest = await discoverProject(options.root, { maxDepth: options.maxDepth });
+    const contents = `${JSON.stringify(manifest, null, options.pretty ? 2 : 0)}\n`;
+    if (options.stdout) stdout.write(contents);
+    else {
+      const target = await writeProjectManifest(options.root, options.output, contents);
+      stderr.write(`Discovered ${manifest.summary.projectCount} project(s).\n`);
+      stderr.write(`Manifest: ${target}\n`);
+      if (manifest.warnings.length) stderr.write(`Warnings: ${manifest.warnings.length}\n`);
+    }
+    return options.failOnWarning && manifest.warnings.length > 0 ? 2 : 0;
+  } catch (error) {
+    const guidance = failureRecoveryGuidance(null, error);
+    stderr.write(
+      `${CLI_NAME}: ${error.message}\n`
+      + (guidance.length > 0 ? `${guidance.join('\n')}\n` : '')
+    );
+    return 1;
+  }
+}
+
+export { HELP };