@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/migration-checklist/presentation.js

@@ -0,0 +1,292 @@
+import { canonicalJson } from '../canonical-json.js';
+import { compareText } from '../portable.js';
+import { validateMigrationChecklist } from './migration-checklist.js';
+
+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 inlineCode(value) {
+  return `\`${String(value).replaceAll('`', '\\`')}\``;
+}
+
+function headingText(value) {
+  return String(value).replace(/[\r\n]+/g, ' ').replaceAll('\\', '\\\\').replaceAll('#', '\\#');
+}
+
+function qualificationPresentation(decision, checklist) {
+  if (!decision || typeof decision.status !== 'string'
+      || typeof decision.executionAllowed !== 'boolean'
+      || !Array.isArray(decision.limitations)) {
+    throw new TypeError('Migration Checklist presentation requires a normalized qualification decision.');
+  }
+  if (!decision.executionAllowed) {
+    throw new TypeError('Migration Checklist presentation cannot render a blocked qualification decision.');
+  }
+  if (canonicalJson(decision.limitations) !== canonicalJson(checklist.limitations)) {
+    throw new TypeError('Migration Checklist qualification decision and artifact limitations do not match.');
+  }
+  return {
+    status: decision.status,
+    qualificationId: decision.qualificationId,
+    sourceKind: decision.sourceKind,
+    sourcePath: decision.sourcePath,
+    runtimeIdentity: structuredClone(decision.runtimeIdentity),
+    experimentalOverrideUsed: decision.experimentalOverrideUsed,
+    limitations: structuredClone(decision.limitations),
+    nextAction: decision.nextAction
+  };
+}
+
+/** Map only validated artifact fields into stable presentation data. */
+export function buildMigrationChecklistViewModel(checklist, { qualificationDecision } = {}) {
+  validateMigrationChecklist(checklist);
+  const dependencies = checklist.dependencies.map((record) => ({
+    analysisResultId: record.analysisResultId,
+    packageId: record.dependency.packageId,
+    name: record.dependency.declaredName,
+    projectId: record.dependency.projectId,
+    manifest: record.dependency.manifest,
+    status: record.status,
+    handoffStatus: record.handoff.status,
+    decisionStatus: record.decision.status,
+    decisionId: record.decisionId,
+    targetOrigin: record.decision.targetOrigin,
+    recommendationDriver: record.decision.recommendationDriver,
+    decisionReasonCodes: [...record.decision.reasonCodes],
+    analysisStatus: record.analysisStatus,
+    installedVersion: record.versions.installedVersion ?? record.versions.currentVersion,
+    currentVersion: record.versions.currentVersion,
+    currentVersionLabel: record.versions.currentVersion === null
+      ? 'unknown current version' : record.versions.currentVersion,
+    targetVersion: record.versions.targetVersion,
+    targetVersionLabel: record.versions.targetPolicy === 'registryLatest'
+      ? `${record.versions.targetVersion ?? 'unknown'} (registry latest fact)`
+      : (record.versions.targetVersion ?? 'unknown target version'),
+    targetPolicy: record.versions.targetPolicy,
+    affectedAreas: structuredClone(record.handoff.affectedAreas),
+    coverage: structuredClone(record.handoff.coverage),
+    verification: structuredClone(record.handoff.verification),
+    officialEvidence: structuredClone(record.handoff.officialEvidence),
+    preconditions: structuredClone(record.handoff.preconditions),
+    recovery: structuredClone(record.handoff.recovery),
+    reviewQuestions: [...record.handoff.reviewQuestions],
+    missingInformation: structuredClone(record.handoff.missingInformation),
+    nextStep: structuredClone(record.handoff.nextStep),
+    humanReviewRequired: record.handoff.humanReviewRequired,
+    findings: record.findings.map((finding) => ({
+      id: finding.id,
+      summary: finding.summary,
+      status: finding.status,
+      eligibilityReasonCode: finding.eligibility.reasonCode,
+      evidenceRefs: [...finding.evidenceRefs],
+      items: finding.items.map((item) => ({
+        id: item.id,
+        kind: item.kind,
+        basis: item.basis,
+        label: item.basis === 'AI_AUTHORED'
+          ? 'AI-selected official guidance'
+          : item.kind === 'REVIEW_CANDIDATE_USAGE'
+            ? 'Candidate review location'
+            : 'Manual-review item',
+        instruction: item.instruction,
+        evidenceRefs: [...item.evidenceRefs],
+        candidateLocations: structuredClone(item.candidateLocations),
+        requiresHumanReview: item.requiresHumanReview
+      }))
+    })),
+    limitations: structuredClone(record.limitations)
+  })).sort((left, right) => (
+    compareText(left.projectId, right.projectId)
+    || compareText(left.packageId, right.packageId)
+    || compareText(left.analysisResultId, right.analysisResultId)
+  ));
+  return deepFreeze({
+    repositoryName: checklist.repository.name,
+    status: checklist.status,
+    experimental: true,
+    qualification: qualificationPresentation(qualificationDecision, checklist),
+    humanReviewRequired: true,
+    summary: structuredClone(checklist.summary),
+    dependencies,
+    limitations: structuredClone(checklist.limitations)
+  });
+}
+
+export function renderMigrationChecklistConsole({ viewModel, artifactPath }) {
+  const summary = viewModel.summary;
+  const heading = summary.groundedActionCount === 0
+    ? '! Migration checklist contains no grounded action'
+    : summary.limitationCount > 0
+      ? '✓ Migration checklist created with limitations'
+      : '✓ Migration checklist created';
+  const lines = [
+    heading,
+    '',
+    `  ${summary.findingCount} breaking findings represented`,
+    `  ${summary.aiAuthoredItemCount} AI-selected official guidance items`,
+    `  ${summary.candidateLocationCount} candidate review locations`,
+    `  ${summary.handoffStatusCounts.ACTIONABLE_WITH_REVIEW} actionable handoffs require review`,
+    `  ${summary.handoffStatusCounts.INVESTIGATION_REQUIRED} investigation handoffs`,
+    `  ${summary.requiresHumanReviewItemCount} checklist items require human review`,
+    `  Provider qualification: ${viewModel.qualification.status}`,
+    `  Qualification ID: ${viewModel.qualification.qualificationId ?? 'none'}`,
+    `  Qualification source: ${viewModel.qualification.sourceKind}`,
+    `  Experimental override: ${viewModel.qualification.experimentalOverrideUsed ? 'YES' : 'NO'}`,
+    `  Runtime identity: ${viewModel.qualification.runtimeIdentity.provider} / ${viewModel.qualification.runtimeIdentity.model} / ${viewModel.qualification.runtimeIdentity.adapter}`,
+    '  Human review required: YES'
+  ];
+  if (viewModel.qualification.sourcePath) {
+    lines.splice(9, 0, `  Qualification path: ${viewModel.qualification.sourcePath}`);
+  }
+  if (viewModel.qualification.nextAction !== 'NONE') {
+    lines.push(`  Next action: ${viewModel.qualification.nextAction}`);
+  }
+  if (summary.groundedActionCount === 0) {
+    lines.push(
+      '',
+      '  Selected official evidence did not yield an explicit grounded migration action.',
+      '  Manual review is required.'
+    );
+  }
+  lines.push('', `  Checklist  ${artifactPath}`, '');
+  return lines.join('\n');
+}
+
+function renderItem(item) {
+  const lines = [
+    `- **${item.label} — requires human review:** ${item.instruction}`,
+    `  - Evidence references: ${item.evidenceRefs.length > 0
+      ? item.evidenceRefs.map(inlineCode).join(', ') : 'None'}`
+  ];
+  for (const location of item.candidateLocations) {
+    lines.push(
+      `  - Candidate review location: ${inlineCode(location.symbol)} in ${inlineCode(location.file)}; impact evidence ${inlineCode(location.impactEvidenceId)}`
+    );
+  }
+  return lines;
+}
+
+function renderDependency(dependency) {
+  const lines = [
+    `### ${inlineCode(dependency.name)} (${inlineCode(dependency.packageId)})`,
+    '',
+    `- Checklist status: ${inlineCode(dependency.status)}`,
+    `- Handoff status: ${inlineCode(dependency.handoffStatus)}`,
+    `- Upgrade decision: ${inlineCode(dependency.decisionStatus)}`,
+    `- Decision ID: ${inlineCode(dependency.decisionId)}`,
+    `- Target origin: ${inlineCode(dependency.targetOrigin)}`,
+    `- Recommendation driver: ${inlineCode(dependency.recommendationDriver ?? 'none')}`,
+    `- Manifest: ${inlineCode(dependency.manifest)}`,
+    `- Installed version: ${dependency.installedVersion ?? 'unknown'}`,
+    `- Current version: ${dependency.currentVersionLabel}`,
+    `- Target version: ${dependency.targetVersionLabel}`,
+    `- Usage coverage: ${inlineCode(`${dependency.coverage.status} / ${dependency.coverage.reasonCode ?? 'none'}`)}`,
+    `- Next step: ${inlineCode(dependency.nextStep.code)} — ${dependency.nextStep.message}`,
+    ''
+  ];
+  if (dependency.affectedAreas.length === 0) {
+    lines.push('Affected areas: none verified. This is not proof that source adaptation is unnecessary.', '');
+  } else {
+    lines.push('Affected areas to inspect before proposing a patch:');
+    for (const area of dependency.affectedAreas) {
+      lines.push(
+        `- ${inlineCode(area.file)} — symbol ${inlineCode(area.symbol)}; finding ${inlineCode(area.findingId)}; impact evidence ${inlineCode(area.impactEvidenceId)}`
+      );
+    }
+    lines.push('');
+  }
+  if (dependency.verification.status === 'AVAILABLE') {
+    lines.push('Project-derived verification commands:');
+    for (const command of dependency.verification.commands) {
+      lines.push(
+        `- ${inlineCode(command.command)} from ${inlineCode(command.source.path)}; run in ${inlineCode(command.workingDirectory)}`
+      );
+    }
+    lines.push('');
+  } else if (dependency.verification.status !== 'NOT_APPLICABLE') {
+    lines.push(`${inlineCode('VERIFICATION_COMMAND_UNAVAILABLE')}: no supported project-derived verification command is available.`, '');
+  }
+  if (dependency.officialEvidence.length > 0) {
+    lines.push('Official evidence metadata:');
+    for (const evidence of dependency.officialEvidence) {
+      lines.push(
+        `- ${inlineCode(evidence.id)} — ${evidence.kind}; `
+        + `${evidence.authority}/${evidence.trust}; `
+        + `releases ${evidence.releaseVersions.join(', ')}; locator ${inlineCode(evidence.locator)}`
+      );
+    }
+    lines.push('');
+  }
+  if (dependency.reviewQuestions.length > 0) {
+    lines.push('Investigation questions:');
+    for (const question of dependency.reviewQuestions) lines.push(`- ${question}`);
+    lines.push('');
+  }
+  if (dependency.missingInformation.length > 0) {
+    lines.push('Missing information:');
+    for (const item of dependency.missingInformation) {
+      lines.push(`- ${inlineCode(item.code)}: ${item.message}`);
+    }
+    lines.push('');
+  }
+  if (dependency.findings.length === 0) lines.push('No grounded breaking-change record is available.', '');
+  for (const finding of dependency.findings) {
+    lines.push(
+      `#### ${headingText(finding.summary)}`,
+      '',
+      `- Finding ID: ${inlineCode(finding.id)}`,
+      `- Eligibility: ${inlineCode(finding.eligibilityReasonCode)}`,
+      `- Evidence references: ${finding.evidenceRefs.length > 0
+        ? finding.evidenceRefs.map(inlineCode).join(', ') : 'None'}`,
+      ''
+    );
+    for (const item of finding.items) lines.push(...renderItem(item));
+    lines.push('');
+  }
+  if (dependency.limitations.length > 0) {
+    lines.push('Limitations:');
+    for (const item of dependency.limitations) lines.push(`- ${inlineCode(item.code)}: ${item.message}`);
+    lines.push('');
+  }
+  return lines;
+}
+
+export function renderMigrationChecklistMarkdownSection({ viewModel }) {
+  const lines = [
+    '## Migration Checklist',
+    '',
+    '> Experimental evidence-grounded checklist. Every AI-selected official guidance item requires human review.',
+    '>',
+    '> Checklist coverage marked COMPLETE applies only to the grounded records represented here. It does not mean the upgrade is safe or the migration is complete.',
+    '>',
+    '> Coding Agents must inspect every listed affected source area before designing or applying a patch.',
+    '',
+    `- Checklist status: ${inlineCode(viewModel.status)}`,
+    `- Provider qualification: ${inlineCode(viewModel.qualification.status)}`,
+    `- Qualification ID: ${inlineCode(viewModel.qualification.qualificationId ?? 'none')}`,
+    `- Qualification source: ${inlineCode(viewModel.qualification.sourceKind)}`,
+    `- Qualification path: ${inlineCode(viewModel.qualification.sourcePath ?? 'none')}`,
+    `- Experimental override: **${viewModel.qualification.experimentalOverrideUsed ? 'YES' : 'NO'}**`,
+    `- Runtime identity: ${inlineCode(`${viewModel.qualification.runtimeIdentity.provider} / ${viewModel.qualification.runtimeIdentity.model} / ${viewModel.qualification.runtimeIdentity.adapter}`)}`,
+    '- Human review required: **YES**',
+    `- AI-selected official guidance items: ${viewModel.summary.aiAuthoredItemCount}`,
+    `- Candidate review locations: ${viewModel.summary.candidateLocationCount}`,
+    ''
+  ];
+  if (viewModel.qualification.nextAction !== 'NONE') {
+    lines.splice(11, 0, `- Next action: ${inlineCode(viewModel.qualification.nextAction)}`);
+  }
+  if (viewModel.dependencies.length === 0) lines.push('No migration checklist dependency records.', '');
+  else for (const dependency of viewModel.dependencies) lines.push(...renderDependency(dependency));
+  if (viewModel.limitations.length > 0) {
+    lines.push('### Migration Checklist Limitations', '');
+    for (const item of viewModel.limitations) {
+      lines.push(`- ${inlineCode(item.code)}: ${item.message}`);
+    }
+    lines.push('');
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/migration-checklist/progress.js

@@ -0,0 +1,96 @@
+export const MIGRATION_PROGRESS_EVENTS = Object.freeze([
+  'stage:start',
+  'stage:progress',
+  'stage:complete',
+  'stage:failed',
+  'stage:cancelled',
+  'migration:context-start',
+  'migration:context-complete',
+  'migration:abstained',
+  'migration:trust-rejected',
+  'migration:fallback',
+  'migration:artifact-written'
+]);
+
+const EVENT_SET = new Set(MIGRATION_PROGRESS_EVENTS);
+const MODES = new Set(['auto', 'interactive', 'plain']);
+
+function elapsedSeconds(milliseconds) {
+  return `${(Math.max(0, milliseconds) / 1000).toFixed(1)}s`;
+}
+
+function selectedMode(stream, mode) {
+  if (!MODES.has(mode)) throw new TypeError('Migration progress mode must be auto, interactive, or plain.');
+  return mode === 'auto' ? (stream.isTTY ? 'interactive' : 'plain') : mode;
+}
+
+function plainLine(event) {
+  if (event.type === 'stage:start') {
+    return `[MIGRATION_CHECKLIST] START contexts=${event.total} qualification=${event.qualificationStatus} qualificationId=${event.qualificationId ?? 'none'} experimentalOverride=${event.experimentalOverrideUsed ? 'yes' : 'no'}`;
+  }
+  if (event.type === 'migration:context-start') {
+    return `[MIGRATION_CHECKLIST] CONTEXT_START package=${event.packageName} processed=${event.processed}/${event.total}`;
+  }
+  if (['migration:context-complete', 'migration:abstained', 'migration:trust-rejected', 'migration:fallback'].includes(event.type)) {
+    return `[MIGRATION_CHECKLIST] CONTEXT package=${event.packageName} status=${event.outcome} processed=${event.processed}/${event.total}${event.reasonCode ? ` reason=${event.reasonCode}` : ''}`;
+  }
+  if (event.type === 'migration:artifact-written') {
+    return `[MIGRATION_CHECKLIST] ARTIFACT path=${event.artifactPath}`;
+  }
+  if (event.type === 'stage:complete') {
+    return `[MIGRATION_CHECKLIST] COMPLETE generated=${event.generated} abstained=${event.abstained} rejected=${event.rejected} failed=${event.failed} qualification=${event.qualificationStatus} qualificationId=${event.qualificationId ?? 'none'} experimentalOverride=${event.experimentalOverrideUsed ? 'yes' : 'no'}`;
+  }
+  if (event.type === 'stage:failed') {
+    return `[MIGRATION_CHECKLIST] FAILED reason=${event.reasonCode} qualification=${event.qualificationStatus} qualificationId=${event.qualificationId ?? 'none'} experimentalOverride=${event.experimentalOverrideUsed ? 'yes' : 'no'}`;
+  }
+  if (event.type === 'stage:cancelled') {
+    return `[MIGRATION_CHECKLIST] CANCELLED reason=${event.reasonCode}`;
+  }
+  return null;
+}
+
+function interactiveLine(event, startedAt, now) {
+  if (event.type === 'stage:start') {
+    return `● Building migration checklist  ${elapsedSeconds(now - startedAt)}\n  0/${event.total} breaking findings processed\n  Provider qualification: ${event.qualificationStatus}\n  Qualification ID: ${event.qualificationId ?? 'none'}\n  Experimental override: ${event.experimentalOverrideUsed ? 'YES' : 'NO'}`;
+  }
+  if (['migration:context-complete', 'migration:abstained', 'migration:trust-rejected', 'migration:fallback'].includes(event.type)) {
+    return `  ${event.processed}/${event.total} ${event.packageName}: ${event.outcome}`;
+  }
+  if (event.type === 'migration:artifact-written') return `  Checklist: ${event.artifactPath}`;
+  if (event.type === 'stage:complete') {
+    return `✓ Migration checklist completed  ${elapsedSeconds(now - startedAt)}\n  ${event.processed}/${event.total} breaking findings processed\n  ${event.generated} grounded actions; ${event.abstained} abstained; ${event.rejected + event.failed} fallbacks\n  Provider qualification: ${event.qualificationStatus}\n  Qualification ID: ${event.qualificationId ?? 'none'}\n  Experimental override: ${event.experimentalOverrideUsed ? 'YES' : 'NO'}`;
+  }
+  if (event.type === 'stage:failed') {
+    return `✗ Migration checklist failed  ${elapsedSeconds(now - startedAt)}\n  Reason: ${event.reasonCode}\n  Provider qualification: ${event.qualificationStatus}\n  Qualification ID: ${event.qualificationId ?? 'none'}\n  Experimental override: ${event.experimentalOverrideUsed ? 'YES' : 'NO'}`;
+  }
+  if (event.type === 'stage:cancelled') {
+    return `■ Migration checklist cancelled  ${elapsedSeconds(now - startedAt)}`;
+  }
+  return null;
+}
+
+/** Render stable line-oriented progress. Interactive mode intentionally uses no cursor control. */
+export function createMigrationProgressReporter(stream, {
+  mode = 'auto',
+  clock = () => Date.now()
+} = {}) {
+  if (!stream || typeof stream.write !== 'function') {
+    throw new TypeError('Migration progress reporter requires a writable stream.');
+  }
+  const activeMode = selectedMode(stream, mode);
+  let startedAt = null;
+  return Object.freeze({
+    mode: activeMode,
+    handle(event) {
+      if (!event || !EVENT_SET.has(event.type)) {
+        throw new TypeError('Unknown Migration Checklist progress event.');
+      }
+      const now = clock();
+      if (event.type === 'stage:start') startedAt = now;
+      const line = activeMode === 'plain'
+        ? plainLine(event)
+        : interactiveLine(event, startedAt ?? now, now);
+      if (line) stream.write(`${line}\n`);
+    }
+  });
+}

package/src/migration-checklist/prompt.js

@@ -0,0 +1,83 @@
+import { MIGRATION_CHECKLIST_CANDIDATE_SCHEMA } from './ai-candidate.js';
+
+export const MIGRATION_PLANNING_TASK = 'migration-planning.v1';
+export const MIGRATION_PLANNING_PROMPT_VERSION = '1';
+export const MIGRATION_PLANNING_SCHEMA_NAME = 'upgradelens_migration_checklist_candidate';
+
+function promptEvidence(evidence) {
+  return {
+    id: evidence.id,
+    sourceId: evidence.sourceId,
+    kind: evidence.kind,
+    authority: evidence.authority,
+    trust: evidence.trust,
+    retrievedAt: evidence.retrievedAt,
+    contentDigest: evidence.contentDigest,
+    locator: evidence.locator,
+    releaseVersions: [...evidence.releaseVersions],
+    content: evidence.content
+  };
+}
+
+/** Build the minimal model-visible projection. Locations and source URLs stay deterministic. */
+export function buildMigrationChecklistPromptContext(context) {
+  return {
+    contextId: context.contextId,
+    dependency: {
+      packageId: context.dependency.packageId,
+      declaredName: context.dependency.declaredName,
+      normalizedName: context.dependency.normalizedName,
+      ecosystem: context.dependency.ecosystem,
+      registry: context.dependency.registry
+    },
+    versions: structuredClone(context.versions),
+    analysisResultId: context.analysisResultId,
+    finding: structuredClone(context.finding),
+    evidence: context.evidence.map(promptEvidence),
+    evidenceAllowlist: [...context.evidenceAllowlist],
+    eligibility: structuredClone(context.eligibility),
+    locationEligibility: structuredClone(context.locationEligibility),
+    requiresHumanReview: true,
+    humanReviewReasons: [...context.humanReviewReasons],
+    limitations: structuredClone(context.limitations)
+  };
+}
+
+export function buildMigrationChecklistPrompt({
+  context,
+  outputSchema = MIGRATION_CHECKLIST_CANDIDATE_SCHEMA,
+  promptVersion = MIGRATION_PLANNING_PROMPT_VERSION
+}) {
+  const modelContext = buildMigrationChecklistPromptContext(context);
+  return {
+    promptVersion,
+    system: [
+      'You are the UpgradeLens evidence transformation component for a human-review migration checklist.',
+      'Use only the bounded selected evidence in the supplied context; do not use outside knowledge.',
+      'Identify only explicit migration actions and paraphrase them as short review drafts.',
+      'This is not autonomous planning. Abstain when the evidence does not explicitly state an action.',
+      'Return only JSON that satisfies the structured output schema.'
+    ].join('\n'),
+    user: [
+      'Rules:',
+      '- Keep the exact package and target-version scope supplied in the context.',
+      '- Each instruction must cite selected evidence and include a short verbatim supporting excerpt copied from that same evidence record.',
+      '- An exact excerpt is required; do not paraphrase the excerpt and do not cite an id outside evidenceAllowlist.',
+      '- Return ABSTAIN when evidence only describes a change, is ambiguous, has unclear version scope, or gives no explicit migration action.',
+      '- Do not create an action merely to complete the response.',
+      '- Do not emit identity, status, eligibility, item id, finding id, package identity, approval, or completion state.',
+      '- Do not create or mention URLs, repository files, symbols, locations, source snippets, code, patches, diffs, or commands.',
+      '- Do not invent replacement APIs, packages, flags, config keys, prerequisites, or dependency ordering.',
+      '- Do not create rollback plans, effort estimates, numeric confidence, or safety/ready/verified/complete claims.',
+      '- Unknown currentVersion remains unknown. registryLatest is a registry fact, not a recommendation.',
+      '- Unsupported or absent usage coverage does not mean unused, not impacted, or safe to upgrade.',
+      '- All generated drafts require human review.',
+      '',
+      'Structured output schema:',
+      JSON.stringify(outputSchema),
+      '',
+      'Migration Checklist Context:',
+      JSON.stringify(modelContext)
+    ].join('\n')
+  };
+}