@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/conformance-report.js

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { canonicalJsonBytes } from './canonical-json.js';
+import { ARTIFACT_GENERATOR_NAME, VERSION } from './constants.js';
+import { compareText } from './portable.js';
+import { RUNTIME_CONFORMANCE_CAPABILITIES } from './runtime-conformance.js';
+
+export const CONFORMANCE_REPORT_SCHEMA_VERSION = '1.0.0';
+
+const schema = JSON.parse(await readFile(
+  new URL('../schemas/conformance-report.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+function capabilitySummary(caseResults) {
+  return Object.fromEntries(RUNTIME_CONFORMANCE_CAPABILITIES.map((capability) => {
+    const relevant = caseResults.filter((result) => result.capabilities.includes(capability));
+    if (relevant.some((result) => result.status === 'FAIL')) return [capability, 'FAIL'];
+    if (relevant.length > 0 && relevant.every((result) => result.capabilityStatus === 'NOT_SUPPORTED')) {
+      return [capability, 'NOT_SUPPORTED'];
+    }
+    return [capability, 'PASS'];
+  }));
+}
+
+function recommendationFor(caseResults) {
+  if (caseResults.some((result) => result.required && result.status === 'FAIL')) return 'NON_CONFORMANT';
+  if (caseResults.some((result) => result.status === 'FAIL' || result.status === 'SKIP')) {
+    return 'PARTIALLY_CONFORMANT';
+  }
+  return 'CONFORMANT';
+}
+
+export function buildConformanceReport({
+  runtime,
+  caseResults,
+  deploymentProfileDigest,
+  capabilityProfileDigest,
+  conformanceScope = 'offline-runtime-protocol',
+  generatedAt = new Date()
+}) {
+  const sortedResults = [...caseResults].sort((left, right) => compareText(left.id, right.id));
+  const cases = sortedResults.map((result) => ({
+    id: result.id,
+    capability: result.capability,
+    required: result.required,
+    status: result.status,
+    expected: result.expected,
+    observed: result.observed
+  }));
+  const failedResults = sortedResults.filter((result) => result.status === 'FAIL');
+  const report = {
+    schemaVersion: CONFORMANCE_REPORT_SCHEMA_VERSION,
+    generatedAt: generatedAt instanceof Date ? generatedAt.toISOString() : generatedAt,
+    generator: { name: ARTIFACT_GENERATOR_NAME, version: VERSION },
+    suite: {
+      mode: 'offlineFixture',
+      protocol: 'openai-compatible-chat-completions',
+      scope: conformanceScope,
+      caseCount: cases.length
+    },
+    runtime: {
+      provider: runtime.provider,
+      model: runtime.model
+    },
+    deploymentProfileDigest,
+    capabilityProfileDigest,
+    conformanceScope,
+    summary: {
+      total: cases.length,
+      passed: cases.filter((result) => result.status === 'PASS').length,
+      failed: failedResults.length,
+      skipped: cases.filter((result) => result.status === 'SKIP').length
+    },
+    capabilities: capabilitySummary(sortedResults),
+    cases,
+    failures: failedResults.map((result) => ({
+      caseId: result.id,
+      code: result.observed,
+      message: 'Observed runtime behavior did not match the conformance contract.'
+    })),
+    recommendation: recommendationFor(sortedResults)
+  };
+  return validateConformanceReport(report);
+}
+
+export function validateConformanceReport(report) {
+  if (report?.schemaVersion !== CONFORMANCE_REPORT_SCHEMA_VERSION) {
+    throw new Error(`Conformance Report validation error: unsupported schema version; expected ${CONFORMANCE_REPORT_SCHEMA_VERSION}.`);
+  }
+  if (!validateSchema(report)) {
+    throw new Error(`Conformance Report validation error: schema validation failed: ${ajv.errorsText(validateSchema.errors, { separator: '; ' })}`);
+  }
+  if (report.suite.caseCount !== report.cases.length || report.summary.total !== report.cases.length) {
+    throw new Error('Conformance Report validation error: case totals do not match the case list.');
+  }
+  if (report.suite.scope !== report.conformanceScope) {
+    throw new Error('Conformance Report validation error: suite scope does not match conformanceScope.');
+  }
+  const counted = report.summary.passed + report.summary.failed + report.summary.skipped;
+  if (counted !== report.summary.total) {
+    throw new Error('Conformance Report validation error: summary counts do not add up to the total.');
+  }
+  const caseIds = new Set();
+  for (const result of report.cases) {
+    if (caseIds.has(result.id)) throw new Error(`Conformance Report validation error: duplicate case ${result.id}.`);
+    caseIds.add(result.id);
+  }
+  for (const failure of report.failures) {
+    const result = report.cases.find((entry) => entry.id === failure.caseId);
+    if (!result || result.status !== 'FAIL') {
+      throw new Error(`Conformance Report validation error: failure references non-failed case ${failure.caseId}.`);
+    }
+  }
+  if (report.failures.length !== report.summary.failed) {
+    throw new Error('Conformance Report validation error: failure count does not match the summary.');
+  }
+  return report;
+}
+
+export function serializeConformanceReport(report) {
+  validateConformanceReport(report);
+  return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+export function conformanceReportDigest(report) {
+  validateConformanceReport(report);
+  return `sha256:${createHash('sha256').update(canonicalJsonBytes(report)).digest('hex')}`;
+}
+
+export async function writeConformanceReport(outputPath, report) {
+  const target = path.resolve(outputPath);
+  const temporary = `${target}.${process.pid}.tmp`;
+  const contents = serializeConformanceReport(report);
+  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/conformance-runner.js

@@ -0,0 +1,253 @@
+import { buildConformanceReport } from './conformance-report.js';
+import { createOpenAiCompatibleProvider } from './openai-compatible-provider.js';
+import {
+  OFFLINE_CONFORMANCE_ENDPOINT,
+  capabilityProfileDigest as digestCapabilityProfile,
+  createDefaultGovernanceArtifacts,
+  deploymentProfileDigest as digestDeploymentProfile
+} from './governance-metadata.js';
+import {
+  RUNTIME_CONFORMANCE_CASES,
+  RUNTIME_CONFORMANCE_OUTPUT_SCHEMA,
+  RuntimeConformanceValidationError,
+  normalizeConformanceError,
+  validateRuntimeConformanceOutput
+} from './runtime-conformance.js';
+
+const FIXTURE_ENDPOINT = OFFLINE_CONFORMANCE_ENDPOINT;
+const FIXTURE_USAGE = Object.freeze({
+  prompt_tokens: 17,
+  completion_tokens: 9,
+  total_tokens: 26
+});
+
+function fixtureSuccessBody(model, transport) {
+  const content = transport.content
+    ?? JSON.stringify({ status: 'ok', protocol: 'chat-completions' });
+  const choice = {
+    index: 0,
+    message: { role: 'assistant', content },
+    finish_reason: 'stop'
+  };
+  const body = {
+    id: 'offline-conformance-response',
+    model: transport.returnedModel ?? model,
+    usage: { ...FIXTURE_USAGE }
+  };
+  if (!transport.omitChoices) {
+    body.choices = transport.choiceCount === 2
+      ? [choice, { ...choice, index: 1 }]
+      : [choice];
+  }
+  return body;
+}
+
+function jsonResponse(body, { status = 200, contentType = 'application/json' } = {}) {
+  return new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+    status,
+    headers: { 'content-type': contentType }
+  });
+}
+
+function waitForAbort(signal) {
+  return new Promise((resolve, reject) => {
+    const rejectAbort = () => reject(new DOMException('Fixture request aborted.', 'AbortError'));
+    if (signal.aborted) rejectAbort();
+    else signal.addEventListener('abort', rejectAbort, { once: true });
+  });
+}
+
+function createFixtureFetch(caseDefinition, runtime, observations) {
+  return async (_url, init) => {
+    observations.authorization = init.headers.authorization ?? null;
+    observations.redirect = init.redirect;
+    observations.requestBody = JSON.parse(init.body);
+    const transport = caseDefinition.transport;
+    if (transport.type === 'networkError') throw new TypeError('Offline fixture network failure.');
+    if (transport.type === 'waitForAbort') return waitForAbort(init.signal);
+    if (transport.type === 'redirect') throw new TypeError('Offline fixture redirect rejected.');
+    if (transport.type === 'malformedJson') return jsonResponse('{malformed');
+    if (transport.type === 'oversized') {
+      return new Response('x'.repeat(512), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+          'content-length': '512'
+        }
+      });
+    }
+    if (transport.type === 'httpError') {
+      return jsonResponse({
+        error: {
+          message: transport.descriptor ?? `offline fixture HTTP ${transport.status}`
+        }
+      }, { status: transport.status });
+    }
+    return jsonResponse(fixtureSuccessBody(runtime.model, transport), {
+      contentType: transport.contentType
+    });
+  };
+}
+
+function runtimeRequest(caseDefinition, signal) {
+  return {
+    contractVersion: '1.0.0',
+    runId: `conformance:${caseDefinition.id}`,
+    contextId: 'offline-runtime-conformance',
+    task: 'runtime-conformance.v1',
+    promptVersion: '1.0.0',
+    systemPrompt: 'Return the fixed runtime conformance object.',
+    userPrompt: 'Return status ok and protocol chat-completions.',
+    structuredOutput: {
+      mode: caseDefinition.mode,
+      name: 'upgradelens_runtime_conformance',
+      schema: RUNTIME_CONFORMANCE_OUTPUT_SCHEMA
+    },
+    ...(signal ? { signal } : {})
+  };
+}
+
+function assertionError(code, message) {
+  throw new RuntimeConformanceValidationError(code, message);
+}
+
+function validateAssertions(caseDefinition, result, observations, runtime) {
+  for (const assertion of caseDefinition.assertions) {
+    if (assertion === 'outputSchema') validateRuntimeConformanceOutput(result.output);
+    else if (assertion === 'noAuthorization' && observations.authorization !== null) {
+      assertionError('AUTH_MAPPING_INVALID', 'No-auth request unexpectedly sent authorization.');
+    } else if (assertion === 'bearerAuthorization'
+      && observations.authorization !== caseDefinition.authorization) {
+      assertionError('AUTH_MAPPING_INVALID', 'Bearer authorization was not forwarded exactly.');
+    } else if (assertion === 'structuredRequest') {
+      const format = observations.requestBody?.response_format;
+      if (format?.type !== 'json_schema'
+        || format.json_schema?.strict !== true
+        || JSON.stringify(format.json_schema.schema) !== JSON.stringify(RUNTIME_CONFORMANCE_OUTPUT_SCHEMA)
+        || observations.requestBody.stream !== false) {
+        assertionError('REQUEST_MAPPING_INVALID', 'JSON Schema request mapping is not exact.');
+      }
+    } else if (assertion === 'usage') {
+      if (result.usage.inputTokens !== FIXTURE_USAGE.prompt_tokens
+        || result.usage.outputTokens !== FIXTURE_USAGE.completion_tokens
+        || result.usage.totalTokens !== FIXTURE_USAGE.total_tokens) {
+        assertionError('USAGE_MAPPING_INVALID', 'Token usage was not mapped exactly.');
+      }
+    } else if (assertion === 'identity') {
+      if (result.requestedModel !== runtime.model
+        || result.model !== runtime.model
+        || result.actualModel !== runtime.model) {
+        assertionError('IDENTITY_MAPPING_INVALID', 'Configured and returned model identities do not match.');
+      }
+    } else if (assertion === 'redirectErrorMode' && observations.redirect !== 'error') {
+      assertionError('REDIRECT_PROTECTION_INVALID', 'Fetch redirect mode was not set to error.');
+    }
+  }
+}
+
+export function createOfflineConformanceExecutor({
+  providerFactory = createOpenAiCompatibleProvider
+} = {}) {
+  return async function executeConformanceCase(caseDefinition, runtime) {
+    if (caseDefinition.transport.type === 'unknownError') {
+      try {
+        throw new Error('Offline fixture unknown error.');
+      } catch (error) {
+        return { outcome: normalizeConformanceError(error) };
+      }
+    }
+
+    const observations = {};
+    const provider = providerFactory({
+      endpoint: FIXTURE_ENDPOINT,
+      model: runtime.model,
+      provider: runtime.provider,
+      authorization: caseDefinition.authorization,
+      fetchImplementation: createFixtureFetch(caseDefinition, runtime, observations),
+      timeoutMs: caseDefinition.id === 'timeout-classification' ? 10 : 1_000,
+      maxResponseBytes: caseDefinition.transport.type === 'oversized' ? 64 : 2_048,
+      requireExactModelIdentity: caseDefinition.requireExactModelIdentity
+    });
+    const callerController = caseDefinition.assertions.includes('callerAbort')
+      ? new AbortController()
+      : null;
+
+    try {
+      const pending = provider.generateStructured(runtimeRequest(caseDefinition, callerController?.signal));
+      if (callerController) callerController.abort();
+      const result = await pending;
+      validateAssertions(caseDefinition, result, observations, runtime);
+      return { outcome: 'SUCCESS' };
+    } catch (error) {
+      try {
+        if (caseDefinition.assertions.includes('redirectErrorMode') && observations.redirect !== 'error') {
+          assertionError('REDIRECT_PROTECTION_INVALID', 'Fetch redirect mode was not set to error.');
+        }
+      } catch (assertionFailure) {
+        return { outcome: normalizeConformanceError(assertionFailure) };
+      }
+      return { outcome: normalizeConformanceError(error) };
+    }
+  };
+}
+
+function validateRuntimeProfile(runtime) {
+  if (!runtime || typeof runtime !== 'object' || Array.isArray(runtime)) {
+    throw new TypeError('Conformance runtime profile must be an object.');
+  }
+  if (typeof runtime.provider !== 'string' || runtime.provider.trim().length === 0) {
+    throw new TypeError('Conformance runtime provider is required.');
+  }
+  if (typeof runtime.model !== 'string' || runtime.model.trim().length === 0) {
+    throw new TypeError('Conformance runtime model is required.');
+  }
+  return { provider: runtime.provider, model: runtime.model };
+}
+
+export async function runConformance({
+  runtime = { provider: 'openai-compatible', model: 'offline-fixture' },
+  cases = RUNTIME_CONFORMANCE_CASES,
+  capabilityProfileDigest,
+  deploymentProfileDigest,
+  conformanceScope = 'offline-runtime-protocol',
+  generatedAt = new Date()
+} = {}, {
+  executeCase = createOfflineConformanceExecutor()
+} = {}) {
+  const profile = validateRuntimeProfile(runtime);
+  const governance = createDefaultGovernanceArtifacts({
+    provider: profile.provider,
+    endpoint: FIXTURE_ENDPOINT,
+    model: profile.model
+  });
+  const caseResults = [];
+  for (const caseDefinition of cases) {
+    let observed;
+    try {
+      const result = await executeCase(caseDefinition, profile);
+      observed = typeof result?.outcome === 'string' ? result.outcome : 'UNKNOWN';
+    } catch (error) {
+      observed = normalizeConformanceError(error);
+    }
+    caseResults.push({
+      id: caseDefinition.id,
+      capability: caseDefinition.capability,
+      capabilities: caseDefinition.capabilities,
+      required: caseDefinition.required,
+      capabilityStatus: caseDefinition.capabilityStatusByOutcome[observed] ?? 'PASS',
+      status: caseDefinition.accepted.includes(observed) ? 'PASS' : 'FAIL',
+      expected: caseDefinition.expected,
+      observed
+    });
+  }
+  return buildConformanceReport({
+    runtime: profile,
+    caseResults,
+    deploymentProfileDigest: deploymentProfileDigest
+      ?? digestDeploymentProfile(governance.deploymentProfile),
+    capabilityProfileDigest: capabilityProfileDigest
+      ?? digestCapabilityProfile(governance.capabilityProfile),
+    conformanceScope,
+    generatedAt
+  });
+}

package/src/constants.js

@@ -0,0 +1,73 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const packageMetadata = require('../package.json');
+
+export const PRODUCT_NAME = 'DepVerdict';
+export const PACKAGE_NAME = '@thomasminh1995/depverdict';
+export const CLI_NAME = 'depverdict';
+export const ARTIFACT_GENERATOR_NAME = 'UpgradeLens';
+export const VERSION = packageMetadata.version;
+export const USER_AGENT = `${PRODUCT_NAME}/${VERSION}`;
+export const MANIFEST_SCHEMA_VERSION = '2.0.0';
+export const DEFAULT_OUTPUT_DIRECTORY = '.depverdict';
+export const DEFAULT_MANIFEST_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/project-manifest.json`;
+export const KNOWLEDGE_MANIFEST_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_KNOWLEDGE_MANIFEST_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/knowledge-manifest.json`;
+export const VERSION_ANALYSIS_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_VERSION_ANALYSIS_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/version-analysis.json`;
+export const USAGE_INDEX_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_USAGE_INDEX_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/usage-index.json`;
+export const REPOSITORY_IMPACT_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_REPOSITORY_IMPACT_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/repository-impact.json`;
+export const REPOSITORY_IMPACT_EVIDENCE_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_REPOSITORY_IMPACT_EVIDENCE_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/repository-impact-evidence.json`;
+export const UPGRADE_DECISION_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_UPGRADE_DECISION_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/upgrade-decision.json`;
+export const MIGRATION_CHECKLIST_SCHEMA_VERSION = '2.0.0';
+export const DEFAULT_MIGRATION_CHECKLIST_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/migration-checklist.json`;
+export const DEFAULT_MIGRATION_PLANNING_QUALIFICATION_PATH =
+  `${DEFAULT_OUTPUT_DIRECTORY}/migration-planning-qualification.json`;
+export const DEFAULT_REPOSITORY_IMPACT_REPORT_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/repository-impact.md`;
+export const DEFAULT_ANALYSIS_LOG_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/logs/analyze.log`;
+export const DEFAULT_EVALUATION_REPORT_PATH = 'evaluation-report.json';
+export const DEFAULT_METRICS_PATH = 'metrics.json';
+export const DEFAULT_AI_SCORECARD_PATH = 'ai-scorecard.json';
+export const DEFAULT_BENCHMARK_CONFIG_PATH = 'benchmark.json';
+export const DEFAULT_BENCHMARK_REPORT_PATH = 'benchmark-report.json';
+export const DEFAULT_CONFORMANCE_REPORT_PATH = `${DEFAULT_OUTPUT_DIRECTORY}/conformance-report.json`;
+export const DEFAULT_GOVERNANCE_DIRECTORY = DEFAULT_OUTPUT_DIRECTORY;
+export const CAPABILITY_PROFILE_FILENAME = 'capability-profile.json';
+export const DEPLOYMENT_PROFILE_FILENAME = 'deployment-profile.json';
+export const QUALIFICATION_RECORD_FILENAME = 'qualification-record.json';
+export const DEFAULT_CAPABILITY_PROFILE_PATH = `${DEFAULT_GOVERNANCE_DIRECTORY}/${CAPABILITY_PROFILE_FILENAME}`;
+export const DEFAULT_DEPLOYMENT_PROFILE_PATH = `${DEFAULT_GOVERNANCE_DIRECTORY}/${DEPLOYMENT_PROFILE_FILENAME}`;
+export const DEFAULT_QUALIFICATION_RECORD_PATH = `${DEFAULT_GOVERNANCE_DIRECTORY}/${QUALIFICATION_RECORD_FILENAME}`;
+
+export const DEFAULT_IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.cache',
+  '.depverdict',
+  '.gradle',
+  '.hg',
+  '.idea',
+  '.mypy_cache',
+  '.next',
+  '.nuxt',
+  '.pytest_cache',
+  '.svn',
+  '.tox',
+  '.turbo',
+  '.upgradelens',
+  '.venv',
+  '.yarn',
+  '__pycache__',
+  'bower_components',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+  'target',
+  'vendor'
+]);

package/src/cooperative-scheduler.js

@@ -0,0 +1,79 @@
+import { performance } from 'node:perf_hooks';
+
+export const DEFAULT_COOPERATIVE_BATCH_SIZE = 64;
+export const DEFAULT_COOPERATIVE_MAX_INTERVAL_MS = 50;
+
+function yieldToEventLoop() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+function cancellationError(signal) {
+  const error = new Error('Repository scan was cancelled.', { cause: signal?.reason });
+  error.name = 'AbortError';
+  error.code = 'ANALYSIS_CANCELLED';
+  return error;
+}
+
+function requireMonotonicTime(clock) {
+  const value = clock();
+  if (!Number.isFinite(value)) {
+    throw new TypeError('Cooperative scheduler monotonic clock must return a finite number.');
+  }
+  return value;
+}
+
+/**
+ * Creates operation-local cooperative scheduling state for sequential scanners.
+ * A boundary represents one fully completed unit; it never exposes partial work.
+ */
+export function createCooperativeScheduler({
+  signal,
+  enabled = true,
+  batchSize = DEFAULT_COOPERATIVE_BATCH_SIZE,
+  maxIntervalMs = DEFAULT_COOPERATIVE_MAX_INTERVAL_MS,
+  monotonicClock = () => performance.now(),
+  yieldImplementation = yieldToEventLoop
+} = {}) {
+  if (typeof enabled !== 'boolean') throw new TypeError('Cooperative scheduler enabled must be boolean.');
+  if (!Number.isSafeInteger(batchSize) || batchSize <= 0) {
+    throw new TypeError('Cooperative scheduler batchSize must be a positive integer.');
+  }
+  if (!Number.isFinite(maxIntervalMs) || maxIntervalMs <= 0) {
+    throw new TypeError('Cooperative scheduler maxIntervalMs must be positive.');
+  }
+  if (typeof monotonicClock !== 'function' || typeof yieldImplementation !== 'function') {
+    throw new TypeError('Cooperative scheduler requires clock and yield functions.');
+  }
+
+  let completedUnits = 0;
+  let unitsSinceYield = 0;
+  let yieldCount = 0;
+  let lastYieldAt = requireMonotonicTime(monotonicClock);
+
+  function throwIfAborted() {
+    if (signal?.aborted) throw cancellationError(signal);
+  }
+
+  return Object.freeze({
+    checkpoint: throwIfAborted,
+    async boundary() {
+      throwIfAborted();
+      completedUnits += 1;
+      unitsSinceYield += 1;
+      if (!enabled) return false;
+
+      const now = requireMonotonicTime(monotonicClock);
+      if (unitsSinceYield < batchSize && now - lastYieldAt < maxIntervalMs) return false;
+
+      await yieldImplementation();
+      yieldCount += 1;
+      unitsSinceYield = 0;
+      lastYieldAt = requireMonotonicTime(monotonicClock);
+      throwIfAborted();
+      return true;
+    },
+    snapshot() {
+      return Object.freeze({ completedUnits, yieldCount, unitsSinceYield });
+    }
+  });
+}

package/src/dependencies.js

@@ -0,0 +1,44 @@
+function compare(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function sortDependencies(dependencies) {
+  return [...dependencies].sort((left, right) =>
+    compare(left.normalizedName, right.normalizedName)
+    || compare(left.type, right.type)
+    || compare(left.name, right.name)
+    || compare(left.declaredVersion ?? '', right.declaredVersion ?? '')
+    || compare(left.manifest ?? '', right.manifest ?? '')
+  );
+}
+
+export function summarizeDependencies(dependencies, byType) {
+  const declarationCount = dependencies.length;
+  const uniqueCount = new Set(dependencies.map((dependency) => dependency.normalizedName)).size;
+  return {
+    status: 'parsed',
+    declarationCount,
+    uniqueCount,
+    duplicateCount: declarationCount - uniqueCount,
+    ...(byType ? { byType } : {})
+  };
+}
+
+export function duplicateDependencyNames(dependencies) {
+  const counts = new Map();
+  for (const dependency of dependencies) {
+    counts.set(dependency.normalizedName, (counts.get(dependency.normalizedName) ?? 0) + 1);
+  }
+  return [...counts]
+    .filter(([, count]) => count > 1)
+    .map(([name]) => name)
+    .sort();
+}
+
+export function duplicateDependencyWarnings(dependencies, manifest) {
+  return duplicateDependencyNames(dependencies).map((name) => ({
+    code: 'DUPLICATE_DEPENDENCY_DECLARATION',
+    path: manifest,
+    message: `Dependency ${name} is declared multiple times.`
+  }));
+}