@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/http/bounded-fetch.js

@@ -0,0 +1,278 @@
+import { USER_AGENT } from '../constants.js';
+
+const JSON_MEDIA_TYPE = /^(?:application\/(?:json|[a-z0-9.+-]+\+json))(?:\s*;|$)/i;
+const EVIDENCE_MEDIA_TYPE = /^(?:text\/(?:plain|markdown|html)|application\/(?:json|[a-z0-9.+-]+\+json|xhtml\+xml))(?:\s*;|$)/i;
+
+/**
+ * Adapter configuration is intentionally bounded even though the transport
+ * helper itself can enforce any positive safe integer supplied by a caller.
+ */
+export const MAX_REGISTRY_RESPONSE_BYTES = 64 * 1024 * 1024;
+
+export class BoundedFetchError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'BoundedFetchError';
+    this.code = code;
+  }
+}
+
+function headerValue(headers, name) {
+  if (!headers || typeof headers.get !== 'function') return null;
+  return headers.get(name);
+}
+
+function validLimit(value, name, errorPrefix) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new BoundedFetchError(`${errorPrefix}_REQUEST_INVALID`, `${name} must be a positive integer.`);
+  }
+}
+
+/** Validate an adapter-owned response limit without imposing a shared default. */
+export function validateRegistryResponseLimit(value, {
+  errorPrefix = 'HTTP',
+  maximum = MAX_REGISTRY_RESPONSE_BYTES
+} = {}) {
+  validLimit(value, 'maxResponseBytes', errorPrefix);
+  if (value > maximum) {
+    throw new BoundedFetchError(
+      `${errorPrefix}_REQUEST_INVALID`,
+      `maxResponseBytes must not exceed ${maximum} bytes.`
+    );
+  }
+  return value;
+}
+
+async function discardResponseBody(response) {
+  try {
+    await response?.body?.cancel?.();
+  } catch {
+    // Cleanup cannot change a sanitized registry result.
+  }
+}
+
+async function readBoundedText(response, maxResponseBytes, { errorPrefix, serviceName }) {
+  const declaredLength = headerValue(response.headers, 'content-length');
+  if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > maxResponseBytes) {
+    await discardResponseBody(response);
+    throw new BoundedFetchError(`${errorPrefix}_RESPONSE_TOO_LARGE`, `${serviceName} response exceeds the configured size limit.`);
+  }
+
+  const reader = response.body?.getReader?.();
+  if (!reader) {
+    return readFallbackText(response, maxResponseBytes, { errorPrefix, serviceName });
+  }
+
+  const chunks = [];
+  let byteCount = 0;
+  let completed = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        completed = true;
+        break;
+      }
+      const chunk = Buffer.from(value);
+      byteCount += chunk.length;
+      if (byteCount > maxResponseBytes) {
+        throw new BoundedFetchError(`${errorPrefix}_RESPONSE_TOO_LARGE`, `${serviceName} response exceeds the configured size limit.`);
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    if (!completed) {
+      try {
+        await reader.cancel?.();
+      } catch {
+        // Cleanup cannot change a sanitized registry result.
+      }
+    }
+    try {
+      reader.releaseLock?.();
+    } catch {
+      // Cleanup cannot change a sanitized registry result.
+    }
+    if (!completed) await discardResponseBody(response);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readFallbackText(response, maxResponseBytes, { errorPrefix, serviceName }) {
+  const read = typeof response?.text === 'function'
+    ? () => response.text()
+    : typeof response?.body?.text === 'function'
+      ? () => response.body.text()
+      : null;
+  if (!read) {
+    await discardResponseBody(response);
+    throw new BoundedFetchError(`${errorPrefix}_RESPONSE_INVALID`, `${serviceName} response body is not readable.`);
+  }
+
+  let completed = false;
+  try {
+    const text = await read();
+    if (Buffer.byteLength(String(text), 'utf8') > maxResponseBytes) {
+      throw new BoundedFetchError(`${errorPrefix}_RESPONSE_TOO_LARGE`, `${serviceName} response exceeds the configured size limit.`);
+    }
+    completed = true;
+    return String(text);
+  } finally {
+    if (!completed) await discardResponseBody(response);
+  }
+}
+
+/**
+ * Fetch one registry JSON representation without allowing an unbounded body
+ * into memory. Redirects are explicitly disabled in this small adapter.
+ */
+export async function fetchRegistryJson(url, {
+  fetchImplementation = globalThis.fetch,
+  timeoutMs = 10_000,
+  maxResponseBytes,
+  userAgent = USER_AGENT,
+  errorPrefix = 'NPM',
+  serviceName = 'npm Registry',
+  setTimeoutImplementation = setTimeout,
+  clearTimeoutImplementation = clearTimeout
+} = {}) {
+  if (typeof fetchImplementation !== 'function') {
+    throw new BoundedFetchError(`${errorPrefix}_REQUEST_INVALID`, 'A WHATWG-compatible fetch implementation is required.');
+  }
+  validLimit(timeoutMs, 'timeoutMs', errorPrefix);
+  validLimit(maxResponseBytes, 'maxResponseBytes', errorPrefix);
+  if (typeof setTimeoutImplementation !== 'function' || typeof clearTimeoutImplementation !== 'function') {
+    throw new BoundedFetchError(`${errorPrefix}_REQUEST_INVALID`, 'Timer implementations must be functions.');
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeoutImplementation(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    try {
+      response = await fetchImplementation(url, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': userAgent
+        },
+        signal: controller.signal,
+        credentials: 'omit',
+        redirect: 'error'
+      });
+    } catch (error) {
+      if (controller.signal.aborted || error?.name === 'AbortError') {
+        throw new BoundedFetchError(`${errorPrefix}_REQUEST_TIMEOUT`, `${serviceName} request timed out.`);
+      }
+      throw new BoundedFetchError(`${errorPrefix}_TRANSPORT_FAILED`, `${serviceName} request failed.`);
+    }
+
+    if (!response || !Number.isInteger(response.status)) {
+      await discardResponseBody(response);
+      throw new BoundedFetchError(`${errorPrefix}_RESPONSE_INVALID`, `${serviceName} returned an invalid HTTP response.`);
+    }
+    if (response.status !== 200) {
+      await discardResponseBody(response);
+      return { status: response.status, body: null };
+    }
+
+    const contentType = headerValue(response.headers, 'content-type');
+    if (!contentType || !JSON_MEDIA_TYPE.test(contentType)) {
+      await discardResponseBody(response);
+      throw new BoundedFetchError(`${errorPrefix}_RESPONSE_INVALID`, `${serviceName} response must use a JSON media type.`);
+    }
+
+    let text;
+    try {
+      text = await readBoundedText(response, maxResponseBytes, { errorPrefix, serviceName });
+    } catch (error) {
+      if (error instanceof BoundedFetchError) throw error;
+      if (controller.signal.aborted || error?.name === 'AbortError') {
+        throw new BoundedFetchError(`${errorPrefix}_REQUEST_TIMEOUT`, `${serviceName} request timed out.`);
+      }
+      throw new BoundedFetchError(`${errorPrefix}_TRANSPORT_FAILED`, `${serviceName} response could not be read.`);
+    }
+    try {
+      return { status: 200, body: JSON.parse(text) };
+    } catch {
+      throw new BoundedFetchError(`${errorPrefix}_RESPONSE_INVALID`, `${serviceName} response is not valid JSON.`);
+    }
+  } finally {
+    clearTimeoutImplementation(timer);
+  }
+}
+
+export function fetchNpmJson(url, options = {}) {
+  return fetchRegistryJson(url, { ...options, errorPrefix: 'NPM', serviceName: 'npm Registry' });
+}
+
+/**
+ * Fetch one bounded public evidence document. This deliberately shares the
+ * registry transport policy: GET only, no credentials, no redirects, a hard
+ * deadline, a hard body limit, and sanitized failures.
+ */
+export async function fetchEvidenceDocument(url, {
+  fetchImplementation = globalThis.fetch,
+  timeoutMs = 10_000,
+  maxResponseBytes = 512 * 1024,
+  userAgent = USER_AGENT,
+  setTimeoutImplementation = setTimeout,
+  clearTimeoutImplementation = clearTimeout
+} = {}) {
+  if (typeof fetchImplementation !== 'function') {
+    throw new BoundedFetchError('EVIDENCE_REQUEST_INVALID', 'A WHATWG-compatible fetch implementation is required.');
+  }
+  validLimit(timeoutMs, 'timeoutMs', 'EVIDENCE');
+  validLimit(maxResponseBytes, 'maxResponseBytes', 'EVIDENCE');
+  const controller = new AbortController();
+  const timer = setTimeoutImplementation(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    try {
+      response = await fetchImplementation(url, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json, text/markdown, text/plain, text/html;q=0.8',
+          'User-Agent': userAgent
+        },
+        signal: controller.signal,
+        credentials: 'omit',
+        redirect: 'error'
+      });
+    } catch (error) {
+      if (controller.signal.aborted || error?.name === 'AbortError') {
+        throw new BoundedFetchError('EVIDENCE_REQUEST_TIMEOUT', 'Evidence source request timed out.');
+      }
+      throw new BoundedFetchError('EVIDENCE_TRANSPORT_FAILED', 'Evidence source request failed.');
+    }
+    if (!response || !Number.isInteger(response.status)) {
+      await discardResponseBody(response);
+      throw new BoundedFetchError('EVIDENCE_RESPONSE_INVALID', 'Evidence source returned an invalid HTTP response.');
+    }
+    if (response.status !== 200) {
+      await discardResponseBody(response);
+      return { status: response.status, mediaType: null, text: null };
+    }
+    const contentType = headerValue(response.headers, 'content-type');
+    if (!contentType || !EVIDENCE_MEDIA_TYPE.test(contentType)) {
+      await discardResponseBody(response);
+      throw new BoundedFetchError('EVIDENCE_RESPONSE_INVALID', 'Evidence source returned an unsupported media type.');
+    }
+    let text;
+    try {
+      text = await readBoundedText(response, maxResponseBytes, {
+        errorPrefix: 'EVIDENCE',
+        serviceName: 'Evidence source'
+      });
+    } catch (error) {
+      if (error instanceof BoundedFetchError) throw error;
+      if (controller.signal.aborted || error?.name === 'AbortError') {
+        throw new BoundedFetchError('EVIDENCE_REQUEST_TIMEOUT', 'Evidence source request timed out.');
+      }
+      throw new BoundedFetchError('EVIDENCE_TRANSPORT_FAILED', 'Evidence source response could not be read.');
+    }
+    return { status: 200, mediaType: contentType.split(';', 1)[0].trim().toLowerCase(), text };
+  } finally {
+    clearTimeoutImplementation(timer);
+  }
+}

package/src/http/cli-http-runtime.js

@@ -0,0 +1,44 @@
+import { Agent, fetch as undiciFetch } from 'undici';
+
+const DEFAULT_AGENT_OPTIONS = Object.freeze({
+  connections: 4,
+  keepAliveTimeout: 1_000,
+  keepAliveMaxTimeout: 1_000
+});
+
+export class CliHttpRuntimeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliHttpRuntimeError';
+  }
+}
+
+/**
+ * Create the short-lived HTTP runtime owned by one online CLI research run.
+ * It deliberately does not mutate Undici's process-wide global dispatcher.
+ */
+export function createCliHttpRuntime({
+  createAgent = (options) => new Agent(options),
+  fetchImplementation = undiciFetch,
+  agentOptions = {}
+} = {}) {
+  if (typeof createAgent !== 'function' || typeof fetchImplementation !== 'function') {
+    throw new CliHttpRuntimeError('Unable to create the CLI HTTP runtime.');
+  }
+  const dispatcher = createAgent({ ...DEFAULT_AGENT_OPTIONS, ...agentOptions });
+  if (!dispatcher || typeof dispatcher.close !== 'function') {
+    throw new CliHttpRuntimeError('Unable to create the CLI HTTP runtime.');
+  }
+
+  let closePromise = null;
+  const close = async () => {
+    if (!closePromise) closePromise = Promise.resolve().then(() => dispatcher.close());
+    return closePromise;
+  };
+  const fetch = async (input, init = {}) => {
+    if (closePromise) throw new CliHttpRuntimeError('The CLI HTTP runtime is closed.');
+    return fetchImplementation(input, { ...init, dispatcher });
+  };
+
+  return Object.freeze({ fetch, close });
+}

package/src/impact/input-loader.js

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import { DEFAULT_USAGE_INDEX_PATH, USAGE_INDEX_SCHEMA_VERSION } from '../constants.js';
+import { isPortableRelativePath } from '../portable.js';
+import { UsageDiscoveryInputError, loadUsageDiscoveryInputs } from '../usage/input-loader.js';
+import { validateUsageIndex } from '../usage/usage-index.js';
+
+export class ImpactAnalysisInputError extends Error {
+  constructor(message, code = 'IMPACT_ANALYSIS_INPUT_INVALID') {
+    super(`Impact Analysis input error: ${message}`);
+    this.name = 'ImpactAnalysisInputError';
+    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 ImpactAnalysisInputError('Usage Index 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_USAGE_INDEX_PATH;
+  if (!isPortableRelativePath(artifact)) {
+    throw new ImpactAnalysisInputError('Usage Index artifact must be a portable repository-relative path.');
+  }
+  return artifact;
+}
+
+function lineageMismatches(expected, actual, fields) {
+  return fields.filter((field) => {
+    const path = field.split('.');
+    const read = (value) => path.reduce((current, segment) => current?.[segment], value);
+    return read(expected) !== read(actual);
+  });
+}
+
+function validateLineage(baseInput, usageIndex) {
+  const projectMismatches = lineageMismatches(
+    usageIndex.input.projectManifest,
+    baseInput.projectManifest,
+    ['schemaVersion', 'artifact', 'artifactDigest', 'repository.name', 'repository.root']
+  );
+  const versionMismatches = lineageMismatches(
+    usageIndex.input.versionAnalysis,
+    baseInput.versionAnalysis,
+    ['schemaVersion', 'artifact', 'artifactDigest']
+  );
+  const mismatches = [
+    ...projectMismatches.map((field) => `Project Manifest ${field}`),
+    ...versionMismatches.map((field) => `Version Analysis ${field}`)
+  ];
+  if (mismatches.length > 0) {
+    throw new ImpactAnalysisInputError(
+      `Usage Index lineage mismatch: ${mismatches.join(', ')}.`,
+      'LINEAGE_MISMATCH'
+    );
+  }
+}
+
+function validateUsageReferences(versionAnalysis, usageIndex) {
+  const results = new Map();
+  for (const result of versionAnalysis.results) {
+    const key = `${result.dependency.projectId}\0${result.dependency.packageId}`;
+    if (!results.has(key)) results.set(key, []);
+    results.get(key).push(result);
+  }
+  const errors = [];
+  for (const usage of usageIndex.dependencies) {
+    const key = `${usage.projectId}\0${usage.packageId}`;
+    const candidates = results.get(key) ?? [];
+    if (candidates.length === 0) {
+      errors.push(`${usage.packageId} in ${usage.projectId} has no Version Analysis result`);
+    } else if (!candidates.some((result) => result.dependency.declaredName === usage.name)) {
+      errors.push(`${usage.packageId} in ${usage.projectId} has a dependency-name mismatch`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new ImpactAnalysisInputError(`invalid Usage Index references: ${errors.sort().join('; ')}.`);
+  }
+}
+
+function validateCoverageReferences(projectManifest, usageIndex) {
+  if (!usageIndex.analysis.coverage) return;
+  const projects = new Map(projectManifest.projects.map((project) => [project.id, project]));
+  const errors = [];
+  for (const coverage of usageIndex.analysis.coverage) {
+    const project = projects.get(coverage.projectId);
+    if (!project) {
+      errors.push(`${coverage.projectId} coverage references an unknown project`);
+    } else if (coverage.projectPath !== project.path || coverage.ecosystem !== project.ecosystem) {
+      errors.push(`${coverage.projectId} coverage project identity does not match Project Manifest`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new ImpactAnalysisInputError(`invalid Usage Index coverage references: ${errors.sort().join('; ')}.`);
+  }
+}
+
+export async function loadImpactAnalysisInputs(sources, options = {}) {
+  if (!sources?.projectManifest || !sources?.versionAnalysis || !sources?.usageIndex) {
+    throw new ImpactAnalysisInputError('projectManifest, versionAnalysis, and usageIndex sources are required.');
+  }
+  let base;
+  try {
+    base = await loadUsageDiscoveryInputs(sources, options);
+  } catch (error) {
+    if (error instanceof UsageDiscoveryInputError) {
+      throw new ImpactAnalysisInputError(error.message, error.code);
+    }
+    throw error;
+  }
+  const artifact = artifactFor(sources.usageIndex, options.usageIndexArtifact);
+  const bytes = await readBytes(sources.usageIndex);
+  let usageIndex;
+  try {
+    usageIndex = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new ImpactAnalysisInputError('Usage Index bytes are not valid JSON.');
+  }
+  if (usageIndex?.schemaVersion !== USAGE_INDEX_SCHEMA_VERSION) {
+    throw new ImpactAnalysisInputError(
+      `unsupported Usage Index schema version; expected ${USAGE_INDEX_SCHEMA_VERSION}.`
+    );
+  }
+  try {
+    validateUsageIndex(usageIndex);
+  } catch (error) {
+    throw new ImpactAnalysisInputError(error.message);
+  }
+  validateLineage(base.input, usageIndex);
+  validateUsageReferences(base.versionAnalysis, usageIndex);
+  validateCoverageReferences(base.projectManifest, usageIndex);
+
+  return {
+    projectManifest: base.projectManifest,
+    versionAnalysis: base.versionAnalysis,
+    usageIndex,
+    input: {
+      ...base.input,
+      usageIndex: {
+        schemaVersion: usageIndex.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes)
+      }
+    }
+  };
+}

package/src/impact/matcher.js

@@ -0,0 +1,40 @@
+import { compareText } from '../portable.js';
+
+export const EXACT_SYMBOL_MATCHER_ID = 'exact-symbol';
+export const EXACT_SYMBOL_MATCHER_VERSION = '1.0.0';
+
+const SYNTHETIC_SYMBOLS = new Set(['*', 'default']);
+const IDENTIFIER_CHARACTER = '\\p{L}\\p{N}\\p{M}\\p{Pc}$\\u200C\\u200D';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function isMatchableUsageSymbol(symbol) {
+  return typeof symbol === 'string' && symbol.length > 0 && !SYNTHETIC_SYMBOLS.has(symbol);
+}
+
+export function summaryContainsExactSymbol(summary, symbol) {
+  if (typeof summary !== 'string' || !isMatchableUsageSymbol(symbol)) return false;
+  const expression = new RegExp(
+    `(?:^|[^${IDENTIFIER_CHARACTER}])${escapeRegExp(symbol)}(?=$|[^${IDENTIFIER_CHARACTER}])`,
+    'u'
+  );
+  return expression.test(summary);
+}
+
+export function matchFindingToUsage(finding, dependencyUsage) {
+  if (finding?.kind !== 'breakingChange' || !dependencyUsage) return [];
+  return dependencyUsage.symbols
+    .filter((usage) => summaryContainsExactSymbol(finding.summary, usage.name))
+    .map((usage) => ({ symbol: usage.name, files: [...usage.files].sort(compareText) }))
+    .sort((left, right) => compareText(left.symbol, right.symbol));
+}
+
+export function createExactSymbolImpactMatcher() {
+  return Object.freeze({
+    id: EXACT_SYMBOL_MATCHER_ID,
+    version: EXACT_SYMBOL_MATCHER_VERSION,
+    match: matchFindingToUsage
+  });
+}