@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/usage/analyzer-registry.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+
+function normalizeExtension(extension) {
+  if (typeof extension !== 'string' || !/^\.[a-z0-9]+$/i.test(extension)) {
+    throw new Error(`Usage analyzer extension must start with a dot: ${extension}.`);
+  }
+  return extension.toLowerCase();
+}
+
+function validateAnalyzer(analyzer) {
+  if (!analyzer || typeof analyzer !== 'object') throw new Error('Usage analyzer must be an object.');
+  if (typeof analyzer.id !== 'string' || analyzer.id.length === 0) {
+    throw new Error('Usage analyzer id must be a non-empty string.');
+  }
+  if (typeof analyzer.version !== 'string' || analyzer.version.length === 0) {
+    throw new Error(`Usage analyzer ${analyzer.id} version must be a non-empty string.`);
+  }
+  if (!Array.isArray(analyzer.ecosystems) || analyzer.ecosystems.length === 0) {
+    throw new Error(`Usage analyzer ${analyzer.id} must declare at least one ecosystem.`);
+  }
+  if (!Array.isArray(analyzer.extensions) || analyzer.extensions.length === 0) {
+    throw new Error(`Usage analyzer ${analyzer.id} must declare at least one extension.`);
+  }
+  if (typeof analyzer.analyze !== 'function') {
+    throw new Error(`Usage analyzer ${analyzer.id} must expose analyze().`);
+  }
+}
+
+export function createUsageAnalyzerRegistry(analyzers = []) {
+  const byId = new Map();
+  const byCapability = new Map();
+
+  for (const analyzer of analyzers) {
+    validateAnalyzer(analyzer);
+    if (byId.has(analyzer.id)) throw new Error(`Duplicate usage analyzer id: ${analyzer.id}.`);
+    byId.set(analyzer.id, analyzer);
+
+    for (const ecosystem of analyzer.ecosystems) {
+      for (const declaredExtension of analyzer.extensions) {
+        const extension = normalizeExtension(declaredExtension);
+        const key = `${ecosystem}\0${extension}`;
+        if (byCapability.has(key)) {
+          throw new Error(
+            `Usage analyzer capability conflict for ${ecosystem}/${extension}: `
+            + `${byCapability.get(key).id} and ${analyzer.id}.`
+          );
+        }
+        byCapability.set(key, analyzer);
+      }
+    }
+  }
+
+  return Object.freeze({
+    analyzers: () => [...byId.values()],
+    extensions: () => [...new Set([...byCapability.keys()].map((key) => key.split('\0')[1]))].sort(),
+    forEcosystem(ecosystem) {
+      return [...byId.values()].filter((analyzer) => analyzer.ecosystems.includes(ecosystem));
+    },
+    find(ecosystem, filePath) {
+      return byCapability.get(`${ecosystem}\0${path.extname(filePath).toLowerCase()}`) ?? null;
+    }
+  });
+}

package/src/usage/coverage.js

@@ -0,0 +1,116 @@
+import { compareText } from '../portable.js';
+
+export const USAGE_COVERAGE_STATUSES = Object.freeze([
+  'complete',
+  'partial',
+  'unavailable',
+  'failed'
+]);
+
+export const USAGE_COVERAGE_REASON_CODES = Object.freeze([
+  'COVERAGE_COMPLETE',
+  'ANALYZER_UNAVAILABLE',
+  'ANALYZER_AMBIGUOUS',
+  'SOURCE_SCAN_INCOMPLETE',
+  'SOURCE_PARSE_FAILED',
+  'FILE_UNREADABLE',
+  'ANALYZER_FAILED',
+  'MULTIPLE_ANALYSIS_FAILURES',
+  'COVERAGE_METADATA_MISSING'
+]);
+
+export const compareCoverage = (left, right) => (
+  compareText(left.projectId, right.projectId)
+  || compareText(left.ecosystem, right.ecosystem)
+  || compareText(left.projectPath, right.projectPath)
+);
+
+function failureReason(counts) {
+  const failures = [
+    counts.scanFailureCount > 0 ? 'SOURCE_SCAN_INCOMPLETE' : null,
+    counts.parseFailureCount > 0 ? 'SOURCE_PARSE_FAILED' : null,
+    counts.unreadableFileCount > 0 ? 'FILE_UNREADABLE' : null,
+    counts.analyzerFailureCount > 0 ? 'ANALYZER_FAILED' : null
+  ].filter(Boolean);
+  return failures.length === 1 ? failures[0] : 'MULTIPLE_ANALYSIS_FAILURES';
+}
+
+export function buildProjectUsageCoverage({
+  projectId,
+  projectPath,
+  ecosystem,
+  analyzers,
+  scannedFileCount = 0,
+  analyzedFileCount = 0,
+  parseFailureCount = 0,
+  analyzerFailureCount = 0,
+  unreadableFileCount = 0,
+  scanFailureCount = 0
+}) {
+  const candidates = [...new Map(
+    analyzers.map((analyzer) => [`${analyzer.id}\0${analyzer.version}`, analyzer])
+  ).values()];
+  const counts = {
+    scannedFileCount,
+    analyzedFileCount,
+    parseFailureCount,
+    analyzerFailureCount,
+    unreadableFileCount,
+    scanFailureCount
+  };
+  let status;
+  let reasonCode;
+  let analyzer = null;
+  if (candidates.length === 0) {
+    status = 'unavailable';
+    reasonCode = 'ANALYZER_UNAVAILABLE';
+  } else if (candidates.length > 1) {
+    status = 'unavailable';
+    reasonCode = 'ANALYZER_AMBIGUOUS';
+  } else {
+    analyzer = { id: candidates[0].id, version: candidates[0].version };
+    const failureCount = parseFailureCount + analyzerFailureCount
+      + unreadableFileCount + scanFailureCount;
+    if (failureCount === 0) {
+      status = 'complete';
+      reasonCode = 'COVERAGE_COMPLETE';
+    } else if (analyzerFailureCount > 0 && analyzedFileCount === 0 && parseFailureCount === 0) {
+      status = 'failed';
+      reasonCode = failureReason(counts);
+    } else {
+      status = 'partial';
+      reasonCode = failureReason(counts);
+    }
+  }
+  return {
+    projectId,
+    projectPath,
+    ecosystem,
+    status,
+    analyzer,
+    ...counts,
+    reasonCode
+  };
+}
+
+export function unavailableLegacyCoverage(projectId, ecosystem = null) {
+  return {
+    projectId,
+    projectPath: null,
+    ecosystem,
+    status: 'unavailable',
+    analyzer: null,
+    scannedFileCount: 0,
+    analyzedFileCount: 0,
+    parseFailureCount: 0,
+    analyzerFailureCount: 0,
+    unreadableFileCount: 0,
+    scanFailureCount: 0,
+    reasonCode: 'COVERAGE_METADATA_MISSING'
+  };
+}
+
+export function coverageForProject(usageIndex, projectId, ecosystem = null) {
+  return usageIndex?.analysis?.coverage?.find((item) => item.projectId === projectId)
+    ?? unavailableLegacyCoverage(projectId, ecosystem);
+}

package/src/usage/input-loader.js

@@ -0,0 +1,139 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import {
+  DEFAULT_MANIFEST_PATH,
+  DEFAULT_VERSION_ANALYSIS_PATH,
+  VERSION_ANALYSIS_SCHEMA_VERSION
+} from '../constants.js';
+import { isPortableRelativePath } from '../portable.js';
+import { loadProjectManifestInput } from '../project-manifest-input.js';
+import { validateVersionAnalysisManifest } from '../version-analysis-manifest.js';
+
+export class UsageDiscoveryInputError extends Error {
+  constructor(message, code = 'USAGE_DISCOVERY_INPUT_INVALID') {
+    super(`Usage Discovery input error: ${message}`);
+    this.name = 'UsageDiscoveryInputError';
+    this.code = code;
+  }
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+async function readBytes(source, label) {
+  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 UsageDiscoveryInputError(`${label} source must be a file path or { bytes, artifact }.`);
+}
+
+function artifactFor(source, configured, defaultArtifact, label) {
+  const artifact = source && typeof source === 'object' && 'bytes' in source
+    ? source.artifact
+    : configured ?? defaultArtifact;
+  if (!isPortableRelativePath(artifact)) {
+    throw new UsageDiscoveryInputError(`${label} artifact must be a portable repository-relative path.`);
+  }
+  return artifact;
+}
+
+function validateLineage(projectInput, versionAnalysis) {
+  const expected = versionAnalysis.input.projectManifest;
+  const actual = projectInput.input.projectManifest;
+  const mismatches = [];
+  if (expected.schemaVersion !== actual.schemaVersion) mismatches.push('schemaVersion');
+  if (expected.artifactDigest !== actual.artifactDigest) mismatches.push('artifactDigest');
+  if (expected.repository.name !== actual.repository.name) mismatches.push('repository.name');
+  if (expected.repository.root !== actual.repository.root) mismatches.push('repository.root');
+  if (mismatches.length > 0) {
+    throw new UsageDiscoveryInputError(
+      `Version Analysis Project Manifest lineage mismatch: ${mismatches.join(', ')}.`,
+      'LINEAGE_MISMATCH'
+    );
+  }
+}
+
+function validateDependencyReferences(projectManifest, versionAnalysis) {
+  const projects = new Map(projectManifest.projects.map((project) => [project.id, project]));
+  const errors = [];
+  for (const result of versionAnalysis.results) {
+    const occurrence = result.dependency;
+    const project = projects.get(occurrence.projectId);
+    if (!project) {
+      errors.push(`${occurrence.packageId} references unknown project ${occurrence.projectId}`);
+      continue;
+    }
+    const declared = project.dependencies.some((dependency) => (
+      dependency.normalizedName === occurrence.normalizedName
+      && dependency.type === occurrence.dependencyType
+      && dependency.manifest === occurrence.manifest
+    ));
+    if (!declared) {
+      errors.push(`${occurrence.packageId} does not match a declared dependency in ${occurrence.projectId}`);
+    }
+    if (project.ecosystem !== occurrence.ecosystem) {
+      errors.push(`${occurrence.packageId} ecosystem does not match project ${occurrence.projectId}`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new UsageDiscoveryInputError(`invalid dependency references: ${errors.sort().join('; ')}.`);
+  }
+}
+
+export async function loadUsageDiscoveryInputs(sources, options = {}) {
+  if (!sources?.projectManifest || !sources?.versionAnalysis) {
+    throw new UsageDiscoveryInputError('projectManifest and versionAnalysis sources are required.');
+  }
+  const projectArtifact = artifactFor(
+    sources.projectManifest,
+    options.projectManifestArtifact,
+    DEFAULT_MANIFEST_PATH,
+    'Project Manifest'
+  );
+  const versionArtifact = artifactFor(
+    sources.versionAnalysis,
+    options.versionAnalysisArtifact,
+    DEFAULT_VERSION_ANALYSIS_PATH,
+    'Version Analysis'
+  );
+  const [projectInput, versionBytes] = await Promise.all([
+    loadProjectManifestInput(sources.projectManifest, { artifact: projectArtifact }),
+    readBytes(sources.versionAnalysis, 'Version Analysis')
+  ]);
+
+  let versionAnalysis;
+  try {
+    versionAnalysis = JSON.parse(versionBytes.toString('utf8'));
+  } catch {
+    throw new UsageDiscoveryInputError('Version Analysis bytes are not valid JSON.');
+  }
+  if (versionAnalysis?.schemaVersion !== VERSION_ANALYSIS_SCHEMA_VERSION) {
+    throw new UsageDiscoveryInputError(
+      `unsupported Version Analysis schema version; expected ${VERSION_ANALYSIS_SCHEMA_VERSION}.`
+    );
+  }
+  try {
+    validateVersionAnalysisManifest(versionAnalysis);
+  } catch (error) {
+    throw new UsageDiscoveryInputError(error.message);
+  }
+  validateLineage(projectInput, versionAnalysis);
+  validateDependencyReferences(projectInput.manifest, versionAnalysis);
+
+  return {
+    projectManifest: projectInput.manifest,
+    versionAnalysis,
+    input: {
+      projectManifest: projectInput.input.projectManifest,
+      versionAnalysis: {
+        schemaVersion: versionAnalysis.schemaVersion,
+        artifact: versionArtifact,
+        artifactDigest: digest(versionBytes)
+      }
+    }
+  };
+}
+

package/src/usage/js/analyzer.js

@@ -0,0 +1,240 @@
+import { parseJavaScriptSource } from './parser.js';
+
+export const JAVASCRIPT_USAGE_ANALYZER_ID = 'javascript-typescript';
+export const JAVASCRIPT_USAGE_ANALYZER_VERSION = '1.0.0';
+export const JAVASCRIPT_SOURCE_EXTENSIONS = Object.freeze([
+  '.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx'
+]);
+
+const SKIPPED_KEYS = new Set(['loc', 'start', 'end', 'extra', 'errors', 'tokens', 'comments']);
+
+function childEntries(node) {
+  const entries = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (SKIPPED_KEYS.has(key)) continue;
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child.type === 'string') entries.push([child, key]);
+      }
+    } else if (value && typeof value.type === 'string') entries.push([value, key]);
+  }
+  return entries;
+}
+
+function walk(node, visitor, parent = null, key = null, ancestors = []) {
+  visitor(node, parent, key, ancestors);
+  for (const [child, childKey] of childEntries(node)) {
+    walk(child, visitor, node, childKey, [...ancestors, node]);
+  }
+}
+
+function importedName(specifier) {
+  if (specifier.type === 'ImportDefaultSpecifier') return 'default';
+  if (specifier.type === 'ImportNamespaceSpecifier') return '*';
+  return specifier.imported?.name ?? specifier.imported?.value;
+}
+
+function exportedName(specifier) {
+  if (specifier.type === 'ExportNamespaceSpecifier') return '*';
+  return specifier.local?.name ?? specifier.local?.value;
+}
+
+function moduleName(node) {
+  return typeof node?.value === 'string' ? node.value : null;
+}
+
+export function npmPackageName(specifier) {
+  if (typeof specifier !== 'string' || specifier.length === 0) return null;
+  if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('#')
+      || specifier.startsWith('node:') || /^[a-z][a-z+.-]*:/i.test(specifier)) return null;
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+
+function createDependencyMatcher(dependencies) {
+  const candidates = [...dependencies]
+    .filter((item) => typeof item.name === 'string' && item.name.length > 0)
+    .sort((left, right) => right.name.length - left.name.length || left.name.localeCompare(right.name));
+  return (specifier) => {
+    const root = npmPackageName(specifier);
+    if (!root) return null;
+    return candidates.find((item) => root === item.name) ?? null;
+  };
+}
+
+function patternNames(pattern, names = []) {
+  if (!pattern) return names;
+  if (pattern.type === 'Identifier') names.push(pattern.name);
+  else if (pattern.type === 'RestElement') patternNames(pattern.argument, names);
+  else if (pattern.type === 'AssignmentPattern') patternNames(pattern.left, names);
+  else if (pattern.type === 'ObjectPattern') {
+    for (const property of pattern.properties) {
+      patternNames(property.type === 'RestElement' ? property.argument : property.value, names);
+    }
+  } else if (pattern.type === 'ArrayPattern') {
+    for (const element of pattern.elements) patternNames(element, names);
+  } else if (pattern.type === 'TSParameterProperty') patternNames(pattern.parameter, names);
+  return names;
+}
+
+function nearestScope(ancestors, kind = 'lexical') {
+  const candidates = [...ancestors].reverse();
+  if (kind === 'var') {
+    return candidates.find((node) => node.type === 'Program' || /^(Function)/.test(node.type));
+  }
+  return candidates.find((node) => (
+    node.type === 'Program' || node.type === 'BlockStatement' || node.type === 'CatchClause'
+    || /^(Function)/.test(node.type)
+  ));
+}
+
+function addShadow(shadows, names, scope) {
+  if (!scope || typeof scope.start !== 'number' || typeof scope.end !== 'number') return;
+  for (const name of names) {
+    if (!shadows.has(name)) shadows.set(name, []);
+    shadows.get(name).push([scope.start, scope.end]);
+  }
+}
+
+function collectShadowRanges(program, importedBindings) {
+  const shadows = new Map();
+  walk(program, (node, parent, key, ancestors) => {
+    if (node.type === 'VariableDeclaration') {
+      const names = node.declarations.flatMap((declaration) => patternNames(declaration.id));
+      addShadow(shadows, names.filter((name) => importedBindings.has(name)), nearestScope(ancestors, node.kind));
+    } else if (/^Function/.test(node.type)) {
+      const names = node.params.flatMap((parameter) => patternNames(parameter));
+      addShadow(shadows, names.filter((name) => importedBindings.has(name)), node);
+      if (node.type === 'FunctionDeclaration' && node.id && importedBindings.has(node.id.name)) {
+        addShadow(shadows, [node.id.name], nearestScope(ancestors));
+      } else if (node.type === 'FunctionExpression' && node.id && importedBindings.has(node.id.name)) {
+        addShadow(shadows, [node.id.name], node.body);
+      }
+    } else if (node.type === 'ClassDeclaration' && node.id && importedBindings.has(node.id.name)) {
+      addShadow(shadows, [node.id.name], nearestScope(ancestors));
+    } else if (node.type === 'CatchClause') {
+      const names = patternNames(node.param).filter((name) => importedBindings.has(name));
+      addShadow(shadows, names, node.body);
+    } else if (/^TS(?:Interface|TypeAlias|Enum|Module)Declaration$/.test(node.type)
+        && node.id?.name && importedBindings.has(node.id.name)) {
+      addShadow(shadows, [node.id.name], nearestScope(ancestors));
+    }
+  });
+  return shadows;
+}
+
+function isShadowed(shadows, name, node) {
+  return (shadows.get(name) ?? []).some(([start, end]) => node.start >= start && node.end <= end);
+}
+
+function isDeclarationIdentifier(node, parent, key) {
+  if (!parent) return false;
+  if (parent.type.startsWith('Import')) return true;
+  if ((parent.type === 'VariableDeclarator' || parent.type === 'AssignmentPattern') && key === 'id') return true;
+  if (/^(Function|Class)/.test(parent.type) && (key === 'id' || key === 'params')) return true;
+  if ((parent.type === 'RestElement' || parent.type === 'TSParameterProperty') && key === 'argument') return true;
+  if (parent.type === 'CatchClause' && key === 'param') return true;
+  return false;
+}
+
+function isReferenceIdentifier(node, parent, key) {
+  if (!parent || isDeclarationIdentifier(node, parent, key)) return false;
+  if ((parent.type === 'MemberExpression' || parent.type === 'OptionalMemberExpression')
+      && key === 'property' && !parent.computed) return false;
+  if (parent.type === 'JSXMemberExpression' && key === 'property') return false;
+  if (parent.type === 'JSXAttribute' && key === 'name') return false;
+  if ((parent.type === 'ObjectProperty' || parent.type === 'ObjectMethod' || parent.type === 'ClassMethod'
+      || parent.type === 'ClassProperty' || parent.type === 'ClassAccessorProperty')
+      && key === 'key' && !parent.computed) return false;
+  if (parent.type === 'ExportSpecifier' && key === 'exported') return false;
+  if (parent.type === 'LabeledStatement' || parent.type === 'BreakStatement' || parent.type === 'ContinueStatement') {
+    return false;
+  }
+  if (parent.type.startsWith('TS') && ['key', 'id'].includes(key)
+      && !['TSTypeReference', 'TSExpressionWithTypeArguments', 'TSTypeQuery'].includes(parent.type)) return false;
+  return true;
+}
+
+function namespaceMember(node, parent, key) {
+  if ((parent?.type === 'MemberExpression' || parent?.type === 'OptionalMemberExpression')
+      && key === 'object') {
+    if (!parent.computed && parent.property.type === 'Identifier') return parent.property.name;
+    if (parent.computed && parent.property.type === 'StringLiteral') return parent.property.value;
+  }
+  if (node.type === 'JSXIdentifier' && parent?.type === 'JSXMemberExpression' && key === 'object') {
+    return parent.property.name;
+  }
+  return '*';
+}
+
+function addUsage(usages, dependency, symbol, file) {
+  if (!dependency || (symbol !== null && (typeof symbol !== 'string' || symbol.length === 0))) return;
+  usages.set(`${dependency.packageId}\0${symbol ?? '<dependency>'}`, {
+    packageId: dependency.packageId,
+    dependency: dependency.name,
+    symbol,
+    file
+  });
+}
+
+export function analyzeJavaScriptUsage({ source, file, dependencies }) {
+  const ast = parseJavaScriptSource(source, file);
+  const matchDependency = createDependencyMatcher(dependencies);
+  const bindings = new Map();
+  const usages = new Map();
+
+  for (const statement of ast.program.body) {
+    if (statement.type === 'ImportDeclaration') {
+      const dependency = matchDependency(moduleName(statement.source));
+      if (!dependency) continue;
+      if (statement.specifiers.length === 0) addUsage(usages, dependency, null, file);
+      for (const specifier of statement.specifiers) {
+        bindings.set(specifier.local.name, {
+          dependency,
+          symbol: importedName(specifier),
+          namespace: specifier.type === 'ImportNamespaceSpecifier',
+          declaration: specifier.local
+        });
+      }
+    } else if (statement.type === 'ExportNamedDeclaration' && statement.source) {
+      const dependency = matchDependency(moduleName(statement.source));
+      for (const specifier of statement.specifiers) {
+        addUsage(usages, dependency, exportedName(specifier), file);
+      }
+    } else if (statement.type === 'ExportAllDeclaration') {
+      addUsage(usages, matchDependency(moduleName(statement.source)), '*', file);
+    }
+  }
+
+  const shadows = collectShadowRanges(ast.program, bindings);
+  walk(ast.program, (node, parent, key) => {
+    if (node.type === 'ImportExpression') {
+      addUsage(usages, matchDependency(moduleName(node.source)), '*', file);
+      return;
+    }
+    if (node.type !== 'Identifier' && node.type !== 'JSXIdentifier') return;
+    const binding = bindings.get(node.name);
+    if (!binding || node === binding.declaration || isShadowed(shadows, node.name, node)
+        || !isReferenceIdentifier(node, parent, key)) return;
+    addUsage(
+      usages,
+      binding.dependency,
+      binding.namespace ? namespaceMember(node, parent, key) : binding.symbol,
+      file
+    );
+  });
+
+  return [...usages.values()].sort((left, right) => (
+    left.packageId.localeCompare(right.packageId) || (left.symbol ?? '').localeCompare(right.symbol ?? '')
+  ));
+}
+
+export function createJavaScriptUsageAnalyzer() {
+  return Object.freeze({
+    id: JAVASCRIPT_USAGE_ANALYZER_ID,
+    version: JAVASCRIPT_USAGE_ANALYZER_VERSION,
+    ecosystems: Object.freeze(['node']),
+    extensions: JAVASCRIPT_SOURCE_EXTENSIONS,
+    analyze: analyzeJavaScriptUsage
+  });
+}

package/src/usage/js/parser.js

@@ -0,0 +1,21 @@
+import { parse } from '@babel/parser';
+
+export function parseJavaScriptSource(source, filePath = '<source>') {
+  return parse(source, {
+    sourceFilename: filePath,
+    sourceType: 'unambiguous',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    createImportExpressions: true,
+    plugins: [
+      'jsx',
+      'typescript',
+      'decoratorAutoAccessors',
+      ['decorators', { decoratorsBeforeExport: true }],
+      'explicitResourceManagement',
+      'importAttributes'
+    ]
+  });
+}
+
+export const parseJavaScriptModule = parseJavaScriptSource;