@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/product-completion.js

@@ -0,0 +1,249 @@
+import { compareText } from './portable.js';
+
+export const PRODUCT_COMPLETION_SCHEMA_VERSION = '1.0.0';
+export const PRODUCT_COMPLETION_STATUSES = Object.freeze([
+  'COMPLETED',
+  'COMPLETED_WITH_REVIEW',
+  'PARTIAL',
+  'INSUFFICIENT_DATA',
+  'FAILED',
+  'CANCELLED'
+]);
+
+const HANDOFF_STATUSES = Object.freeze([
+  'NO_VERSION_CHANGE_REQUIRED',
+  'ACTIONABLE_WITH_REVIEW',
+  'INVESTIGATION_REQUIRED',
+  'INSUFFICIENT_EVIDENCE',
+  'NOT_ANALYZED',
+  'ACTION_GENERATION_FAILED',
+  'NO_GROUNDED_ACTION'
+]);
+
+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 handoffByDecision(migrationChecklistViewModel) {
+  return new Map((migrationChecklistViewModel?.dependencies ?? []).map((dependency) => [
+    dependency.decisionId,
+    dependency
+  ]));
+}
+
+function analysisById(versionAnalysis) {
+  return new Map((versionAnalysis?.results ?? []).map((result) => [result.id, result]));
+}
+
+function failureCodes(record, analysis) {
+  return [...new Set([
+    ...record.reasonCodes,
+    ...(analysis?.humanReviewReasons ?? []),
+    ...(analysis?.limitations ?? []).map((item) => item.code)
+  ])].sort(compareText);
+}
+
+function failureRecovery(codes) {
+  if (codes.includes('INSUFFICIENT_CREDIT')) {
+    return 'Add credit or change the configured provider, then rerun the failed dependency analysis.';
+  }
+  if (codes.some((code) => code.includes('RATE_LIMIT'))) {
+    return 'Wait for the configured provider rate limit to clear, then rerun the failed dependency analysis.';
+  }
+  if (codes.some((code) => /OUTPUT|SCHEMA|REJECT/.test(code))) {
+    return 'The provider output was rejected and was not published; review or rerun the failed dependency analysis.';
+  }
+  if (codes.some((code) => /TIMEOUT|PROVIDER|RUNTIME/.test(code))) {
+    return 'Resolve the configured provider/runtime failure, then rerun the failed dependency analysis.';
+  }
+  return 'Review the failed Version Analysis occurrence and rerun it after resolving the recorded limitation.';
+}
+
+function nextStepFor(record, handoff) {
+  if (handoff?.nextStep?.message) return handoff.nextStep.message;
+  if (record.decision === 'KEEP_CURRENT') return 'No version change is required for this target.';
+  if (record.decision === 'PLAN_UPGRADE' || record.decision === 'UPGRADE_NOW') {
+    return 'Review the evidence-bounded migration handoff before changing source or dependency declarations.';
+  }
+  if (record.decision === 'INVESTIGATE') {
+    if (record.primaryReasonCode === 'UPGRADE_AVAILABLE_NO_RECOMMENDATION_DRIVER') {
+      return 'A newer version is available, but no upgrade target has been selected; use --target to select one.';
+    }
+    return 'Complete the stated human investigation before selecting migration work.';
+  }
+  if (record.primaryReasonCode === 'INSTALLED_VERSION_UNAVAILABLE') {
+    return 'Resolve the installed version baseline and rerun analysis.';
+  }
+  if (record.primaryReasonCode === 'TARGET_VERSION_UNAVAILABLE') {
+    return 'Refresh research when external verification is available or select a validated explicit target.';
+  }
+  if (record.decision === 'INSUFFICIENT_EVIDENCE') {
+    return 'Collect valid target-scoped evidence and rerun analysis.';
+  }
+  if (record.primaryReasonCode === 'VERSION_ANALYSIS_SKIPPED') {
+    return 'Resolve the missing baseline, target, or evidence and rerun Version Analysis.';
+  }
+  return 'Resolve the failed Version Analysis occurrence and rerun it.';
+}
+
+function coverageLabel(record) {
+  const coverage = record.impact.coverage.status;
+  const values = {
+    complete: record.impact.status === 'IMPACTED' ? 'Impacted; complete coverage' : 'Complete coverage',
+    partial: 'Partial coverage',
+    unavailable: 'Coverage unavailable',
+    failed: 'Coverage failed',
+    missing: 'Coverage unavailable'
+  };
+  return values[coverage] ?? 'Coverage unknown';
+}
+
+function compareDecisions(left, right) {
+  return compareText(left.projectId, right.projectId)
+    || compareText(left.manifest, right.manifest)
+    || compareText(left.packageId, right.packageId)
+    || compareText(left.dependencyType, right.dependencyType)
+    || compareText(left.id, right.id);
+}
+
+function overallNextStep(status, decisions) {
+  if (status === 'PARTIAL') {
+    return 'Resolve the listed provider/output/runtime failures and rerun the failed occurrences.';
+  }
+  if (status === 'INSUFFICIENT_DATA') {
+    return 'Resolve missing installed baselines or target-scoped evidence, then rerun analysis.';
+  }
+  if (status === 'COMPLETED_WITH_REVIEW') {
+    if (decisions.some((item) => item.handoffStatus === 'ACTIONABLE_WITH_REVIEW')) {
+      return 'Review and approve the evidence-bounded migration handoff before source changes.';
+    }
+    if (decisions.some((item) => (
+      item.decision === 'INVESTIGATE'
+      && item.nextStep.includes('--target')
+    ))) {
+      return 'Review investigation results; use --target for any dependency you choose to plan.';
+    }
+    return 'Review the listed dependency decisions and coverage limitations.';
+  }
+  return 'No additional version change is required for the evaluated targets.';
+}
+
+export function buildProductCompletion({
+  upgradeDecision,
+  versionAnalysis = null,
+  migrationChecklistViewModel = null,
+  artifactPaths = {}
+}) {
+  if (!upgradeDecision?.summary || !Array.isArray(upgradeDecision.decisions)) {
+    throw new Error('Product completion requires a persisted Upgrade Decision artifact.');
+  }
+  const handoffs = handoffByDecision(migrationChecklistViewModel);
+  const analyses = analysisById(versionAnalysis);
+  const decisions = upgradeDecision.decisions.map((record) => {
+    const handoff = handoffs.get(record.id) ?? null;
+    return {
+      id: record.id,
+      analysisResultId: record.analysisResultId,
+      projectId: record.occurrence.projectId,
+      manifest: record.occurrence.manifest,
+      dependencyType: record.occurrence.dependencyType,
+      packageId: record.occurrence.packageId,
+      dependency: record.occurrence.declaredName,
+      installedVersion: record.versions.installedVersion,
+      targetVersion: record.versions.targetVersion,
+      targetOrigin: record.versions.targetPolicy,
+      decision: record.decision,
+      explanation: record.summary,
+      coverage: coverageLabel(record),
+      handoffStatus: handoff?.handoffStatus ?? null,
+      nextStep: nextStepFor(record, handoff),
+      requiresHumanReview: record.requiresHumanReview
+    };
+  }).sort(compareDecisions);
+  const failedOccurrences = upgradeDecision.decisions.flatMap((record) => {
+    const handoff = handoffs.get(record.id);
+    const versionFailed = record.reasonCodes.includes('VERSION_ANALYSIS_FAILED');
+    const actionFailed = handoff?.handoffStatus === 'ACTION_GENERATION_FAILED';
+    if (!versionFailed && !actionFailed) return [];
+    const analysis = analyses.get(record.analysisResultId);
+    const codes = failureCodes(record, analysis);
+    return [{
+      decisionId: record.id,
+      projectId: record.occurrence.projectId,
+      manifest: record.occurrence.manifest,
+      dependencyType: record.occurrence.dependencyType,
+      packageId: record.occurrence.packageId,
+      dependency: record.occurrence.declaredName,
+      stage: actionFailed ? 'Migration Checklist' : 'Version Analysis',
+      failureType: actionFailed ? 'ACTION_GENERATION_FAILED' : 'VERSION_ANALYSIS_FAILED',
+      recovery: actionFailed
+        ? 'Review the rejected or failed migration action manually, then rerun Migration Checklist.'
+        : failureRecovery(codes)
+    }];
+  }).sort(compareDecisions);
+  const explicitInsufficient = upgradeDecision.decisions.some((record) => (
+    record.versions.targetPolicy === 'explicit'
+    && record.decision === 'INSUFFICIENT_EVIDENCE'
+  ));
+  const unansweredCount = upgradeDecision.decisions.filter((record) => (
+    record.decision === 'INSUFFICIENT_EVIDENCE'
+    || (record.decision === 'NOT_ANALYZED'
+      && !record.reasonCodes.includes('VERSION_ANALYSIS_FAILED'))
+  )).length;
+  const majorityUnanswered = upgradeDecision.decisions.length > 0
+    && unansweredCount * 2 > upgradeDecision.decisions.length;
+  const hasReview = upgradeDecision.decisions.some((record) => (
+    record.requiresHumanReview
+    || ['PLAN_UPGRADE', 'UPGRADE_NOW', 'INVESTIGATE'].includes(record.decision)
+    || record.impact.coverage.status !== 'complete'
+  ));
+  const actionGenerationFailed = [...handoffs.values()].some((handoff) => (
+    handoff.handoffStatus === 'ACTION_GENERATION_FAILED'
+  ));
+  const status = failedOccurrences.length > 0 || actionGenerationFailed
+    ? 'PARTIAL'
+    : explicitInsufficient || majorityUnanswered
+      ? 'INSUFFICIENT_DATA'
+      : hasReview
+        ? 'COMPLETED_WITH_REVIEW'
+        : 'COMPLETED';
+  const handoffCounts = Object.fromEntries(HANDOFF_STATUSES.map((value) => [
+    value,
+    migrationChecklistViewModel?.summary?.handoffStatusCounts?.[value] ?? 0
+  ]));
+  const output = {
+    schemaVersion: PRODUCT_COMPLETION_SCHEMA_VERSION,
+    status,
+    nextStep: overallNextStep(status, decisions),
+    decisionCounts: {
+      KEEP_CURRENT: upgradeDecision.summary.KEEP_CURRENT,
+      UPGRADE_NOW: upgradeDecision.summary.UPGRADE_NOW,
+      PLAN_UPGRADE: upgradeDecision.summary.PLAN_UPGRADE,
+      INVESTIGATE: upgradeDecision.summary.INVESTIGATE,
+      INSUFFICIENT_EVIDENCE: upgradeDecision.summary.INSUFFICIENT_EVIDENCE,
+      NOT_ANALYZED: upgradeDecision.summary.NOT_ANALYZED
+    },
+    handoffCounts,
+    reviewRequiredCount: upgradeDecision.summary.requiresHumanReviewCount,
+    failedOccurrences,
+    decisions,
+    artifactPaths: {
+      report: artifactPaths.report ?? null,
+      upgradeDecision: artifactPaths.upgradeDecision ?? null,
+      migrationChecklist: artifactPaths.migrationChecklist ?? null
+    }
+  };
+  return deepFreeze(output);
+}
+
+export function productCompletionExitCode(completion, { strict = false } = {}) {
+  if (completion.status === 'FAILED') return 1;
+  if (completion.status === 'CANCELLED') return 130;
+  if (completion.status === 'PARTIAL') return 2;
+  if (strict && ['COMPLETED_WITH_REVIEW', 'INSUFFICIENT_DATA'].includes(completion.status)) {
+    return 2;
+  }
+  return 0;
+}

package/src/project-manifest-input.js

@@ -0,0 +1,90 @@
+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_MANIFEST_PATH, MANIFEST_SCHEMA_VERSION } from './constants.js';
+import { isPortableRelativePath } from './portable.js';
+import { validateProjectManifestInvariants } from './project-manifest.js';
+
+const schema = JSON.parse(await readFile(
+  new URL('../schemas/project-manifest.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+function inputError(message) {
+  return new Error(`Project Manifest input error: ${message}`);
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function parseManifest(bytes) {
+  try {
+    return JSON.parse(Buffer.from(bytes).toString('utf8'));
+  } catch {
+    throw inputError('manifest bytes are not valid JSON.');
+  }
+}
+
+function artifactFor(source, options) {
+  const artifact = typeof source === 'object' && source !== null && 'bytes' in source
+    ? source.artifact
+    : options.artifact ?? DEFAULT_MANIFEST_PATH;
+  if (!isPortableRelativePath(artifact)) {
+    throw inputError('artifact must be a portable repository-relative path.');
+  }
+  return artifact;
+}
+
+async function readInputBytes(source) {
+  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('bytes must be a Uint8Array or Buffer.');
+    }
+    return Buffer.from(source.bytes);
+  }
+  throw inputError('source must be a manifest file path or { bytes, artifact }.');
+}
+
+/**
+ * Read one exact Project Manifest byte sequence, validate it, and return its
+ * parsed value together with portable lineage for research planning.
+ */
+export async function loadProjectManifestInput(source, options = {}) {
+  const artifact = artifactFor(source, options);
+  const bytes = await readInputBytes(source);
+  const manifest = parseManifest(bytes);
+
+  if (manifest?.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    throw inputError(`unsupported schema version; expected ${MANIFEST_SCHEMA_VERSION}.`);
+  }
+  if (!validateSchema(manifest)) {
+    throw inputError(`schema validation failed: ${ajv.errorsText(validateSchema.errors, { separator: '; ' })}`);
+  }
+  const invariantErrors = validateProjectManifestInvariants(manifest);
+  if (invariantErrors.length > 0) {
+    throw inputError(`runtime invariants failed: ${invariantErrors.join(' ')}`);
+  }
+
+  return {
+    manifest,
+    input: {
+      projectManifest: {
+        schemaVersion: manifest.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes),
+        repository: {
+          name: manifest.repository.name,
+          root: manifest.repository.root
+        }
+      }
+    }
+  };
+}

package/src/project-manifest.js

@@ -0,0 +1,141 @@
+import { compareText, isPortableRelativePath } from './portable.js';
+
+const NODE_DEPENDENCY_TYPES = {
+  dependency: 'dependencies',
+  devDependency: 'devDependencies',
+  optionalDependency: 'optionalDependencies',
+  peerDependency: 'peerDependencies'
+};
+
+function addMismatch(errors, field, actual, expected) {
+  if (actual !== expected) errors.push(`${field} is ${actual}; expected ${expected}.`);
+}
+
+/**
+ * Validate relationships in a Project Manifest that JSON Schema cannot compare.
+ * Input ordering is intentionally not required here because research planning
+ * canonicalizes its own output independently of manifest array order.
+ */
+export function validateProjectManifestInvariants(manifest) {
+  const errors = [];
+  const projects = manifest.projects ?? [];
+  const ecosystems = {};
+  const projectIds = new Set();
+
+  for (const project of projects) {
+    if (projectIds.has(project.id)) errors.push(`Duplicate project id ${project.id}.`);
+    projectIds.add(project.id);
+    ecosystems[project.ecosystem] = (ecosystems[project.ecosystem] ?? 0) + 1;
+    if (!isPortableRelativePath(project.path)) {
+      errors.push(`Project ${project.id} has a non-portable path.`);
+    }
+    for (const manifestPath of project.manifests) {
+      if (!isPortableRelativePath(manifestPath)) {
+        errors.push(`Project ${project.id} has a non-portable manifest path.`);
+      }
+    }
+    if (project.workspace && !isPortableRelativePath(project.workspace.root)) {
+      errors.push(`Project ${project.id} has a non-portable workspace root.`);
+    }
+
+    const dependencies = project.dependencies;
+    for (const dependency of dependencies) {
+      if (!isPortableRelativePath(dependency.manifest)) {
+        errors.push(`Project ${project.id} has a dependency with a non-portable manifest path.`);
+      }
+      const baselineFields = [
+        'installedVersion',
+        'installedVersionStatus',
+        'installedVersionSource',
+        'installedVersionReason'
+      ];
+      const baselineFieldCount = baselineFields.filter((field) => field in dependency).length;
+      if (baselineFieldCount !== 0 && baselineFieldCount !== baselineFields.length) {
+        errors.push(`Project ${project.id} dependency ${dependency.name} has an incomplete installed-version baseline.`);
+      }
+      if (baselineFieldCount === baselineFields.length) {
+        if (dependency.installedVersionStatus === 'resolved') {
+          if (
+            typeof dependency.installedVersion !== 'string'
+            || dependency.installedVersionSource === null
+            || dependency.installedVersionReason !== null
+          ) {
+            errors.push(`Project ${project.id} dependency ${dependency.name} has inconsistent resolved baseline fields.`);
+          }
+        } else if (
+          dependency.installedVersionStatus === 'unresolved'
+          && (
+            dependency.installedVersion !== null
+            || dependency.installedVersionSource !== null
+            || dependency.installedVersionReason === null
+          )
+        ) {
+          errors.push(`Project ${project.id} dependency ${dependency.name} has inconsistent unresolved baseline fields.`);
+        }
+        if (
+          dependency.installedVersionSource
+          && (
+            !isPortableRelativePath(dependency.installedVersionSource.path)
+            || !isPortableRelativePath(dependency.installedVersionSource.packagePath)
+          )
+        ) {
+          errors.push(`Project ${project.id} dependency ${dependency.name} has non-portable installed-version provenance.`);
+        }
+      }
+    }
+
+    if (project.dependencySummary.status !== 'parsed') {
+      if (dependencies.length !== 0) {
+        errors.push(`Project ${project.id} has dependencies with a non-parsed dependency summary.`);
+      }
+      continue;
+    }
+
+    const summary = project.dependencySummary;
+    const uniqueCount = new Set(dependencies.map((dependency) => dependency.normalizedName)).size;
+    addMismatch(errors, `${project.id}.dependencySummary.declarationCount`, summary.declarationCount, dependencies.length);
+    addMismatch(errors, `${project.id}.dependencySummary.uniqueCount`, summary.uniqueCount, uniqueCount);
+    addMismatch(
+      errors,
+      `${project.id}.dependencySummary.duplicateCount`,
+      summary.duplicateCount,
+      dependencies.length - uniqueCount
+    );
+
+    if (summary.byType) {
+      const byType = {
+        dependencies: 0,
+        devDependencies: 0,
+        peerDependencies: 0,
+        optionalDependencies: 0
+      };
+      for (const dependency of dependencies) {
+        const key = NODE_DEPENDENCY_TYPES[dependency.type];
+        if (key) byType[key] += 1;
+      }
+      for (const [type, count] of Object.entries(byType)) {
+        addMismatch(errors, `${project.id}.dependencySummary.byType.${type}`, summary.byType[type], count);
+      }
+    }
+  }
+
+  addMismatch(errors, 'summary.projectCount', manifest.summary.projectCount, projects.length);
+  addMismatch(
+    errors,
+    'summary.workspaceCount',
+    manifest.summary.workspaceCount,
+    projects.filter((project) => project.workspace?.role === 'root').length
+  );
+
+  const actualEcosystemKeys = Object.keys(ecosystems).sort(compareText);
+  const summaryEcosystemKeys = Object.keys(manifest.summary.ecosystems ?? []).sort(compareText);
+  if (actualEcosystemKeys.join('\0') !== summaryEcosystemKeys.join('\0')) {
+    errors.push('summary.ecosystems does not match project ecosystems.');
+  } else {
+    for (const ecosystem of actualEcosystemKeys) {
+      addMismatch(errors, `summary.ecosystems.${ecosystem}`, manifest.summary.ecosystems[ecosystem], ecosystems[ecosystem]);
+    }
+  }
+
+  return errors.sort(compareText);
+}

package/src/python-requirements.js

@@ -0,0 +1,137 @@
+import {
+  duplicateDependencyNames,
+  sortDependencies,
+  summarizeDependencies
+} from './dependencies.js';
+
+const PACKAGE_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?/;
+const EXTRAS = /^\[([A-Za-z0-9._-]+(?:\s*,\s*[A-Za-z0-9._-]+)*)\]/;
+const VERSION_SPECIFIERS = /^(?:===|==|~=|!=|>=|<=|>|<)\s*[^\s,]+(?:\s*,\s*(?:===|==|~=|!=|>=|<=|>|<)\s*[^\s,]+)*$/;
+
+export function normalizePythonPackageName(name) {
+  return name.toLowerCase().replace(/[-_.]+/g, '-');
+}
+
+function stripInlineComment(line) {
+  for (let index = 0; index < line.length; index += 1) {
+    if (line[index] === '#' && (index === 0 || /\s/.test(line[index - 1]))) {
+      return line.slice(0, index).trim();
+    }
+  }
+  return line.trim();
+}
+
+function packageNameFromEgg(reference) {
+  const encoded = reference.match(/[#&]egg=([^&\s]+)/i)?.[1];
+  if (!encoded) return undefined;
+  let egg;
+  try {
+    egg = decodeURIComponent(encoded);
+  } catch {
+    egg = encoded;
+  }
+  return egg.match(PACKAGE_NAME)?.[0];
+}
+
+function isUnnamedReference(value) {
+  return /^(?:[A-Za-z][A-Za-z0-9+.-]*:|git\+|\.\.?[/\\]|[/\\])/.test(value);
+}
+
+function dependency(name, declaredVersion, type, normalizeName = true) {
+  return {
+    name,
+    normalizedName: normalizeName ? normalizePythonPackageName(name) : name,
+    declaredVersion,
+    type
+  };
+}
+
+function parseNamedRequirement(value) {
+  const nameMatch = value.match(PACKAGE_NAME);
+  if (!nameMatch) return undefined;
+  const name = nameMatch[0];
+  let remainder = value.slice(name.length);
+
+  if (remainder.startsWith('[')) {
+    const extrasMatch = remainder.match(EXTRAS);
+    if (!extrasMatch) return undefined;
+    remainder = remainder.slice(extrasMatch[0].length);
+  }
+
+  remainder = remainder.trim();
+  const markerIndex = remainder.indexOf(';');
+  if (markerIndex >= 0) {
+    const marker = remainder.slice(markerIndex + 1).trim();
+    if (!marker) return undefined;
+    remainder = remainder.slice(0, markerIndex).trim();
+  }
+
+  if (remainder.startsWith('@')) {
+    const reference = remainder.slice(1).trim();
+    return reference ? dependency(name, reference, 'directReference') : undefined;
+  }
+  if (!remainder || VERSION_SPECIFIERS.test(remainder)) {
+    return dependency(name, remainder || null, 'runtime');
+  }
+  return undefined;
+}
+
+function parseRequirementLine(value) {
+  if (/^(?:-r|--requirement)(?:\s+|=)(\S.*)$/.test(value)) return { kind: 'directive' };
+  if (/^(?:-c|--constraint)(?:\s+|=)(\S.*)$/.test(value)) return { kind: 'directive' };
+  if (/^(?:-r|--requirement|-c|--constraint)$/.test(value)) {
+    return { kind: 'invalid', reason: 'include or constraint directive is missing a path' };
+  }
+
+  const editable = value.match(/^(?:-e|--editable)(?:\s+|=)(\S.*)$/);
+  if (editable) {
+    const target = editable[1];
+    const named = packageNameFromEgg(target) ?? parseNamedRequirement(target)?.name;
+    return {
+      kind: 'dependency',
+      dependency: dependency(named ?? target, target, 'editable', named !== undefined)
+    };
+  }
+  if (/^(?:-e|--editable)$/.test(value)) {
+    return { kind: 'invalid', reason: 'editable directive is missing a target' };
+  }
+
+  if (/^--(?:index-url|extra-index-url)(?:\s+|=)/.test(value)) return { kind: 'option' };
+  if (/^--[A-Za-z0-9-]+(?:\s|=|$)/.test(value)) return { kind: 'option' };
+  if (/^-[A-Za-z]/.test(value)) return { kind: 'option' };
+
+  if (isUnnamedReference(value)) {
+    const name = packageNameFromEgg(value);
+    return {
+      kind: 'dependency',
+      dependency: dependency(name ?? value, value, 'directReference', name !== undefined)
+    };
+  }
+
+  const parsed = parseNamedRequirement(value);
+  return parsed
+    ? { kind: 'dependency', dependency: parsed }
+    : { kind: 'invalid', reason: 'unsupported or malformed requirement' };
+}
+
+export function parseRequirementsTxt(contents) {
+  const dependencies = [];
+  const issues = [];
+  const lines = contents.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const value = stripInlineComment(lines[index]);
+    if (!value) continue;
+    const result = parseRequirementLine(value);
+    if (result.kind === 'dependency') dependencies.push(result.dependency);
+    else if (result.kind === 'invalid') issues.push({ line: index + 1, reason: result.reason });
+  }
+
+  const sortedDependencies = sortDependencies(dependencies);
+  return {
+    dependencies: sortedDependencies,
+    dependencySummary: summarizeDependencies(sortedDependencies),
+    duplicateNames: duplicateDependencyNames(sortedDependencies),
+    issues
+  };
+}