@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/migration-checklist/qualification-store.js

@@ -0,0 +1,225 @@
+import { createHash } from 'node:crypto';
+import {
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm
+} from 'node:fs/promises';
+import path from 'node:path';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { canonicalJsonBytes } from '../canonical-json.js';
+import {
+  DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH
+} from '../constants.js';
+import { compareText, isPortableRelativePath, isSorted } from '../portable.js';
+
+const schema = JSON.parse(await readFile(
+  new URL('../../schemas/migration-planning-qualification-record.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+export const MIGRATION_PLANNING_QUALIFICATION_RECORD_SCHEMA_VERSION = '1.0.0';
+
+export class MigrationQualificationStoreError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'MigrationQualificationStoreError';
+    this.code = code;
+  }
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function digest(value) {
+  return `sha256:${createHash('sha256').update(canonicalJsonBytes(value)).digest('hex')}`;
+}
+
+function recordMaterial(record) {
+  return {
+    schemaVersion: record.schemaVersion,
+    qualification: record.qualification
+  };
+}
+
+function duplicate(values) {
+  return values.find((value, index) => values.indexOf(value) !== index) ?? null;
+}
+
+function containsSensitiveValue(value) {
+  if (typeof value === 'string') {
+    return /(?:\bBearer\s+\S+|\bsk-[A-Za-z0-9_-]{8,}|(?:api[_ -]?key|access[_ -]?token|authorization|client[_ -]?secret)\s*[:=])/i.test(value)
+      || /https?:\/\/[^/\s:@]+:[^/\s@]+@/i.test(value);
+  }
+  if (Array.isArray(value)) return value.some(containsSensitiveValue);
+  if (value && typeof value === 'object') return Object.values(value).some(containsSensitiveValue);
+  return false;
+}
+
+function invariantErrors(record) {
+  const errors = [];
+  const qualification = record.qualification;
+  if (qualification.qualificationId !== digest(qualification.identity)) {
+    errors.push('qualificationId does not match the exact qualification identity.');
+  }
+  if (record.recordDigest !== digest(recordMaterial(record))) {
+    errors.push('recordDigest does not match the canonical persisted qualification material.');
+  }
+  const duplicateMetric = duplicate(qualification.thresholdResults.map((item) => item.metric));
+  if (duplicateMetric) errors.push(`duplicate threshold metric ${duplicateMetric}.`);
+  const duplicateGate = duplicate(qualification.criticalGates.map((item) => item.id));
+  if (duplicateGate) errors.push(`duplicate critical gate ${duplicateGate}.`);
+  if (!isSorted(qualification.limitations, (left, right) => (
+    compareText(left.code, right.code) || compareText(left.message, right.message)
+  ))) {
+    errors.push('limitations must use deterministic code/message ordering.');
+  }
+  for (const field of ['observedProviders', 'observedModels']) {
+    if (!isSorted(qualification.identity.runtime[field], compareText)) {
+      errors.push(`runtime.${field} must be sorted.`);
+    }
+  }
+  const criticalFailure = qualification.criticalGates.some((item) => !item.passed)
+    || qualification.thresholdResults.some((item) => item.critical && !item.passed);
+  if (qualification.verdict === 'NOT_QUALIFIED' && !criticalFailure) {
+    errors.push('NOT_QUALIFIED requires a failed critical gate or threshold.');
+  }
+  if (['QUALIFIED', 'QUALIFIED_WITH_LIMITATIONS', 'INSUFFICIENT_EVIDENCE'].includes(
+    qualification.verdict
+  ) && criticalFailure) {
+    errors.push(`${qualification.verdict} cannot contain a failed critical gate or threshold.`);
+  }
+  if (qualification.verdict === 'QUALIFIED' && qualification.limitations.length > 0) {
+    errors.push('QUALIFIED cannot contain qualification limitations.');
+  }
+  if (qualification.verdict === 'QUALIFIED_WITH_LIMITATIONS'
+      && qualification.limitations.length === 0) {
+    errors.push('QUALIFIED_WITH_LIMITATIONS requires at least one limitation.');
+  }
+  if (containsSensitiveValue(record)) {
+    errors.push('qualification record contains a secret-like value.');
+  }
+  return errors;
+}
+
+export function validateMigrationPlanningQualificationRecordSchema(record) {
+  if (!validateSchema(record)) {
+    throw new MigrationQualificationStoreError(
+      'MIGRATION_QUALIFICATION_RECORD_SCHEMA_INVALID',
+      'Migration Planning qualification record failed strict schema validation.'
+    );
+  }
+  return record;
+}
+
+export function validateMigrationPlanningQualificationRecord(record) {
+  validateMigrationPlanningQualificationRecordSchema(record);
+  const errors = invariantErrors(record);
+  if (errors.length > 0) {
+    const code = errors.some((item) => item.includes('secret-like'))
+      ? 'MIGRATION_QUALIFICATION_RECORD_SENSITIVE'
+      : 'MIGRATION_QUALIFICATION_RECORD_INTEGRITY_INVALID';
+    throw new MigrationQualificationStoreError(
+      code,
+      'Migration Planning qualification record failed integrity validation.'
+    );
+  }
+  return record;
+}
+
+export function buildMigrationPlanningQualificationRecord(qualification) {
+  const record = {
+    schemaVersion: MIGRATION_PLANNING_QUALIFICATION_RECORD_SCHEMA_VERSION,
+    recordDigest: `sha256:${'0'.repeat(64)}`,
+    qualification: structuredClone(qualification)
+  };
+  record.recordDigest = digest(recordMaterial(record));
+  return deepFreeze(validateMigrationPlanningQualificationRecord(record));
+}
+
+export function serializeMigrationPlanningQualificationRecord(record) {
+  validateMigrationPlanningQualificationRecord(record);
+  return `${JSON.stringify(record, null, 2)}\n`;
+}
+
+function artifactTarget(repositoryRoot, artifactPath) {
+  if (!isPortableRelativePath(artifactPath)) {
+    throw new MigrationQualificationStoreError(
+      'MIGRATION_QUALIFICATION_PATH_INVALID',
+      'Migration Planning qualification path must be portable and relative to the repository root.'
+    );
+  }
+  return path.resolve(repositoryRoot, artifactPath);
+}
+
+export async function loadMigrationPlanningQualificationRecord(repositoryRoot, {
+  artifactPath = DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH,
+  readArtifact = readFile
+} = {}) {
+  const target = artifactTarget(repositoryRoot, artifactPath);
+  let bytes;
+  try {
+    bytes = await readArtifact(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new MigrationQualificationStoreError(
+        'MIGRATION_QUALIFICATION_RECORD_MISSING',
+        `Migration Planning qualification record was not found at ${artifactPath}.`
+      );
+    }
+    throw new MigrationQualificationStoreError(
+      'MIGRATION_QUALIFICATION_RECORD_UNREADABLE',
+      `Migration Planning qualification record could not be read at ${artifactPath}.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(bytes).toString('utf8'));
+  } catch {
+    throw new MigrationQualificationStoreError(
+      'MIGRATION_QUALIFICATION_RECORD_INVALID_JSON',
+      'Migration Planning qualification record is not valid JSON.'
+    );
+  }
+  return deepFreeze(validateMigrationPlanningQualificationRecord(parsed));
+}
+
+export async function writeMigrationPlanningQualificationRecord(
+  repositoryRoot,
+  qualification,
+  {
+    artifactPath = DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH
+  } = {}
+) {
+  const record = buildMigrationPlanningQualificationRecord(qualification);
+  const target = artifactTarget(repositoryRoot, artifactPath);
+  const temporary = `${target}.${process.pid}.tmp`;
+  await mkdir(path.dirname(target), { recursive: true });
+  let handle;
+  try {
+    handle = await open(temporary, 'w', 0o600);
+    await handle.writeFile(serializeMigrationPlanningQualificationRecord(record), 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, target);
+  } catch {
+    await handle?.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+    throw new MigrationQualificationStoreError(
+      'MIGRATION_QUALIFICATION_RECORD_WRITE_FAILED',
+      `Migration Planning qualification record could not be written at ${artifactPath}.`
+    );
+  }
+  return artifactPath;
+}

package/src/migration-checklist/runtime.js

@@ -0,0 +1,205 @@
+import { DEFAULT_MIGRATION_CHECKLIST_PATH } from '../constants.js';
+import { assembleMigrationChecklist } from './assembler.js';
+import { prepareMigrationChecklistContexts } from './context-runtime.js';
+import { generateMigrationExtractiveChecklistDrafts } from './generator.js';
+import { buildMigrationChecklistViewModel } from './presentation.js';
+import {
+  decideMigrationQualification,
+  migrationQualificationErrorForDecision
+} from './qualification-guard.js';
+import { writeMigrationChecklist } from './writer.js';
+
+export const MIGRATION_CHECKLIST_STAGE_ID = 'migrationChecklist';
+export const MIGRATION_CHECKLIST_STAGE_LABEL = 'Migration Checklist';
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function emit(listener, event) {
+  if (!listener) return;
+  try {
+    if (typeof listener === 'function') listener(deepFreeze(structuredClone(event)));
+    else listener.handle?.(deepFreeze(structuredClone(event)));
+  } catch {
+    // Operational presentation cannot affect business output.
+  }
+}
+
+function failureCode(error) {
+  if (typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(error.code)) return error.code;
+  if (/lineage/i.test(error?.message ?? '')) return 'LINEAGE_INVALID';
+  if (/schema|validation/i.test(error?.message ?? '')) return 'ARTIFACT_VALIDATION_FAILED';
+  return 'MIGRATION_CHECKLIST_STAGE_FAILED';
+}
+
+function eventTypeForResult(event) {
+  if (event.outcome === 'generated') return 'migration:context-complete';
+  if (event.outcome === 'abstained') return 'migration:abstained';
+  if (event.reasonCode === 'TRUST_VALIDATION_REJECTED') return 'migration:trust-rejected';
+  return 'migration:fallback';
+}
+
+function throwIfCancelled(signal) {
+  if (!signal?.aborted) return;
+  const error = new Error('Migration Checklist stage was cancelled.', { cause: signal.reason });
+  error.code = 'ANALYSIS_CANCELLED';
+  throw error;
+}
+
+/**
+ * Experimental application stage: validated artifacts + Upgrade Decision -> MP-02 ->
+ * v2 guard -> extractive generator -> MP-01 assembly -> atomic artifact -> presentation view model.
+ */
+export async function runMigrationChecklistStage({
+  repositoryRoot,
+  aiRuntime,
+  createAiRuntime,
+  runtimeMetadata,
+  qualification = null,
+  qualificationDecision = null,
+  allowExperimental = false,
+  generatedAt,
+  artifactPath = DEFAULT_MIGRATION_CHECKLIST_PATH,
+  onCompatibilityDiagnostic,
+  onEvent,
+  signal,
+  prepareContexts = prepareMigrationChecklistContexts,
+  generateDrafts = generateMigrationExtractiveChecklistDrafts,
+  assemble = assembleMigrationChecklist,
+  writeArtifact = writeMigrationChecklist
+}) {
+  let total = 0;
+  let processed = 0;
+  let qualificationResult;
+  try {
+    throwIfCancelled(signal);
+    qualificationResult = qualificationDecision ?? await decideMigrationQualification({
+      qualification,
+      runtimeMetadata,
+      allowExperimental,
+      sourceKind: qualification ? 'injected' : 'none'
+    });
+    if (!qualificationResult.executionAllowed) {
+      throw migrationQualificationErrorForDecision(qualificationResult);
+    }
+    throwIfCancelled(signal);
+    const prepared = await prepareContexts(repositoryRoot, {
+      onCompatibilityDiagnostic
+    });
+    throwIfCancelled(signal);
+    total = prepared.eligibleContexts.length;
+    emit(onEvent, {
+      type: 'stage:start',
+      stageId: MIGRATION_CHECKLIST_STAGE_ID,
+      total,
+      qualificationStatus: qualificationResult.status,
+      qualificationId: qualificationResult.qualificationId,
+      experimentalOverrideUsed: qualificationResult.experimentalOverrideUsed
+    });
+    emit(onEvent, {
+      type: 'stage:progress',
+      stageId: MIGRATION_CHECKLIST_STAGE_ID,
+      processed,
+      total,
+      qualificationStatus: qualificationResult.status,
+      qualificationId: qualificationResult.qualificationId,
+      experimentalOverrideUsed: qualificationResult.experimentalOverrideUsed
+    });
+    const activeRuntime = aiRuntime ?? (total > 0 ? createAiRuntime?.() : {
+      async generateStructured() {
+        throw new Error('No eligible migration context should invoke the AI runtime.');
+      }
+    });
+    const generation = await generateDrafts(prepared, {
+      aiRuntime: activeRuntime,
+      signal,
+      onContextEvent(event) {
+        if (event.phase === 'start') {
+          emit(onEvent, {
+            type: 'migration:context-start',
+            stageId: MIGRATION_CHECKLIST_STAGE_ID,
+            packageName: event.packageName,
+            processed,
+            total
+          });
+          return;
+        }
+        processed += 1;
+        emit(onEvent, {
+          type: eventTypeForResult(event),
+          stageId: MIGRATION_CHECKLIST_STAGE_ID,
+          packageName: event.packageName,
+          processed,
+          total,
+          outcome: event.outcome,
+          reasonCode: event.reasonCode,
+          detailCode: event.detailCode
+        });
+        emit(onEvent, {
+          type: 'stage:progress',
+          stageId: MIGRATION_CHECKLIST_STAGE_ID,
+          processed,
+          total,
+          qualificationStatus: qualificationResult.status,
+          qualificationId: qualificationResult.qualificationId,
+          experimentalOverrideUsed: qualificationResult.experimentalOverrideUsed
+        });
+      }
+    });
+    throwIfCancelled(signal);
+    const checklist = assemble({
+      prepared,
+      generation,
+      qualification: qualificationResult,
+      generatedAt
+    });
+    throwIfCancelled(signal);
+    const outputPath = await writeArtifact(repositoryRoot, checklist, { artifactPath });
+    emit(onEvent, {
+      type: 'migration:artifact-written',
+      stageId: MIGRATION_CHECKLIST_STAGE_ID,
+      artifactPath: outputPath
+    });
+    const viewModel = buildMigrationChecklistViewModel(checklist, {
+      qualificationDecision: qualificationResult
+    });
+    emit(onEvent, {
+      type: 'stage:complete',
+      stageId: MIGRATION_CHECKLIST_STAGE_ID,
+      processed,
+      total,
+      generated: generation.summary.generated,
+      abstained: generation.summary.abstained,
+      rejected: generation.summary.rejected,
+      failed: generation.summary.failed,
+      limitationCount: checklist.summary.limitationCount,
+      qualificationStatus: qualificationResult.status,
+      qualificationId: qualificationResult.qualificationId,
+      experimentalOverrideUsed: qualificationResult.experimentalOverrideUsed
+    });
+    return deepFreeze({
+      artifactPath: outputPath,
+      checklist,
+      viewModel,
+      prepared,
+      generation,
+      qualification: qualificationResult
+    });
+  } catch (error) {
+    qualificationResult ??= error?.decision ?? null;
+    emit(onEvent, {
+      type: signal?.aborted ? 'stage:cancelled' : 'stage:failed',
+      stageId: MIGRATION_CHECKLIST_STAGE_ID,
+      processed,
+      total,
+      reasonCode: signal?.aborted ? 'USER_CANCELLED' : failureCode(error),
+      qualificationStatus: qualificationResult?.status ?? 'UNKNOWN',
+      qualificationId: qualificationResult?.qualificationId ?? null,
+      experimentalOverrideUsed: qualificationResult?.experimentalOverrideUsed ?? false
+    });
+    throw error;
+  }
+}

package/src/migration-checklist/verification.js

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { canonicalJsonBytes } from '../canonical-json.js';
+import { compareText, isPortableRelativePath } from '../portable.js';
+
+export const MIGRATION_VERIFICATION_STATUSES = Object.freeze([
+  'AVAILABLE',
+  'VERIFICATION_COMMAND_UNAVAILABLE',
+  'NOT_APPLICABLE'
+]);
+
+const SCRIPT_ROLES = Object.freeze({
+  build: 'BUILD',
+  check: 'CHECK',
+  lint: 'LINT',
+  test: 'TEST',
+  typecheck: 'TYPECHECK'
+});
+const PACKAGE_MANAGER_COMMANDS = Object.freeze({
+  bun: (name) => `bun run ${name}`,
+  npm: (name) => `npm run ${name}`,
+  pnpm: (name) => `pnpm run ${name}`,
+  yarn: (name) => `yarn run ${name}`
+});
+const SAFE_SCRIPT_NAME = /^[A-Za-z0-9:_-]+$/;
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function commandId(value) {
+  return `sha256:${createHash('sha256').update(canonicalJsonBytes(value)).digest('hex')}`;
+}
+
+function unavailable() {
+  return {
+    status: 'VERIFICATION_COMMAND_UNAVAILABLE',
+    commands: [],
+    limitation: {
+      code: 'VERIFICATION_COMMAND_UNAVAILABLE',
+      message: 'No supported project-derived verification command was found.'
+    }
+  };
+}
+
+function manifestPaths(project) {
+  return [...new Set([
+    ...project.manifests,
+    ...project.dependencies.map((dependency) => dependency.manifest)
+  ])].filter((value) => value.endsWith('package.json')).sort(compareText);
+}
+
+function commandRecords(project, sourcePath, sourceDigest, manifest) {
+  const packageManager = project.packageManager?.name;
+  const renderCommand = PACKAGE_MANAGER_COMMANDS[packageManager];
+  if (!renderCommand || !manifest.scripts || typeof manifest.scripts !== 'object'
+      || Array.isArray(manifest.scripts)) {
+    return [];
+  }
+  const workingDirectory = project.path;
+  return Object.entries(SCRIPT_ROLES)
+    .filter(([scriptName]) => (
+      SAFE_SCRIPT_NAME.test(scriptName)
+      && typeof manifest.scripts[scriptName] === 'string'
+      && manifest.scripts[scriptName].trim().length > 0
+    ))
+    .map(([scriptName, role]) => {
+      const core = {
+        role,
+        command: renderCommand(scriptName),
+        workingDirectory,
+        source: {
+          path: sourcePath,
+          contentDigest: sourceDigest,
+          scriptName,
+          packageManager
+        }
+      };
+      return { id: commandId(core), ...core };
+    });
+}
+
+/**
+ * Read only Project Manifest-declared Node package manifests and project safe
+ * script keys. Script bodies are neither parsed nor copied into the handoff.
+ */
+export async function extractProjectVerification(repositoryRoot, projectManifest, {
+  readArtifact = readFile
+} = {}) {
+  const byProject = new Map();
+  for (const project of projectManifest.projects) {
+    const commands = [];
+    if (project.ecosystem === 'node' && typeof repositoryRoot === 'string') {
+      for (const sourcePath of manifestPaths(project)) {
+        if (!isPortableRelativePath(sourcePath)) continue;
+        let bytes;
+        try {
+          bytes = await readArtifact(path.resolve(repositoryRoot, sourcePath));
+        } catch {
+          continue;
+        }
+        let manifest;
+        try {
+          manifest = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        } catch {
+          continue;
+        }
+        commands.push(...commandRecords(
+          project,
+          sourcePath,
+          digest(Buffer.from(bytes)),
+          manifest
+        ));
+      }
+    }
+    const unique = new Map(commands.map((command) => [command.id, command]));
+    const normalized = [...unique.values()].sort((left, right) => (
+      compareText(left.role, right.role)
+      || compareText(left.workingDirectory, right.workingDirectory)
+      || compareText(left.command, right.command)
+      || compareText(left.id, right.id)
+    ));
+    byProject.set(project.id, normalized.length > 0
+      ? { status: 'AVAILABLE', commands: normalized, limitation: null }
+      : unavailable());
+  }
+  return byProject;
+}
+
+export function unavailableProjectVerification() {
+  return unavailable();
+}

package/src/migration-checklist/writer.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+
+import { DEFAULT_MIGRATION_CHECKLIST_PATH } from '../constants.js';
+import { writeTextArtifact } from '../orchestration/text-writer.js';
+import { isPortableRelativePath } from '../portable.js';
+import { serializeMigrationChecklist, validateMigrationChecklist } from './migration-checklist.js';
+
+export class MigrationChecklistWriterError extends Error {
+  constructor(message, cause) {
+    super(message, { cause });
+    this.name = 'MigrationChecklistWriterError';
+    this.code = 'MIGRATION_CHECKLIST_WRITE_FAILED';
+  }
+}
+
+/** Validate first, then atomically publish deterministic bytes and return a portable path. */
+export async function writeMigrationChecklist(repositoryRoot, checklist, {
+  artifactPath = DEFAULT_MIGRATION_CHECKLIST_PATH,
+  writeArtifact = writeTextArtifact
+} = {}) {
+  if (!isPortableRelativePath(artifactPath)) {
+    throw new TypeError('Migration Checklist artifact path must be portable and repository-relative.');
+  }
+  validateMigrationChecklist(checklist);
+  const contents = serializeMigrationChecklist(checklist);
+  try {
+    await writeArtifact(path.resolve(repositoryRoot, artifactPath), contents);
+  } catch (cause) {
+    throw new MigrationChecklistWriterError(
+      `Unable to write Migration Checklist artifact ${artifactPath}.`,
+      cause
+    );
+  }
+  return artifactPath.split(path.sep).join('/');
+}