@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/source-url.js

@@ -0,0 +1,62 @@
+import { isIP } from 'node:net';
+
+function unsafeIpLiteral(hostname) {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  const type = isIP(host);
+  if (type === 4) {
+    const [first, second] = host.split('.').map(Number);
+    return first === 0 || first === 10 || first === 127
+      || (first === 169 && second === 254)
+      || (first === 172 && second >= 16 && second <= 31)
+      || (first === 192 && second === 168);
+  }
+  if (type === 6) {
+    return host === '::1' || host.startsWith('fc') || host.startsWith('fd')
+      || /^fe[89ab]/.test(host) || host.startsWith('::ffff:');
+  }
+  return false;
+}
+
+function publicHostname(hostname) {
+  const host = hostname.toLowerCase().replace(/\.$/, '');
+  return host !== 'localhost' && !host.endsWith('.localhost') && !unsafeIpLiteral(host);
+}
+
+function normalizedPath(url) {
+  let pathname = url.pathname.replace(/\/+$/g, '') || '/';
+  if (url.hostname.toLowerCase() === 'github.com') {
+    pathname = pathname.replace(/\.git$/i, '').replace(/\/+$/g, '') || '/';
+  }
+  return pathname;
+}
+
+/**
+ * Convert a publisher-provided public URL into its portable form. This helper
+ * performs no DNS lookup, redirect handling, or network access.
+ */
+export function canonicalizeSourceUrl(value, { role = null } = {}) {
+  if (typeof value !== 'string' || value.trim() === '') return null;
+  const raw = value.trim();
+  const gitHttps = /^git\+https:/i.test(raw);
+  if (gitHttps && role !== 'repository') return null;
+  const candidate = gitHttps ? raw.replace(/^git\+/i, '') : raw;
+
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || !publicHostname(url.hostname)) {
+    return null;
+  }
+
+  url.hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+  url.hash = '';
+  const pathname = normalizedPath(url);
+  return `${url.protocol}//${url.host}${pathname === '/' ? '' : pathname}`;
+}
+
+export function isCanonicalPublicSourceUrl(value) {
+  return canonicalizeSourceUrl(value) === value;
+}

package/src/structured-output-schema.js

@@ -0,0 +1,66 @@
+const PROVIDER_UNSUPPORTED_GENERATION_KEYWORDS = new Set(['uniqueItems']);
+const MAX_SCHEMA_DEPTH = 256;
+const MAX_SCHEMA_NODES = 100_000;
+
+function projectionError(message) {
+  return new TypeError(`Provider-facing structured output schema projection failed: ${message}`);
+}
+
+/**
+ * Provider structured-output implementations may support only a JSON Schema
+ * subset. Real conformance probes rejected uniqueItems, so generation omits it
+ * while the unchanged exact local schema remains the validation authority.
+ */
+export function projectStructuredOutputSchemaForProvider(schema) {
+  const active = new WeakSet();
+  let visitedNodes = 0;
+
+  function project(value, depth) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) throw projectionError('numbers must be finite JSON values.');
+      return value;
+    }
+    if (['undefined', 'bigint', 'function', 'symbol'].includes(typeof value)) {
+      throw projectionError('schema must contain only JSON values.');
+    }
+    if (depth > MAX_SCHEMA_DEPTH) throw projectionError('schema nesting is too deep.');
+    if (active.has(value)) throw projectionError('circular schema input is not supported.');
+    visitedNodes += 1;
+    if (visitedNodes > MAX_SCHEMA_NODES) throw projectionError('schema is too large.');
+
+    active.add(value);
+    try {
+      if (Array.isArray(value)) {
+        const output = [];
+        for (let index = 0; index < value.length; index += 1) {
+          if (!Object.hasOwn(value, index)) throw projectionError('sparse arrays are not JSON-safe.');
+          output.push(project(value[index], depth + 1));
+        }
+        return output;
+      }
+
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw projectionError('schema objects must be plain JSON objects.');
+      }
+      if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw projectionError('symbol properties are not JSON-safe.');
+      }
+      const entries = [];
+      for (const key of Object.keys(value)) {
+        if (PROVIDER_UNSUPPORTED_GENERATION_KEYWORDS.has(key)) continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+          throw projectionError('schema accessors are not supported.');
+        }
+        entries.push([key, project(descriptor.value, depth + 1)]);
+      }
+      return Object.fromEntries(entries);
+    } finally {
+      active.delete(value);
+    }
+  }
+
+  return project(schema, 0);
+}

package/src/target-selector.js

@@ -0,0 +1,306 @@
+import { createHash } from 'node:crypto';
+
+import { canonicalJsonBytes } from './canonical-json.js';
+import {
+  createDefaultEcosystemVersionAdapterRegistry,
+  getEcosystemVersionAdapter
+} from './ecosystem-version-adapter.js';
+import { compareText, isPortableRelativePath } from './portable.js';
+
+const REQUIRED_KEYS = Object.freeze(['package', 'target']);
+const OPTIONAL_KEYS = Object.freeze(['project', 'manifest', 'type', 'occurrence']);
+const ALLOWED_KEYS = new Set([...REQUIRED_KEYS, ...OPTIONAL_KEYS]);
+const OCCURRENCE_ID_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const OCCURRENCE_ID_VERSION = 'target-occurrence.v1';
+
+export class TargetSelectorError extends Error {
+  constructor(code, message, candidates = []) {
+    super(`${code}: ${message}`);
+    this.name = 'TargetSelectorError';
+    this.code = code;
+    this.candidates = Object.freeze([...candidates]);
+  }
+}
+
+function selectorError(code, message, candidates) {
+  throw new TargetSelectorError(code, message, candidates);
+}
+
+function requireText(value, field) {
+  if (typeof value !== 'string' || value.trim().length === 0 || /[\r\n\0]/.test(value)) {
+    selectorError('TARGET_SELECTOR_INVALID', `${field} must be a non-empty single-line value.`);
+  }
+  return value.trim();
+}
+
+function canonicalPackageId(value) {
+  const text = requireText(value, 'package');
+  const separator = text.indexOf(':');
+  if (separator <= 0 || separator === text.length - 1
+      || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(text.slice(0, separator))
+      || /\s/.test(text.slice(separator + 1))) {
+    selectorError(
+      'TARGET_SELECTOR_INVALID',
+      'package must be an exact canonical ID such as npm:react, npm:@scope/package, or pypi:langsmith.'
+    );
+  }
+  return text;
+}
+
+export function parseTargetSelector(value) {
+  const text = requireText(value, '--target');
+  const fields = {};
+  for (const segment of text.split(',')) {
+    const separator = segment.indexOf('=');
+    if (separator <= 0) {
+      selectorError(
+        'TARGET_SELECTOR_INVALID',
+        'each --target field must use key=value syntax.'
+      );
+    }
+    const key = segment.slice(0, separator).trim();
+    const fieldValue = requireText(segment.slice(separator + 1), key || '--target field');
+    if (!ALLOWED_KEYS.has(key)) {
+      selectorError('TARGET_SELECTOR_INVALID', `unsupported --target field ${key}.`);
+    }
+    if (Object.hasOwn(fields, key)) {
+      selectorError('TARGET_SELECTOR_INVALID', `duplicate --target field ${key}.`);
+    }
+    fields[key] = fieldValue;
+  }
+  for (const key of REQUIRED_KEYS) {
+    if (!Object.hasOwn(fields, key)) {
+      selectorError('TARGET_SELECTOR_INVALID', `--target requires ${key}=<value>.`);
+    }
+  }
+  const selector = {
+    packageId: canonicalPackageId(fields.package),
+    targetVersion: fields.target
+  };
+  if (fields.project) selector.projectId = fields.project;
+  if (fields.manifest) {
+    if (!isPortableRelativePath(fields.manifest)) {
+      selectorError('TARGET_SELECTOR_INVALID', 'manifest must be a portable repository-relative path.');
+    }
+    selector.manifest = fields.manifest;
+  }
+  if (fields.type) selector.dependencyType = fields.type;
+  if (fields.occurrence) {
+    if (!OCCURRENCE_ID_PATTERN.test(fields.occurrence)) {
+      selectorError(
+        'TARGET_SELECTOR_INVALID',
+        'occurrence must be a stable sha256:<64 lowercase hexadecimal characters> identifier.'
+      );
+    }
+    selector.occurrenceId = fields.occurrence;
+  }
+  return Object.freeze(selector);
+}
+
+function occurrenceIdentity(input) {
+  return {
+    schemaVersion: OCCURRENCE_ID_VERSION,
+    projectId: input.project.id,
+    packageId: input.packageRecord.id,
+    manifest: input.dependency.manifest,
+    dependencyType: input.dependency.type,
+    declaredName: input.dependency.name,
+    declaredVersion: input.dependency.declaredVersion ?? null
+  };
+}
+
+export function targetOccurrenceId(input) {
+  const digest = createHash('sha256')
+    .update(canonicalJsonBytes(occurrenceIdentity(input)))
+    .digest('hex');
+  return `sha256:${digest}`;
+}
+
+export function targetOccurrenceKey(input) {
+  return [
+    input.project.id,
+    input.packageRecord.id,
+    input.dependency.manifest,
+    input.dependency.type,
+    input.dependency.name,
+    input.dependency.declaredVersion ?? ''
+  ].join('\0');
+}
+
+function matches(input, selector) {
+  return input.packageRecord.id === selector.packageId
+    && (!selector.projectId || input.project.id === selector.projectId)
+    && (!selector.manifest || input.dependency.manifest === selector.manifest)
+    && (!selector.dependencyType || input.dependency.type === selector.dependencyType);
+}
+
+function exactSelector(input, targetVersion) {
+  return [
+    `package=${input.packageRecord.id}`,
+    `target=${targetVersion}`,
+    `project=${input.project.id}`,
+    `manifest=${input.dependency.manifest}`,
+    `type=${input.dependency.type}`,
+    `occurrence=${targetOccurrenceId(input)}`
+  ].join(',');
+}
+
+function safeDeclaredVersion(value) {
+  if (value === null || value === undefined || value === '') return '<unversioned>';
+  const text = String(value).trim();
+  if (
+    text.length === 0
+    || text.length > 240
+    || /[\u0000-\u001f\u007f]/.test(text)
+    || /(?:authorization|credential|password|secret|token)\s*=/i.test(text)
+  ) {
+    return '<redacted-declaration>';
+  }
+  if (/^(?:file:|link:|\.{1,2}[\\/]|[\\/]|~[\\/])/i.test(text)) {
+    return '<local-path-reference>';
+  }
+  const prefix = text.startsWith('git+') ? 'git+' : '';
+  const candidate = prefix ? text.slice(prefix.length) : text;
+  try {
+    const url = new URL(candidate);
+    if (!['http:', 'https:', 'ssh:', 'git:'].includes(url.protocol)) return text;
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    return `${prefix}${url.toString()}`;
+  } catch {
+    return text;
+  }
+}
+
+function exactCandidate(input, targetVersion) {
+  return {
+    selector: exactSelector(input, targetVersion),
+    projectId: input.project.id,
+    manifest: input.dependency.manifest,
+    dependencyType: input.dependency.type,
+    declaredName: safeDeclaredVersion(input.dependency.name),
+    declaredVersion: safeDeclaredVersion(input.dependency.declaredVersion)
+  };
+}
+
+function candidateMessage(candidate) {
+  return [
+    `  --target '${candidate.selector}'`,
+    `    project: ${candidate.projectId}`,
+    `    manifest: ${candidate.manifest}`,
+    `    type: ${candidate.dependencyType}`,
+    `    declared name: ${candidate.declaredName}`,
+    `    declared: ${candidate.declaredVersion}`
+  ].join('\n');
+}
+
+function occurrenceIndex(inputs) {
+  const indexed = new Map();
+  for (const input of inputs) {
+    const id = targetOccurrenceId(input);
+    if (!indexed.has(id)) indexed.set(id, []);
+    indexed.get(id).push(input);
+  }
+  for (const [id, matchesForId] of indexed) {
+    if (matchesForId.length > 1) {
+      selectorError(
+        'TARGET_SELECTOR_CONFLICT',
+        `dependency occurrence identity ${id} is duplicated; exact target selection is unsafe and no provider call was made.`
+      );
+    }
+  }
+  return indexed;
+}
+
+function matchesForSelector(inputs, selector, indexed) {
+  if (!selector.occurrenceId) return inputs.filter((input) => matches(input, selector));
+  const selected = indexed.get(selector.occurrenceId);
+  if (!selected) {
+    selectorError(
+      'TARGET_SELECTOR_NOT_FOUND',
+      `occurrence ${selector.occurrenceId} is stale or unknown; no provider call was made.`
+    );
+  }
+  const input = selected[0];
+  if (!matches(input, selector)) {
+    selectorError(
+      'TARGET_SELECTOR_CONFLICT',
+      `occurrence ${selector.occurrenceId} conflicts with the supplied package/project/manifest/type fields; no provider call was made.`
+    );
+  }
+  return selected;
+}
+
+function normalizeTarget(input, selector, adapterRegistry) {
+  let adapter;
+  try {
+    adapter = getEcosystemVersionAdapter(input.project.ecosystem, adapterRegistry);
+  } catch (error) {
+    selectorError(
+      'TARGET_VERSION_INVALID',
+      `target ${selector.targetVersion} cannot be validated for ecosystem ${input.project.ecosystem}: ${error.message}`
+    );
+  }
+  const normalized = adapter.normalizeVersion(selector.targetVersion);
+  if (!normalized.ok) {
+    selectorError(
+      'TARGET_VERSION_INVALID',
+      `target ${selector.targetVersion} is invalid for ${input.packageRecord.id}: ${normalized.reason}.`
+    );
+  }
+  return normalized.value;
+}
+
+export function resolveTargetSelectors(inputs, selectors, {
+  adapterRegistry = createDefaultEcosystemVersionAdapterRegistry()
+} = {}) {
+  const parsed = selectors.map((selector) => (
+    typeof selector === 'string' ? parseTargetSelector(selector) : selector
+  ));
+  const indexed = occurrenceIndex(inputs);
+  const selected = new Map();
+  for (const selector of parsed) {
+    const matchingInputs = matchesForSelector(inputs, selector, indexed);
+    if (matchingInputs.length === 0) {
+      selectorError(
+        'TARGET_SELECTOR_NOT_FOUND',
+        `no dependency occurrence matches ${selector.packageId}; no provider call was made.`
+      );
+    }
+    if (matchingInputs.length > 1) {
+      const exactCandidates = [...matchingInputs]
+        .sort((left, right) => compareText(targetOccurrenceKey(left), targetOccurrenceKey(right)))
+        .map((input) => exactCandidate(input, selector.targetVersion));
+      const candidates = exactCandidates.map((candidate) => candidate.selector);
+      selectorError(
+        'TARGET_SELECTOR_AMBIGUOUS',
+        `Target selector for ${selector.packageId} matches ${matchingInputs.length} dependency occurrences.\n`
+        + 'Choose one of the following exact selectors:\n'
+        + exactCandidates.map(candidateMessage).join('\n\n'),
+        candidates
+      );
+    }
+    const input = matchingInputs[0];
+    const key = targetOccurrenceKey(input);
+    const targetVersion = normalizeTarget(input, selector, adapterRegistry);
+    if (selected.has(key)) {
+      const prior = selected.get(key);
+      selectorError(
+        'TARGET_SELECTOR_CONFLICT',
+        `dependency occurrence ${input.project.id} / ${input.dependency.manifest} / `
+        + `${input.dependency.type} / ${input.packageRecord.id} was selected more than once `
+        + `(${prior.targetVersion}, ${targetVersion}).`
+      );
+    }
+    selected.set(key, Object.freeze({
+      targetVersion,
+      target: Object.freeze({ policy: 'explicit', version: targetVersion }),
+      selector: Object.freeze({ ...selector })
+    }));
+  }
+  return Object.freeze(new Map(
+    [...selected.entries()].sort(([left], [right]) => compareText(left, right))
+  ));
+}

package/src/upgrade-decision/input-loader.js

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { DEFAULT_UPGRADE_DECISION_PATH } from '../constants.js';
+import { isPortableRelativePath } from '../portable.js';
+import { buildUpgradeDecision, validateUpgradeDecision } from './upgrade-decision.js';
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function sourceFor(input, options) {
+  const explicit = options.upgradeDecision ?? input?.upgradeDecision ?? input?.sources?.upgradeDecision;
+  if (explicit !== undefined) return { source: explicit, required: true };
+  if (typeof input === 'string' || input === undefined || input === null) {
+    return {
+      source: path.resolve(input ?? '.', options.upgradeDecisionArtifact ?? DEFAULT_UPGRADE_DECISION_PATH),
+      required: false
+    };
+  }
+  if (input instanceof URL) {
+    return {
+      source: new URL(options.upgradeDecisionArtifact ?? DEFAULT_UPGRADE_DECISION_PATH, input),
+      required: false
+    };
+  }
+  if (typeof input.repositoryRoot === 'string') {
+    return {
+      source: path.resolve(
+        input.repositoryRoot,
+        options.upgradeDecisionArtifact ?? DEFAULT_UPGRADE_DECISION_PATH
+      ),
+      required: false
+    };
+  }
+  return { source: undefined, required: false };
+}
+
+function artifactFor(source, options) {
+  const explicit = source && typeof source === 'object' && !(source instanceof URL)
+    ? source.artifact
+    : undefined;
+  const artifact = explicit ?? options.upgradeDecisionArtifact ?? DEFAULT_UPGRADE_DECISION_PATH;
+  if (!isPortableRelativePath(artifact)) {
+    throw new Error('Upgrade Decision input error: artifact path must be repository-relative.');
+  }
+  return artifact;
+}
+
+async function readBytes(source) {
+  if (typeof source === 'string' || source instanceof URL) return readFile(source);
+  if (source?.bytes instanceof Uint8Array) return Buffer.from(source.bytes);
+  if (typeof source?.path === 'string' || source?.path instanceof URL) return readFile(source.path);
+  throw new Error('Upgrade Decision input error: unsupported artifact source.');
+}
+
+export async function loadPersistedUpgradeDecision(input, artifacts, options = {}) {
+  const selected = sourceFor(input, options);
+  if (selected.source === undefined) return artifacts;
+  let bytes;
+  try {
+    bytes = await readBytes(selected.source);
+  } catch (error) {
+    if (!selected.required && error?.code === 'ENOENT') return artifacts;
+    throw error;
+  }
+  let decision;
+  try {
+    decision = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new Error('Upgrade Decision input error: artifact is not valid JSON.');
+  }
+  validateUpgradeDecision(decision);
+  if (!sameJson(decision.input, artifacts.input)) {
+    throw new Error('Upgrade Decision input error: upstream artifact lineage mismatch.');
+  }
+  const resultIds = artifacts.versionAnalysis.results.map((result) => result.id).sort();
+  const decisionIds = decision.decisions
+    .map((record) => record.analysisResultId)
+    .filter((value) => value !== null)
+    .sort();
+  if (!sameJson(resultIds, decisionIds)) {
+    throw new Error('Upgrade Decision input error: dependency occurrence set mismatch.');
+  }
+  const expected = buildUpgradeDecision(artifacts);
+  if (!sameJson(decision, expected)) {
+    throw new Error('Upgrade Decision input error: artifact does not match deterministic policy output.');
+  }
+  const artifact = artifactFor(selected.source, options);
+  return {
+    ...artifacts,
+    upgradeDecision: decision,
+    input: {
+      ...artifacts.input,
+      upgradeDecision: {
+        schemaVersion: decision.schemaVersion,
+        artifact,
+        artifactDigest: digest(bytes)
+      }
+    }
+  };
+}

package/src/upgrade-decision/presentation.js

@@ -0,0 +1,43 @@
+function inlineCode(value) {
+  return `\`${String(value).replaceAll('`', '\\`')}\``;
+}
+
+export function renderUpgradeDecisionConsole({ artifact, artifactPath }) {
+  const lines = [
+    'Upgrade Decisions',
+    '',
+    `Keep current: ${artifact.summary.KEEP_CURRENT}`,
+    `Upgrade now: ${artifact.summary.UPGRADE_NOW}`,
+    `Plan upgrade: ${artifact.summary.PLAN_UPGRADE}`,
+    `Investigate: ${artifact.summary.INVESTIGATE}`,
+    `Insufficient evidence: ${artifact.summary.INSUFFICIENT_EVIDENCE}`,
+    `Not analyzed: ${artifact.summary.NOT_ANALYZED}`,
+    `Artifact: ${artifactPath}`,
+    ''
+  ];
+  for (const record of artifact.decisions) {
+    lines.push(
+      `${record.occurrence.declaredName}: ${record.decision} (${record.primaryReasonCode})`
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function renderUpgradeDecisionMarkdownSection(artifact) {
+  const lines = [
+    '## Upgrade Decisions',
+    '',
+    '| Dependency occurrence | Installed | Target | Decision | Reason |',
+    '| --- | --- | --- | --- | --- |'
+  ];
+  for (const record of artifact.decisions) {
+    const occurrence = `${record.occurrence.declaredName} — ${record.occurrence.manifest} (${record.occurrence.dependencyType})`;
+    lines.push(
+      `| ${inlineCode(occurrence)} | ${inlineCode(record.versions.installedVersion ?? 'unavailable')} | `
+      + `${inlineCode(record.versions.targetVersion ?? 'unavailable')} | ${inlineCode(record.decision)} | `
+      + `${inlineCode(record.primaryReasonCode)} |`
+    );
+  }
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}

package/src/upgrade-decision/runtime.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+
+import { DEFAULT_UPGRADE_DECISION_PATH } from '../constants.js';
+import { loadMigrationChecklistInputs } from '../migration-checklist/input-loader.js';
+import { buildUpgradeDecision } from './upgrade-decision.js';
+import { writeUpgradeDecision } from './writer.js';
+
+export async function runUpgradeDecisionStage({
+  repositoryRoot,
+  artifactPath = DEFAULT_UPGRADE_DECISION_PATH,
+  adapters,
+  onCompatibilityDiagnostic,
+  writeArtifact = writeUpgradeDecision
+}) {
+  const artifacts = await loadMigrationChecklistInputs(repositoryRoot, {
+    onCompatibilityDiagnostic
+  });
+  const decision = buildUpgradeDecision(artifacts, { adapters });
+  await writeArtifact(path.resolve(repositoryRoot, artifactPath), decision);
+  return decision;
+}