@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/impact/repository-impact.js

@@ -0,0 +1,199 @@
+import { readFile } from 'node:fs/promises';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import {
+  ARTIFACT_GENERATOR_NAME,
+  REPOSITORY_IMPACT_SCHEMA_VERSION,
+  VERSION
+} from '../constants.js';
+import { compareText, isSorted } from '../portable.js';
+import { coverageForProject } from '../usage/coverage.js';
+import {
+  REPOSITORY_IMPACT_REASON_CODES,
+  REPOSITORY_IMPACT_STATUSES,
+  classifyDependencyImpact,
+  classifyFindingImpact
+} from './status.js';
+
+const schema = JSON.parse(await readFile(
+  new URL('../../schemas/repository-impact.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+const compareDependencies = (left, right) => (
+  compareText(left.projectId, right.projectId)
+  || compareText(left.packageId, right.packageId)
+  || compareText(left.analysisResultId, right.analysisResultId)
+);
+const compareFindings = (left, right) => compareText(left.id, right.id);
+const compareMatches = (left, right) => compareText(left.symbol, right.symbol);
+
+function buildDependencies(versionAnalysis, usageIndex, matcher) {
+  const usages = new Map(usageIndex.dependencies.map((usage) => (
+    [`${usage.projectId}\0${usage.packageId}`, usage]
+  )));
+  return versionAnalysis.results.map((result) => {
+    const key = `${result.dependency.projectId}\0${result.dependency.packageId}`;
+    const usage = usages.get(key) ?? null;
+    const coverage = coverageForProject(
+      usageIndex,
+      result.dependency.projectId,
+      result.dependency.ecosystem ?? null
+    );
+    const versionStatus = result.status ?? 'analyzed';
+    const findings = result.findings
+      .filter((finding) => finding.kind === 'breakingChange')
+      .map((finding) => {
+        const matches = matcher.match(finding, usage);
+        const state = classifyFindingImpact({ versionStatus, coverage, usage, matches });
+        return {
+          id: finding.id,
+          kind: finding.kind,
+          summary: finding.summary,
+          impacted: matches.length > 0,
+          ...state,
+          matches
+        };
+      })
+      .sort(compareFindings);
+    const state = classifyDependencyImpact({ versionStatus, coverage, usage, findings });
+    return {
+      analysisResultId: result.id,
+      projectId: result.dependency.projectId,
+      packageId: result.dependency.packageId,
+      name: result.dependency.declaredName,
+      impacted: findings.some((finding) => finding.impacted),
+      ...state,
+      coverage: structuredClone(coverage),
+      findings
+    };
+  }).sort(compareDependencies);
+}
+
+function buildSummary(dependencies) {
+  const findings = dependencies.flatMap((dependency) => dependency.findings);
+  const matches = findings.flatMap((finding) => finding.matches);
+  const affectedFiles = new Set(matches.flatMap((match) => match.files));
+  return {
+    impacted: dependencies.some((dependency) => dependency.impacted),
+    dependencyCount: dependencies.length,
+    impactedDependencyCount: dependencies.filter((dependency) => dependency.impacted).length,
+    findingCount: findings.length,
+    impactedFindingCount: findings.filter((finding) => finding.impacted).length,
+    matchCount: matches.length,
+    affectedFileCount: affectedFiles.size,
+    notImpactedDependencyCount: dependencies.filter((item) => item.status === 'NOT_IMPACTED').length,
+    usageNotFoundDependencyCount: dependencies.filter((item) => item.status === 'USAGE_NOT_FOUND').length,
+    coverageUnavailableDependencyCount: dependencies.filter((item) => item.status === 'COVERAGE_UNAVAILABLE').length,
+    notAnalyzedDependencyCount: dependencies.filter((item) => item.status === 'NOT_ANALYZED').length
+  };
+}
+
+export function validateRepositoryImpactInvariants(impact) {
+  const errors = [];
+  if (!isSorted(impact.dependencies, compareDependencies)) errors.push('dependencies must be sorted.');
+  if (impact.analysis.resultCount !== impact.dependencies.length) {
+    errors.push('analysis.resultCount must equal dependencies length.');
+  }
+  const resultIds = new Set();
+  for (const dependency of impact.dependencies) {
+    if (resultIds.has(dependency.analysisResultId)) {
+      errors.push(`duplicate analysis result ${dependency.analysisResultId}.`);
+    }
+    resultIds.add(dependency.analysisResultId);
+    if (!isSorted(dependency.findings, compareFindings)) {
+      errors.push(`findings for ${dependency.analysisResultId} must be sorted.`);
+    }
+    if (new Set(dependency.findings.map((finding) => finding.id)).size !== dependency.findings.length) {
+      errors.push(`findings for ${dependency.analysisResultId} must be unique.`);
+    }
+    const expectedDependencyImpact = dependency.findings.some((finding) => finding.impacted);
+    if (dependency.impacted !== expectedDependencyImpact) {
+      errors.push(`dependency ${dependency.analysisResultId} impacted is inconsistent.`);
+    }
+    if (dependency.status !== undefined) {
+      if (!REPOSITORY_IMPACT_STATUSES.includes(dependency.status)) {
+        errors.push(`dependency ${dependency.analysisResultId} status is unsupported.`);
+      }
+      if (!REPOSITORY_IMPACT_REASON_CODES.includes(dependency.reasonCode)) {
+        errors.push(`dependency ${dependency.analysisResultId} reasonCode is unsupported.`);
+      }
+      if ((dependency.status === 'IMPACTED') !== dependency.impacted) {
+        errors.push(`dependency ${dependency.analysisResultId} status is inconsistent with impacted.`);
+      }
+      if (!dependency.coverage) {
+        errors.push(`dependency ${dependency.analysisResultId} status has no coverage.`);
+      }
+    }
+    for (const finding of dependency.findings) {
+      if (!isSorted(finding.matches, compareMatches)) errors.push(`matches for finding ${finding.id} must be sorted.`);
+      if (new Set(finding.matches.map((match) => match.symbol)).size !== finding.matches.length) {
+        errors.push(`matches for finding ${finding.id} must be unique.`);
+      }
+      if (finding.impacted !== (finding.matches.length > 0)) {
+        errors.push(`finding ${finding.id} impacted is inconsistent.`);
+      }
+      if (finding.status !== undefined) {
+        if (!REPOSITORY_IMPACT_STATUSES.includes(finding.status)) {
+          errors.push(`finding ${finding.id} status is unsupported.`);
+        }
+        if (!REPOSITORY_IMPACT_REASON_CODES.includes(finding.reasonCode)) {
+          errors.push(`finding ${finding.id} reasonCode is unsupported.`);
+        }
+        if ((finding.status === 'IMPACTED') !== finding.impacted) {
+          errors.push(`finding ${finding.id} status is inconsistent with impacted.`);
+        }
+      }
+      for (const match of finding.matches) {
+        if (!isSorted(match.files, compareText)) errors.push(`files for match ${match.symbol} must be sorted.`);
+        if (new Set(match.files).size !== match.files.length) errors.push(`files for match ${match.symbol} must be unique.`);
+      }
+    }
+  }
+  const expected = buildSummary(impact.dependencies);
+  for (const [field, value] of Object.entries(expected)) {
+    const statusAware = impact.dependencies.some((dependency) => dependency.status !== undefined);
+    if (statusAware && impact.summary[field] === undefined) {
+      errors.push(`summary.${field} is required for status-aware impact.`);
+    } else if (impact.summary[field] !== undefined && impact.summary[field] !== value) {
+      errors.push(`summary.${field} is inconsistent.`);
+    }
+  }
+  return errors.sort(compareText);
+}
+
+export function validateRepositoryImpact(impact) {
+  if (!validateSchema(impact)) {
+    throw new Error(
+      `Repository Impact validation error: ${ajv.errorsText(validateSchema.errors, { separator: '; ' })}`
+    );
+  }
+  const errors = validateRepositoryImpactInvariants(impact);
+  if (errors.length > 0) throw new Error(`Repository Impact invariant error: ${errors.join(' ')}`);
+  return impact;
+}
+
+export function buildRepositoryImpact({ input, versionAnalysis, usageIndex, matcher, generatedAt = new Date() }) {
+  if (!matcher || typeof matcher.id !== 'string' || typeof matcher.version !== 'string'
+      || typeof matcher.match !== 'function') {
+    throw new Error('Repository Impact input error: matcher must expose id, version, and match().');
+  }
+  const dependencies = buildDependencies(versionAnalysis, usageIndex, matcher);
+  return validateRepositoryImpact({
+    schemaVersion: REPOSITORY_IMPACT_SCHEMA_VERSION,
+    generatedAt: generatedAt instanceof Date ? generatedAt.toISOString() : generatedAt,
+    generator: { name: ARTIFACT_GENERATOR_NAME, version: VERSION },
+    input: structuredClone(input),
+    analysis: {
+      matcher: { id: matcher.id, version: matcher.version },
+      resultCount: dependencies.length
+    },
+    summary: buildSummary(dependencies),
+    dependencies
+  });
+}

package/src/impact/runtime.js

@@ -0,0 +1,24 @@
+import { loadImpactAnalysisInputs } from './input-loader.js';
+import { createExactSymbolImpactMatcher } from './matcher.js';
+import { buildRepositoryImpact } from './repository-impact.js';
+
+export function analyzeRepositoryImpact({
+  versionAnalysis,
+  usageIndex,
+  input,
+  matcher = createExactSymbolImpactMatcher(),
+  clock
+}) {
+  return buildRepositoryImpact({
+    input,
+    versionAnalysis,
+    usageIndex,
+    matcher,
+    generatedAt: clock?.() ?? new Date()
+  });
+}
+
+export async function runImpactAnalysis({ sources, ...options }) {
+  const artifacts = await loadImpactAnalysisInputs(sources, options);
+  return analyzeRepositoryImpact({ ...artifacts, ...options });
+}

package/src/impact/status.js

@@ -0,0 +1,62 @@
+import { isMatchableUsageSymbol } from './matcher.js';
+
+export const REPOSITORY_IMPACT_STATUSES = Object.freeze([
+  'IMPACTED',
+  'NOT_IMPACTED',
+  'USAGE_NOT_FOUND',
+  'COVERAGE_UNAVAILABLE',
+  'NOT_ANALYZED'
+]);
+
+export const REPOSITORY_IMPACT_REASON_CODES = Object.freeze([
+  'EXACT_SYMBOL_USAGE_FOUND',
+  'NO_EXACT_SYMBOL_USAGE_FOUND',
+  'NO_MATCHABLE_SYMBOL_FOUND',
+  'USAGE_NOT_FOUND',
+  'VERSION_ANALYSIS_SKIPPED',
+  'VERSION_ANALYSIS_FAILED',
+  'COVERAGE_COMPLETE',
+  'ANALYZER_UNAVAILABLE',
+  'ANALYZER_AMBIGUOUS',
+  'SOURCE_SCAN_INCOMPLETE',
+  'SOURCE_PARSE_FAILED',
+  'FILE_UNREADABLE',
+  'ANALYZER_FAILED',
+  'MULTIPLE_ANALYSIS_FAILURES',
+  'COVERAGE_METADATA_MISSING'
+]);
+
+function notAnalyzedReason(status) {
+  return status === 'failed' ? 'VERSION_ANALYSIS_FAILED' : 'VERSION_ANALYSIS_SKIPPED';
+}
+
+export function classifyFindingImpact({ versionStatus = 'analyzed', coverage, usage, matches }) {
+  if (versionStatus !== 'analyzed') {
+    return { status: 'NOT_ANALYZED', reasonCode: notAnalyzedReason(versionStatus) };
+  }
+  if (matches.length > 0) {
+    return { status: 'IMPACTED', reasonCode: 'EXACT_SYMBOL_USAGE_FOUND' };
+  }
+  if (coverage.status !== 'complete') {
+    return { status: 'COVERAGE_UNAVAILABLE', reasonCode: coverage.reasonCode };
+  }
+  if (!usage) return { status: 'USAGE_NOT_FOUND', reasonCode: 'USAGE_NOT_FOUND' };
+  if (!usage.symbols.some((symbol) => isMatchableUsageSymbol(symbol.name))) {
+    return { status: 'NOT_IMPACTED', reasonCode: 'NO_MATCHABLE_SYMBOL_FOUND' };
+  }
+  return { status: 'NOT_IMPACTED', reasonCode: 'NO_EXACT_SYMBOL_USAGE_FOUND' };
+}
+
+export function classifyDependencyImpact({ versionStatus = 'analyzed', coverage, usage, findings }) {
+  if (versionStatus !== 'analyzed') {
+    return { status: 'NOT_ANALYZED', reasonCode: notAnalyzedReason(versionStatus) };
+  }
+  if (findings.some((finding) => finding.status === 'IMPACTED')) {
+    return { status: 'IMPACTED', reasonCode: 'EXACT_SYMBOL_USAGE_FOUND' };
+  }
+  if (coverage.status !== 'complete') {
+    return { status: 'COVERAGE_UNAVAILABLE', reasonCode: coverage.reasonCode };
+  }
+  if (!usage) return { status: 'USAGE_NOT_FOUND', reasonCode: 'USAGE_NOT_FOUND' };
+  return { status: 'NOT_IMPACTED', reasonCode: 'NO_EXACT_SYMBOL_USAGE_FOUND' };
+}

package/src/impact/writer.js

@@ -0,0 +1,30 @@
+import { mkdir, open, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { validateRepositoryImpact } from './repository-impact.js';
+
+export function serializeRepositoryImpact(impact) {
+  validateRepositoryImpact(impact);
+  return `${JSON.stringify(impact, null, 2)}\n`;
+}
+
+export async function writeRepositoryImpact(outputPath, impact) {
+  const target = path.resolve(outputPath);
+  const temporary = `${target}.${process.pid}.tmp`;
+  const contents = serializeRepositoryImpact(impact);
+  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;
+}

package/src/impact-evidence/input-loader.js

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import {
+  DEFAULT_REPOSITORY_IMPACT_PATH,
+  REPOSITORY_IMPACT_SCHEMA_VERSION
+} from '../constants.js';
+import { ImpactAnalysisInputError, loadImpactAnalysisInputs } from '../impact/input-loader.js';
+import {
+  EXACT_SYMBOL_MATCHER_ID,
+  EXACT_SYMBOL_MATCHER_VERSION,
+  matchFindingToUsage
+} from '../impact/matcher.js';
+import { classifyFindingImpact } from '../impact/status.js';
+import { validateRepositoryImpact } from '../impact/repository-impact.js';
+import { isPortableRelativePath } from '../portable.js';
+import { coverageForProject } from '../usage/coverage.js';
+
+export class ImpactEvidenceInputError extends Error {
+  constructor(message, code = 'IMPACT_EVIDENCE_INPUT_INVALID') {
+    super(`Impact Evidence input error: ${message}`);
+    this.name = 'ImpactEvidenceInputError';
+    this.code = code;
+  }
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+async function readBytes(source) {
+  if (typeof source === 'string' || source instanceof URL) return readFile(source);
+  if (source && typeof source === 'object' && 'bytes' in source && source.bytes instanceof Uint8Array) {
+    return Buffer.from(source.bytes);
+  }
+  throw new ImpactEvidenceInputError(
+    'Repository Impact source must be a file path or { bytes, artifact }.'
+  );
+}
+
+function artifactFor(source, configured) {
+  const artifact = source && typeof source === 'object' && 'bytes' in source
+    ? source.artifact
+    : configured ?? DEFAULT_REPOSITORY_IMPACT_PATH;
+  if (!isPortableRelativePath(artifact)) {
+    throw new ImpactEvidenceInputError(
+      'Repository Impact artifact must be a portable repository-relative path.'
+    );
+  }
+  return artifact;
+}
+
+function readField(value, field) {
+  return field.split('.').reduce((current, segment) => current?.[segment], value);
+}
+
+function validateLineage(baseInput, repositoryImpact) {
+  const groups = [
+    ['Project Manifest', repositoryImpact.input.projectManifest, baseInput.projectManifest,
+      ['schemaVersion', 'artifact', 'artifactDigest', 'repository.name', 'repository.root']],
+    ['Version Analysis', repositoryImpact.input.versionAnalysis, baseInput.versionAnalysis,
+      ['schemaVersion', 'artifact', 'artifactDigest']],
+    ['Usage Index', repositoryImpact.input.usageIndex, baseInput.usageIndex,
+      ['schemaVersion', 'artifact', 'artifactDigest']]
+  ];
+  const mismatches = groups.flatMap(([label, expected, actual, fields]) => (
+    fields
+      .filter((field) => readField(expected, field) !== readField(actual, field))
+      .map((field) => `${label} ${field}`)
+  ));
+  if (mismatches.length > 0) {
+    throw new ImpactEvidenceInputError(
+      `Repository Impact lineage mismatch: ${mismatches.join(', ')}.`,
+      'LINEAGE_MISMATCH'
+    );
+  }
+}
+
+function sameValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function validateReferences(versionAnalysis, usageIndex, repositoryImpact) {
+  if (repositoryImpact.analysis.matcher.id !== EXACT_SYMBOL_MATCHER_ID
+      || repositoryImpact.analysis.matcher.version !== EXACT_SYMBOL_MATCHER_VERSION) {
+    throw new ImpactEvidenceInputError(
+      `unsupported impact matcher; expected ${EXACT_SYMBOL_MATCHER_ID}@${EXACT_SYMBOL_MATCHER_VERSION}.`,
+      'MATCHER_UNSUPPORTED'
+    );
+  }
+  const results = new Map(versionAnalysis.results.map((result) => [result.id, result]));
+  const usages = new Map(usageIndex.dependencies.map((usage) => (
+    [`${usage.projectId}\0${usage.packageId}`, usage]
+  )));
+  const errors = [];
+  for (const dependency of repositoryImpact.dependencies) {
+    const result = results.get(dependency.analysisResultId);
+    if (!result) {
+      errors.push(`unknown Version Analysis result ${dependency.analysisResultId}`);
+      continue;
+    }
+    if (dependency.projectId !== result.dependency.projectId
+        || dependency.packageId !== result.dependency.packageId
+        || dependency.name !== result.dependency.declaredName) {
+      errors.push(`dependency identity mismatch for ${dependency.analysisResultId}`);
+    }
+    const versionFindings = result.findings.filter((finding) => finding.kind === 'breakingChange');
+    if (versionFindings.length !== dependency.findings.length) {
+      errors.push(`finding count mismatch for ${dependency.analysisResultId}`);
+      continue;
+    }
+    const findings = new Map(versionFindings.map((finding) => [finding.id, finding]));
+    const usage = usages.get(`${dependency.projectId}\0${dependency.packageId}`) ?? null;
+    const coverage = dependency.coverage
+      ?? coverageForProject(usageIndex, dependency.projectId, result.dependency.ecosystem);
+    for (const impactFinding of dependency.findings) {
+      const sourceFinding = findings.get(impactFinding.id);
+      if (!sourceFinding) {
+        errors.push(`unknown finding ${impactFinding.id} for ${dependency.analysisResultId}`);
+        continue;
+      }
+      if (impactFinding.summary !== sourceFinding.summary) {
+        errors.push(`finding summary mismatch for ${dependency.analysisResultId}/${impactFinding.id}`);
+      }
+      const expectedMatches = matchFindingToUsage(sourceFinding, usage);
+      if (!sameValue(impactFinding.matches, expectedMatches)) {
+        errors.push(`usage match mismatch for ${dependency.analysisResultId}/${impactFinding.id}`);
+      }
+      if (impactFinding.status !== undefined) {
+        const expectedState = classifyFindingImpact({
+          versionStatus: result.status,
+          coverage,
+          usage,
+          matches: expectedMatches
+        });
+        if (impactFinding.status !== expectedState.status
+            || impactFinding.reasonCode !== expectedState.reasonCode) {
+          errors.push(`impact state mismatch for ${dependency.analysisResultId}/${impactFinding.id}`);
+        }
+      }
+    }
+  }
+  if (repositoryImpact.dependencies.length !== versionAnalysis.results.length) {
+    errors.push('Repository Impact dependency count does not match Version Analysis results');
+  }
+  if (errors.length > 0) {
+    throw new ImpactEvidenceInputError(`invalid artifact references: ${errors.sort().join('; ')}.`);
+  }
+}
+
+export async function loadImpactEvidenceInputs(sources, options = {}) {
+  if (!sources?.projectManifest || !sources?.versionAnalysis || !sources?.usageIndex
+      || !sources?.repositoryImpact) {
+    throw new ImpactEvidenceInputError(
+      'projectManifest, versionAnalysis, usageIndex, and repositoryImpact sources are required.'
+    );
+  }
+  let base;
+  try {
+    base = await loadImpactAnalysisInputs(sources, options);
+  } catch (error) {
+    if (error instanceof ImpactAnalysisInputError) {
+      throw new ImpactEvidenceInputError(error.message, error.code);
+    }
+    throw error;
+  }
+  const artifact = artifactFor(sources.repositoryImpact, options.repositoryImpactArtifact);
+  const bytes = await readBytes(sources.repositoryImpact);
+  let repositoryImpact;
+  try {
+    repositoryImpact = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new ImpactEvidenceInputError('Repository Impact bytes are not valid JSON.');
+  }
+  if (repositoryImpact?.schemaVersion !== REPOSITORY_IMPACT_SCHEMA_VERSION) {
+    throw new ImpactEvidenceInputError(
+      `unsupported Repository Impact schema version; expected ${REPOSITORY_IMPACT_SCHEMA_VERSION}.`
+    );
+  }
+  try {
+    validateRepositoryImpact(repositoryImpact);
+  } catch (error) {
+    throw new ImpactEvidenceInputError(error.message);
+  }
+  validateLineage(base.input, repositoryImpact);
+  validateReferences(base.versionAnalysis, base.usageIndex, repositoryImpact);
+
+  return {
+    projectManifest: base.projectManifest,
+    versionAnalysis: base.versionAnalysis,
+    usageIndex: base.usageIndex,
+    repositoryImpact,
+    input: {
+      ...base.input,
+      repositoryImpact: {
+        schemaVersion: repositoryImpact.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes)
+      }
+    }
+  };
+}