@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/version-analysis-loader.js

@@ -0,0 +1,203 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import {
+  DEFAULT_OUTPUT_DIRECTORY,
+  DEFAULT_KNOWLEDGE_MANIFEST_PATH,
+  DEFAULT_MANIFEST_PATH,
+  KNOWLEDGE_MANIFEST_SCHEMA_VERSION
+} from './constants.js';
+import { validateKnowledgeEvidenceBundle } from './knowledge-evidence-bundle.js';
+import { validateKnowledgeManifestInvariants } from './knowledge-manifest.js';
+import { isPortableRelativePath } from './portable.js';
+import { loadProjectManifestInput } from './project-manifest-input.js';
+
+export const DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH =
+  `${DEFAULT_OUTPUT_DIRECTORY}/knowledge-evidence-bundle.json`;
+
+const knowledgeManifestSchema = JSON.parse(await readFile(
+  new URL('../schemas/knowledge-manifest.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const validateKnowledgeManifestSchema = ajv.compile(knowledgeManifestSchema);
+
+export class VersionAnalysisInputError extends Error {
+  constructor(message, code = 'VERSION_ANALYSIS_INPUT_INVALID') {
+    super(`Version Analysis input error: ${message}`);
+    this.name = 'VersionAnalysisInputError';
+    this.code = code;
+  }
+}
+
+function inputError(message, code) {
+  return new VersionAnalysisInputError(message, code);
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function parseJson(bytes, artifactType) {
+  try {
+    return JSON.parse(Buffer.from(bytes).toString('utf8'));
+  } catch {
+    throw inputError(`${artifactType} bytes are not valid JSON.`);
+  }
+}
+
+function artifactFor(source, options, defaultArtifact, artifactType) {
+  const artifact = typeof source === 'object' && source !== null && 'bytes' in source
+    ? source.artifact
+    : options.artifact ?? defaultArtifact;
+  if (!isPortableRelativePath(artifact)) {
+    throw inputError(`${artifactType} artifact must be a portable repository-relative path.`);
+  }
+  return artifact;
+}
+
+async function readInputBytes(source, artifactType) {
+  if (typeof source === 'string' || source instanceof URL) return readFile(source);
+  if (source && typeof source === 'object' && 'bytes' in source) {
+    if (!(source.bytes instanceof Uint8Array)) {
+      throw inputError(`${artifactType} bytes must be a Uint8Array or Buffer.`);
+    }
+    return Buffer.from(source.bytes);
+  }
+  throw inputError(`${artifactType} source must be a file path or { bytes, artifact }.`);
+}
+
+export async function loadKnowledgeManifestInput(source, options = {}) {
+  const artifact = artifactFor(source, options, DEFAULT_KNOWLEDGE_MANIFEST_PATH, 'Knowledge Manifest');
+  const bytes = await readInputBytes(source, 'Knowledge Manifest');
+  const manifest = parseJson(bytes, 'Knowledge Manifest');
+
+  if (manifest?.schemaVersion !== KNOWLEDGE_MANIFEST_SCHEMA_VERSION) {
+    throw inputError(`unsupported Knowledge Manifest schema version; expected ${KNOWLEDGE_MANIFEST_SCHEMA_VERSION}.`);
+  }
+  if (!validateKnowledgeManifestSchema(manifest)) {
+    throw inputError(
+      `Knowledge Manifest schema validation failed: ${ajv.errorsText(validateKnowledgeManifestSchema.errors, { separator: '; ' })}`
+    );
+  }
+  const invariantErrors = validateKnowledgeManifestInvariants(manifest);
+  if (invariantErrors.length > 0) {
+    throw inputError(`Knowledge Manifest runtime invariants failed: ${invariantErrors.join(' ')}`);
+  }
+
+  return {
+    manifest,
+    input: {
+      knowledgeManifest: {
+        schemaVersion: manifest.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes),
+        researchId: manifest.research.researchId
+      }
+    }
+  };
+}
+
+export async function loadKnowledgeEvidenceBundleInput(source, options = {}) {
+  const artifact = artifactFor(source, options, DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH, 'Knowledge Evidence Bundle');
+  const bytes = await readInputBytes(source, 'Knowledge Evidence Bundle');
+  const bundle = parseJson(bytes, 'Knowledge Evidence Bundle');
+
+  if (bundle?.schemaVersion !== '1.0.0') {
+    throw inputError('unsupported Knowledge Evidence Bundle schema version; expected 1.0.0.');
+  }
+  try {
+    validateKnowledgeEvidenceBundle(bundle);
+  } catch (error) {
+    throw inputError(error.message);
+  }
+
+  return {
+    bundle,
+    input: {
+      evidenceArtifact: {
+        schemaVersion: bundle.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes)
+      }
+    }
+  };
+}
+
+function assertProjectKnowledgeLineage(projectInput, knowledgeInput, knowledgeManifest) {
+  const expected = knowledgeManifest.input.projectManifest;
+  const actual = projectInput.projectManifest;
+  const mismatches = [];
+  if (expected.schemaVersion !== actual.schemaVersion) mismatches.push('Project Manifest schemaVersion');
+  if (expected.artifactDigest !== actual.artifactDigest) mismatches.push('Project Manifest artifactDigest');
+  if (expected.repository.name !== actual.repository.name) mismatches.push('Project Manifest repository.name');
+  if (expected.repository.root !== actual.repository.root) mismatches.push('Project Manifest repository.root');
+  if (mismatches.length > 0) {
+    throw inputError(`Knowledge Manifest lineage mismatch: ${mismatches.join(', ')}.`, 'LINEAGE_MISMATCH');
+  }
+}
+
+function assertEvidenceKnowledgeLineage(knowledgeInput, evidenceBundle) {
+  const expected = evidenceBundle.input.knowledgeManifest;
+  const actual = knowledgeInput.knowledgeManifest;
+  const mismatches = [];
+  if (expected.schemaVersion !== actual.schemaVersion) mismatches.push('Knowledge Manifest schemaVersion');
+  if (expected.artifactDigest !== actual.artifactDigest) mismatches.push('Knowledge Manifest artifactDigest');
+  if (expected.researchId !== actual.researchId) mismatches.push('Knowledge Manifest researchId');
+  if (mismatches.length > 0) {
+    throw inputError(`Knowledge Evidence Bundle lineage mismatch: ${mismatches.join(', ')}.`, 'LINEAGE_MISMATCH');
+  }
+}
+
+function assertEvidenceReferences(knowledgeManifest, evidenceBundle) {
+  const packageIds = new Set(knowledgeManifest.packages.map((item) => item.id));
+  const sourceIds = new Set(knowledgeManifest.sources.map((item) => item.id));
+  const errors = [];
+  for (const item of evidenceBundle.evidence) {
+    if (!packageIds.has(item.packageId)) errors.push(`Evidence ${item.id} references unknown package ${item.packageId}.`);
+    if (!sourceIds.has(item.sourceId)) errors.push(`Evidence ${item.id} references unknown source ${item.sourceId}.`);
+  }
+  for (const warning of evidenceBundle.warnings) {
+    if (warning.packageId && !packageIds.has(warning.packageId)) {
+      errors.push(`Evidence warning ${warning.code} references unknown package ${warning.packageId}.`);
+    }
+    if (warning.sourceId && !sourceIds.has(warning.sourceId)) {
+      errors.push(`Evidence warning ${warning.code} references unknown source ${warning.sourceId}.`);
+    }
+  }
+  if (errors.length > 0) throw inputError(errors.join(' '));
+}
+
+export async function loadVersionAnalysisArtifacts(sources, options = {}) {
+  const project = await loadProjectManifestInput(
+    sources.projectManifest,
+    { artifact: options.projectManifestArtifact ?? DEFAULT_MANIFEST_PATH }
+  );
+  const knowledge = await loadKnowledgeManifestInput(
+    sources.knowledgeManifest,
+    { artifact: options.knowledgeManifestArtifact ?? DEFAULT_KNOWLEDGE_MANIFEST_PATH }
+  );
+  const evidence = await loadKnowledgeEvidenceBundleInput(
+    sources.evidenceBundle,
+    { artifact: options.evidenceBundleArtifact ?? DEFAULT_KNOWLEDGE_EVIDENCE_BUNDLE_PATH }
+  );
+
+  assertProjectKnowledgeLineage(project.input, knowledge.input, knowledge.manifest);
+  assertEvidenceKnowledgeLineage(knowledge.input, evidence.bundle);
+  assertEvidenceReferences(knowledge.manifest, evidence.bundle);
+
+  return {
+    projectManifest: project.manifest,
+    knowledgeManifest: knowledge.manifest,
+    evidenceBundle: evidence.bundle,
+    input: {
+      projectManifest: project.input.projectManifest,
+      knowledgeManifest: knowledge.input.knowledgeManifest,
+      evidenceArtifact: evidence.input.evidenceArtifact
+    }
+  };
+}

package/src/version-analysis-manifest.js

@@ -0,0 +1,314 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { canonicalJsonBytes } from './canonical-json.js';
+import { ARTIFACT_GENERATOR_NAME, VERSION } from './constants.js';
+import { DEPENDENCY_AI_CONTEXT_VERSION } from './dependency-ai-context.js';
+import { VERSION_ANALYSIS_PROMPT_VERSION } from './ai-version-analysis.js';
+import { compareText } from './portable.js';
+
+export const VERSION_ANALYSIS_SCHEMA_VERSION = '1.0.0';
+
+const schema = JSON.parse(await readFile(
+  new URL('../schemas/version-analysis.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+function digest(value) {
+  const bytes = value instanceof Uint8Array ? value : canonicalJsonBytes(value);
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function compareBy(...selectors) {
+  return (left, right) => {
+    for (const selector of selectors) {
+      const result = compareText(selector(left), selector(right));
+      if (result !== 0) return result;
+    }
+    return 0;
+  };
+}
+
+const compareResults = compareBy(
+  (item) => item.dependency.projectId,
+  (item) => item.dependency.manifest,
+  (item) => item.dependency.dependencyType,
+  (item) => item.dependency.packageId,
+  (item) => item.versions.declaredVersion ?? '',
+  (item) => item.versions.targetVersion ?? '',
+  (item) => item.contextId
+);
+const compareEvidence = compareBy((item) => item.id);
+const compareFindings = compareBy((item) => item.id);
+
+function sorted(values) {
+  return [...values].sort(compareText);
+}
+
+function isSorted(items, comparator) {
+  return items.every((item, index) => index === 0 || comparator(items[index - 1], item) <= 0);
+}
+
+function duplicateValues(values) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const value of values) {
+    if (seen.has(value)) duplicates.add(value);
+    seen.add(value);
+  }
+  return [...duplicates].sort(compareText);
+}
+
+function addMismatch(errors, field, actual, expected) {
+  if (actual !== expected) errors.push(`${field} is ${actual}; expected ${expected}.`);
+}
+
+function resultIdentity(result) {
+  return [
+    result.dependency.projectId,
+    result.dependency.manifest,
+    result.dependency.dependencyType,
+    result.dependency.packageId,
+    result.versions.declaredVersion ?? '',
+    result.versions.targetVersion ?? ''
+  ].join('\0');
+}
+
+function resultIdMaterial(result) {
+  return {
+    contextId: result.contextId,
+    dependency: result.dependency,
+    versions: result.versions
+  };
+}
+
+function refsFor(result) {
+  return [
+    ...result.summaryEvidenceRefs,
+    ...result.riskEvidenceRefs,
+    ...result.findings.flatMap((finding) => finding.evidenceRefs)
+  ];
+}
+
+function manifestSummary(results) {
+  return {
+    resultCount: results.length,
+    analyzedCount: results.filter((item) => item.status === 'analyzed').length,
+    skippedCount: results.filter((item) => item.status === 'skipped').length,
+    failedCount: results.filter((item) => item.status === 'failed').length,
+    requiresHumanReviewCount: results.filter((item) => item.requiresHumanReview).length,
+    riskCounts: {
+      low: results.filter((item) => item.riskLevel === 'low').length,
+      medium: results.filter((item) => item.riskLevel === 'medium').length,
+      high: results.filter((item) => item.riskLevel === 'high').length,
+      unknown: results.filter((item) => item.riskLevel === 'unknown').length
+    }
+  };
+}
+
+function evidenceFromContext(context) {
+  return context.knowledge.evidence
+    .map((item) => ({
+      id: item.id,
+      kind: item.kind,
+      sourceId: item.sourceId,
+      sourceUrl: item.sourceUrl,
+      authority: item.authority,
+      trust: item.trust,
+      retrievedAt: item.retrievedAt,
+      contentDigest: item.contentDigest,
+      locator: item.locator,
+      releaseVersions: sorted(item.releaseVersions)
+    }))
+    .sort(compareEvidence);
+}
+
+function buildResult(context, analysisResult) {
+  const result = {
+    id: digest(resultIdMaterial(analysisResult)),
+    status: analysisResult.status,
+    contextId: analysisResult.contextId,
+    dependency: structuredClone(analysisResult.dependency),
+    versions: structuredClone(analysisResult.versions),
+    summary: analysisResult.summary,
+    summaryEvidenceRefs: sorted(analysisResult.summaryEvidenceRefs),
+    riskLevel: analysisResult.riskLevel,
+    riskEvidenceRefs: sorted(analysisResult.riskEvidenceRefs),
+    findings: structuredClone(analysisResult.findings)
+      .map((finding) => ({
+        ...finding,
+        appliesToVersions: sorted(finding.appliesToVersions),
+        evidenceRefs: sorted(finding.evidenceRefs)
+      }))
+      .sort(compareFindings),
+    evidence: evidenceFromContext(context),
+    evidenceCoverage: analysisResult.evidenceCoverage,
+    confidence: analysisResult.confidence ?? {
+      evidenceCoverage: analysisResult.evidenceCoverage,
+      validationStatus: analysisResult.validation.status,
+      requiresHumanReview: analysisResult.requiresHumanReview
+    },
+    validation: {
+      status: analysisResult.validation.status,
+      warningCodes: sorted(analysisResult.validation.warningCodes)
+    },
+    requiresHumanReview: analysisResult.requiresHumanReview,
+    humanReviewReasons: sorted(analysisResult.humanReviewReasons),
+    nextAction: analysisResult.nextAction,
+    limitations: structuredClone(analysisResult.limitations)
+      .sort(compareBy((item) => item.code, (item) => item.message))
+  };
+  return result;
+}
+
+function validatePair(context, analysisResult) {
+  if (context.contextId !== analysisResult.contextId) {
+    throw new Error(`Version Analysis Manifest input error: context/result mismatch for ${analysisResult.contextId}.`);
+  }
+  const deterministicFields = ['dependency', 'versions'];
+  for (const field of deterministicFields) {
+    if (JSON.stringify(context[field]) !== JSON.stringify(analysisResult[field])) {
+      throw new Error(`Version Analysis Manifest input error: result ${analysisResult.contextId} changed deterministic ${field}.`);
+    }
+  }
+}
+
+export function validateVersionAnalysisManifestInvariants(manifest) {
+  const errors = [];
+  const results = manifest.results ?? [];
+  if (!isSorted(results, compareResults)) errors.push('results must be sorted by dependency and target.');
+
+  for (const duplicate of duplicateValues(results.map((item) => item.id))) {
+    errors.push(`Duplicate result id ${duplicate}.`);
+  }
+  for (const duplicate of duplicateValues(results.map(resultIdentity))) {
+    errors.push(`Duplicate dependency analysis result ${duplicate.replaceAll('\0', ' / ')}.`);
+  }
+
+  for (const result of results) {
+    const expectedId = digest(resultIdMaterial(result));
+    if (result.id !== expectedId) errors.push(`Result ${result.id} id is not stable for its context/dependency/version facts.`);
+    if (!isSorted(result.evidence, compareEvidence)) errors.push(`Result ${result.id} evidence must be sorted by id.`);
+    if (!isSorted(result.findings, compareFindings)) errors.push(`Result ${result.id} findings must be sorted by id.`);
+    const evidenceIds = new Set(result.evidence.map((item) => item.id));
+    for (const duplicate of duplicateValues(result.evidence.map((item) => item.id))) {
+      errors.push(`Result ${result.id} has duplicate evidence ${duplicate}.`);
+    }
+    for (const ref of refsFor(result)) {
+      if (!evidenceIds.has(ref)) errors.push(`Result ${result.id} references unknown evidence ${ref}.`);
+    }
+    if (result.confidence.evidenceCoverage !== result.evidenceCoverage) {
+      errors.push(`Result ${result.id} confidence.evidenceCoverage does not match evidenceCoverage.`);
+    }
+    if (result.confidence.validationStatus !== result.validation.status) {
+      errors.push(`Result ${result.id} confidence.validationStatus does not match validation.status.`);
+    }
+    if (result.confidence.requiresHumanReview !== result.requiresHumanReview) {
+      errors.push(`Result ${result.id} confidence.requiresHumanReview does not match requiresHumanReview.`);
+    }
+    const versions = result.versions;
+    const installedFields = [
+      'installedVersion',
+      'installedVersionStatus',
+      'installedVersionSource',
+      'installedVersionReason'
+    ];
+    const installedFieldCount = installedFields.filter((field) => field in versions).length;
+    if (installedFieldCount !== 0 && installedFieldCount !== installedFields.length) {
+      errors.push(`Result ${result.id} has an incomplete installed-version baseline.`);
+    } else if (versions.installedVersionStatus === 'resolved') {
+      if (
+        versions.currentVersion !== versions.installedVersion
+        || versions.currentVersionSource !== 'resolvedArtifact'
+        || versions.installedVersionSource === null
+        || versions.installedVersionReason !== null
+      ) {
+        errors.push(`Result ${result.id} does not preserve its resolved installed-version baseline.`);
+      }
+    } else if (
+      versions.installedVersionStatus === 'unresolved'
+      && (
+        versions.installedVersion !== null
+        || versions.installedVersionSource !== null
+        || versions.installedVersionReason === null
+      )
+    ) {
+      errors.push(`Result ${result.id} has inconsistent unresolved installed-version fields.`);
+    }
+  }
+
+  addMismatch(errors, 'analysis.resultCount', manifest.analysis?.resultCount, results.length);
+  const summary = manifestSummary(results);
+  addMismatch(errors, 'summary.resultCount', manifest.summary?.resultCount, summary.resultCount);
+  addMismatch(errors, 'summary.analyzedCount', manifest.summary?.analyzedCount, summary.analyzedCount);
+  addMismatch(errors, 'summary.skippedCount', manifest.summary?.skippedCount, summary.skippedCount);
+  addMismatch(errors, 'summary.failedCount', manifest.summary?.failedCount, summary.failedCount);
+  addMismatch(
+    errors,
+    'summary.requiresHumanReviewCount',
+    manifest.summary?.requiresHumanReviewCount,
+    summary.requiresHumanReviewCount
+  );
+  for (const level of ['low', 'medium', 'high', 'unknown']) {
+    addMismatch(errors, `summary.riskCounts.${level}`, manifest.summary?.riskCounts?.[level], summary.riskCounts[level]);
+  }
+
+  return errors.sort(compareText);
+}
+
+export function validateVersionAnalysisManifest(manifest) {
+  if (manifest?.schemaVersion !== VERSION_ANALYSIS_SCHEMA_VERSION) {
+    throw new Error(`Version Analysis Manifest validation error: unsupported schema version; expected ${VERSION_ANALYSIS_SCHEMA_VERSION}.`);
+  }
+  if (!validateSchema(manifest)) {
+    throw new Error(`Version Analysis Manifest validation error: schema validation failed: ${ajv.errorsText(validateSchema.errors, { separator: '; ' })}`);
+  }
+  const invariantErrors = validateVersionAnalysisManifestInvariants(manifest);
+  if (invariantErrors.length > 0) {
+    throw new Error(`Version Analysis Manifest validation error: runtime invariants failed: ${invariantErrors.join(' ')}`);
+  }
+  return manifest;
+}
+
+export function buildVersionAnalysisManifest({
+  input,
+  contexts,
+  results,
+  generatedAt = new Date(),
+  promptVersion = VERSION_ANALYSIS_PROMPT_VERSION,
+  contextVersion = DEPENDENCY_AI_CONTEXT_VERSION
+}) {
+  if (!Array.isArray(contexts) || !Array.isArray(results) || contexts.length !== results.length) {
+    throw new Error('Version Analysis Manifest input error: contexts and results must be arrays of the same length.');
+  }
+  const records = contexts.map((context, index) => {
+    const result = results[index];
+    validatePair(context, result);
+    return buildResult(context, result);
+  }).sort(compareResults);
+
+  const manifest = {
+    schemaVersion: VERSION_ANALYSIS_SCHEMA_VERSION,
+    generatedAt: generatedAt instanceof Date ? generatedAt.toISOString() : generatedAt,
+    generator: { name: ARTIFACT_GENERATOR_NAME, version: VERSION },
+    input: structuredClone(input),
+    analysis: {
+      promptVersion,
+      contextVersion,
+      resultCount: records.length
+    },
+    summary: manifestSummary(records),
+    results: records
+  };
+  return validateVersionAnalysisManifest(manifest);
+}
+
+export function versionAnalysisManifestDigest(manifest) {
+  return digest(manifest);
+}

package/src/version-analysis-writer.js

@@ -0,0 +1,30 @@
+import { mkdir, open, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { validateVersionAnalysisManifest } from './version-analysis-manifest.js';
+
+export function serializeVersionAnalysisManifest(manifest) {
+  validateVersionAnalysisManifest(manifest);
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export async function writeVersionAnalysisManifest(outputPath, manifest) {
+  const target = path.resolve(outputPath);
+  const temporary = `${target}.${process.pid}.tmp`;
+  const contents = serializeVersionAnalysisManifest(manifest);
+  await mkdir(path.dirname(target), { recursive: true });
+  let handle;
+  try {
+    handle = await open(temporary, 'w', 0o600);
+    await handle.writeFile(contents, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, target);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  return target;
+}