dependencyiq 2.0.0

package/src/freshnessChecker.js

@@ -0,0 +1,306 @@
+/**
+ * Dependency freshness checker.
+ *
+ * Queries each ecosystem's own registry for the latest stable version and
+ * its publish date — real registry data, not a guessed "latest is always
+ * best" heuristic. Used for two things:
+ *  1. Freshness score: how far behind latest stable is the current pin.
+ *  2. Stability-aware recommendation: prefer a release that's been out
+ *     for a while over one published days ago, since a brand-new release
+ *     hasn't had time to surface regressions.
+ */
+
+const axios = require('axios');
+const { withRetry } = require('./httpRetry');
+
+const STABILITY_WINDOW_DAYS = 14; // a release this old with no immediate yank is "settled"
+
+async function npmLatest(packageName) {
+  const { data } = await withRetry(() => axios.get(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, { timeout: 8000 }));
+  const latestTag = data['dist-tags']?.latest;
+  if (!latestTag) return null;
+  return {
+    latestVersion: latestTag,
+    publishedAt: data.time?.[latestTag] || null,
+    allVersions: Object.keys(data.versions || {}),
+    versionTimes: data.time || {},
+  };
+}
+
+async function pypiLatest(packageName) {
+  const { data } = await withRetry(() => axios.get(`https://pypi.org/pypi/${encodeURIComponent(packageName)}/json`, { timeout: 8000 }));
+  const latestVersion = data.info?.version;
+  if (!latestVersion) return null;
+  const releases = data.releases || {};
+  return {
+    latestVersion,
+    publishedAt: releases[latestVersion]?.[0]?.upload_time_iso_8601 || null,
+    allVersions: Object.keys(releases),
+    versionTimes: Object.fromEntries(
+      Object.entries(releases).map(([v, files]) => [v, files?.[0]?.upload_time_iso_8601])
+    ),
+  };
+}
+
+async function goProxyLatest(packageName) {
+  const { data } = await withRetry(() => axios.get(`https://proxy.golang.org/${encodeURIComponent(packageName.toLowerCase())}/@latest`, { timeout: 8000 }));
+  if (!data?.Version) return null;
+  return {
+    latestVersion: data.Version,
+    publishedAt: data.Time || null,
+    allVersions: null, // Go proxy doesn't give a full version list in one call
+    versionTimes: {},
+  };
+}
+
+async function mavenLatest(packageName) {
+  // packageName is "groupId:artifactId"
+  const [groupId, artifactId] = packageName.includes(':') ? packageName.split(':') : [null, packageName];
+  if (!groupId) return null;
+  const { data } = await withRetry(() => axios.get('https://search.maven.org/solrsearch/select', {
+    params: { q: `g:${groupId}+AND+a:${artifactId}`, core: 'gav', rows: 1, sort: 'timestamp desc', wt: 'json' },
+    timeout: 8000,
+  }));
+  const doc = data?.response?.docs?.[0];
+  if (!doc) return null;
+  return {
+    latestVersion: doc.v,
+    publishedAt: doc.timestamp ? new Date(doc.timestamp).toISOString() : null,
+    allVersions: null,
+    versionTimes: {},
+  };
+}
+
+const REGISTRY_LOOKUPS = {
+  npm: npmLatest,
+  PyPI: pypiLatest,
+  Go: goProxyLatest,
+  Maven: mavenLatest,
+};
+
+function parseSemverLoose(version) {
+  const match = String(version).replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: +match[1], minor: +match[2], patch: +match[3] };
+}
+
+function semverDistance(current, latest) {
+  const c = parseSemverLoose(current);
+  const l = parseSemverLoose(latest);
+  if (!c || !l) return { majors: null, minors: null, comparable: false };
+  return {
+    majors: l.major - c.major,
+    minors: l.major === c.major ? l.minor - c.minor : null,
+    comparable: true,
+  };
+}
+
+/**
+ * Compare two semver strings: -1 if a<b, 0 if equal, 1 if a>b, null if
+ * either isn't parseable.
+ */
+function compareSemver(a, b) {
+  const pa = parseSemverLoose(a);
+  const pb = parseSemverLoose(b);
+  if (!pa || !pb) return null;
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Choose which version to actually upgrade to for a security fix — the
+ * real "which version will work" decision that OSV alone can't make.
+ *
+ * OSV reports the *minimum* version that patches the CVE (the security
+ * floor). Blindly taking it is a mistake: it might be a brand-new
+ * release (regression risk), or it might force an unnecessary major
+ * bump. This picks the LEAST-DISRUPTIVE version that is still secure:
+ *
+ *   1. must be >= the OSV fixed version (non-negotiable — below it is
+ *      still vulnerable)
+ *   2. prefer staying within the current MAJOR (avoid breaking changes)
+ *   3. within that, prefer the LOWEST such version (smallest change)
+ *      that has been out >= the settling window (regression-tested by
+ *      the ecosystem, not published hours ago)
+ *   4. only cross a major if the fix simply isn't available in the
+ *      current major — and flag it loudly when that happens
+ *
+ * Registry-history-dependent, so npm/PyPI only. Go/Maven (single-latest
+ * lookups) return { available: false } and the caller falls back to the
+ * OSV floor — flagged honestly, never guessed.
+ *
+ * @returns {Promise<Object>} {
+ *   available, recommendedVersion, osvFloor, crossesMajor, settled,
+ *   ageDays, rationale, reason? }
+ */
+async function chooseSecureTargetVersion(ecosystem, packageName, currentVersion, osvFixedVersion, stabilityWindowDays = STABILITY_WINDOW_DAYS) {
+  const fallback = (reason) => ({ available: false, reason, recommendedVersion: osvFixedVersion, osvFloor: osvFixedVersion });
+
+  const lookup = REGISTRY_LOOKUPS[ecosystem];
+  if (!lookup) return fallback(`No registry lookup for "${ecosystem}" — using OSV fixed version`);
+  if (!parseSemverLoose(osvFixedVersion)) return fallback(`OSV fixed version "${osvFixedVersion}" is not semver — using it as-is`);
+
+  let info;
+  try {
+    info = await lookup(packageName);
+  } catch (error) {
+    return fallback(`Registry lookup failed: ${error.message} — using OSV fixed version`);
+  }
+  if (!info?.allVersions) return fallback(`No full version history for "${ecosystem}" — using OSV fixed version`);
+
+  const cur = parseSemverLoose(currentVersion);
+  const ascending = (a, b) => compareSemver(a.version, b.version);
+
+  // Real releases at or above the security floor; skip pre-releases/builds.
+  const candidates = info.allVersions
+    .filter(v => !/[-+]/.test(v))
+    .map(v => ({ version: v, parsed: parseSemverLoose(v), publishedAt: info.versionTimes?.[v] }))
+    .filter(c => c.parsed && compareSemver(c.version, osvFixedVersion) >= 0)
+    .map(c => ({ ...c, ageDays: c.publishedAt ? Math.floor((Date.now() - new Date(c.publishedAt).getTime()) / 86400000) : null }));
+
+  if (candidates.length === 0) return fallback('No registry version at or above the OSV fixed version — using OSV fixed version');
+
+  const isSettled = c => c.ageDays !== null && c.ageDays >= stabilityWindowDays;
+  const sameMajor = cur ? candidates.filter(c => c.parsed.major === cur.major) : [];
+
+  const settledSameMajor = sameMajor.filter(isSettled).sort(ascending);
+  const anySameMajor = [...sameMajor].sort(ascending);
+  const settledAny = candidates.filter(isSettled).sort(ascending);
+  const anyAll = [...candidates].sort(ascending);
+
+  let chosen;
+  let settled;
+  if (settledSameMajor.length) {
+    [chosen] = settledSameMajor; settled = true;
+  } else if (anySameMajor.length) {
+    [chosen] = anySameMajor; settled = false;
+  } else if (settledAny.length) {
+    [chosen] = settledAny; settled = true;
+  } else {
+    [chosen] = anyAll; settled = false;
+  }
+
+  const crossesMajor = cur ? chosen.parsed.major > cur.major : false;
+
+  let rationale;
+  if (compareSemver(chosen.version, osvFixedVersion) === 0) {
+    rationale = `${chosen.version} is the OSV-reported fixed version${settled ? ` and has been out ${chosen.ageDays}d (settled)` : ' (note: recently published)'}.`;
+  } else if (crossesMajor) {
+    rationale = `The fix is not available within the current major (${cur ? cur.major : '?'}.x); ${chosen.version} is the lowest secure version and crosses a MAJOR boundary — review for breaking changes.`;
+  } else {
+    rationale = `${chosen.version} is the lowest version ≥ the OSV floor (${osvFixedVersion}) that stays within the current major${settled ? ` and has been out ${chosen.ageDays}d (settled)` : ' (note: recently published — no settled option within this major)'}.`;
+  }
+
+  return {
+    available: true,
+    recommendedVersion: chosen.version,
+    osvFloor: osvFixedVersion,
+    crossesMajor,
+    settled,
+    ageDays: chosen.ageDays,
+    rationale,
+  };
+}
+
+/**
+ * Recommend the most recent version that's been out at least
+ * `stabilityWindowDays`, instead of the literal newest — a release
+ * published a few hours ago hasn't had time to surface regressions.
+ * Only possible for ecosystems whose registry returns a full version
+ * history in one call (npm, PyPI) — Go/Maven lookups here only return a
+ * single latest version, so this returns `null` for those rather than
+ * guessing from incomplete data.
+ * @param {Object} info - result of a REGISTRY_LOOKUPS[...] call
+ * @param {number} stabilityWindowDays
+ * @returns {Object|null} { recommendedVersion, isLatest, ageDays } or null
+ */
+function recommendStableVersion(info, stabilityWindowDays = STABILITY_WINDOW_DAYS) {
+  if (!info?.allVersions || !info.versionTimes) return null;
+
+  const candidates = info.allVersions
+    .map(v => ({ version: v, parsed: parseSemverLoose(v), publishedAt: info.versionTimes[v] }))
+    .filter(c => c.parsed && c.publishedAt)
+    .map(c => ({ ...c, ageDays: Math.floor((Date.now() - new Date(c.publishedAt).getTime()) / (1000 * 60 * 60 * 24)) }))
+    .filter(c => c.ageDays >= stabilityWindowDays)
+    .sort((a, b) => (
+      b.parsed.major - a.parsed.major || b.parsed.minor - a.parsed.minor || b.parsed.patch - a.parsed.patch
+    ));
+
+  if (candidates.length === 0) return null;
+  const best = candidates[0];
+  return {
+    recommendedVersion: best.version,
+    isLatest: best.version === info.latestVersion,
+    ageDays: best.ageDays,
+  };
+}
+
+/**
+ * Check freshness of one dependency against its registry.
+ * @param {string} ecosystem - npm | PyPI | Go | Maven
+ * @param {string} packageName
+ * @param {string} currentVersion
+ * @returns {Promise<Object>} freshness result, or { available: false } if
+ *   the ecosystem isn't supported or the registry call failed — never a
+ *   guessed result.
+ */
+async function checkFreshness(ecosystem, packageName, currentVersion) {
+  const lookup = REGISTRY_LOOKUPS[ecosystem];
+  if (!lookup) {
+    return { available: false, reason: `No registry lookup implemented for ecosystem "${ecosystem}"` };
+  }
+
+  let info;
+  try {
+    info = await lookup(packageName);
+  } catch (error) {
+    return { available: false, reason: `Registry lookup failed: ${error.message}` };
+  }
+  if (!info) return { available: false, reason: 'Package not found in registry' };
+
+  const distance = semverDistance(currentVersion, info.latestVersion);
+  const ageDays = info.publishedAt
+    ? Math.floor((Date.now() - new Date(info.publishedAt).getTime()) / (1000 * 60 * 60 * 24))
+    : null;
+
+  // Freshness score: 100 if on latest, degrading with major/minor distance.
+  // Capped at 0. Unknown distance (non-semver) leaves it null rather than 0.
+  let freshnessScore = null;
+  if (distance.comparable) {
+    const majorPenalty = Math.max(distance.majors, 0) * 40;
+    const minorPenalty = distance.minors !== null ? Math.max(distance.minors, 0) * 5 : 0;
+    freshnessScore = Math.max(100 - majorPenalty - minorPenalty, 0);
+  }
+
+  return {
+    available: true,
+    ecosystem,
+    package: packageName,
+    currentVersion,
+    latestVersion: info.latestVersion,
+    latestPublishedAt: info.publishedAt,
+    latestAgeDays: ageDays,
+    versionsBehind: distance,
+    freshnessScore,
+    // A release published in the last STABILITY_WINDOW_DAYS hasn't had time
+    // to surface regressions yet — recommend it cautiously, not blindly.
+    stabilityNote: ageDays === null
+      ? 'unknown publish date'
+      : ageDays < STABILITY_WINDOW_DAYS
+        ? `latest was published ${ageDays}d ago — still within the ${STABILITY_WINDOW_DAYS}d settling window, consider waiting unless this is a security fix`
+        : `latest has been out ${ageDays}d with no newer release — settled`,
+    stableRecommendation: recommendStableVersion(info),
+  };
+}
+
+module.exports = {
+  checkFreshness,
+  recommendStableVersion,
+  chooseSecureTargetVersion,
+  semverDistance,
+  compareSemver,
+  parseSemverLoose,
+  STABILITY_WINDOW_DAYS,
+};

package/src/freshnessPolicy.js

@@ -0,0 +1,73 @@
+/**
+ * Freshness policy enforcement: "never stay more than 2 minor versions
+ * behind" / "never more than 6 months behind" — the technical-debt
+ * prevention angle, separate from CVE-driven urgency. Thresholds come
+ * from AGENTS.md via configLoader.js; null/unset means "not enforced",
+ * never a hardcoded default that wasn't actually requested.
+ */
+
+/**
+ * @param {Object} dependency - { package, ecosystem, currentVersion }
+ * @param {Object} freshness - result from freshnessChecker.checkFreshness
+ * @param {Object} policy - freshness_policy section from configLoader
+ * @returns {Object} { compliant, violations: string[] }
+ */
+function checkPolicy(dependency, freshness, policy = {}) {
+  if (!freshness?.available) {
+    return { compliant: true, violations: [], note: 'freshness data unavailable — policy not evaluated' };
+  }
+
+  const violations = [];
+
+  if (policy.max_minor_versions_behind != null && freshness.versionsBehind?.comparable) {
+    const totalMinorsBehind = freshness.versionsBehind.majors > 0
+      ? Infinity // any major version behind exceeds a minor-version budget
+      : (freshness.versionsBehind.minors ?? 0);
+    if (totalMinorsBehind > policy.max_minor_versions_behind) {
+      violations.push(
+        `${dependency.package} is ${freshness.versionsBehind.majors > 0 ? 'a major version' : `${totalMinorsBehind} minor versions`} behind ${freshness.latestVersion} — policy allows at most ${policy.max_minor_versions_behind} minor version(s) behind`
+      );
+    }
+  }
+
+  if (policy.max_days_behind != null && freshness.latestAgeDays != null) {
+    // "days behind" here means: how long has a newer version been
+    // available that we haven't adopted — approximated by the age of the
+    // latest release, since that's the real registry data we have (we
+    // don't track "when did we last upgrade" without git history analysis).
+    if (freshness.currentVersion !== freshness.latestVersion && freshness.latestAgeDays > policy.max_days_behind) {
+      violations.push(
+        `${dependency.package} has been behind the latest release (${freshness.latestVersion}, published ${freshness.latestAgeDays}d ago) for longer than the ${policy.max_days_behind}d policy window`
+      );
+    }
+  }
+
+  return { compliant: violations.length === 0, violations };
+}
+
+/**
+ * Run policy checks across a whole dependency list, skipping excluded
+ * packages from AGENTS.md.
+ * @param {Array} dependenciesWithFreshness - [{ dependency, freshness }]
+ * @param {Object} config - result of configLoader.loadAgentsConfig
+ * @returns {Object} { compliantCount, violationCount, violations: [{package, violations}] }
+ */
+function runPolicyCheck(dependenciesWithFreshness, config) {
+  const excluded = new Set(config.excluded_packages || []);
+  const violations = [];
+  let compliantCount = 0;
+
+  const included = dependenciesWithFreshness.filter(({ dependency }) => !excluded.has(dependency.package));
+  for (const { dependency, freshness } of included) {
+    const result = checkPolicy(dependency, freshness, config.freshness_policy);
+    if (result.compliant) {
+      compliantCount += 1;
+    } else {
+      violations.push({ package: dependency.package, ecosystem: dependency.ecosystem, violations: result.violations });
+    }
+  }
+
+  return { compliantCount, violationCount: violations.length, violations };
+}
+
+module.exports = { checkPolicy, runPolicyCheck };

package/src/gitlabAuth.js

@@ -0,0 +1,38 @@
+/**
+ * Shared GitLab API auth headers.
+ *
+ * Two distinct tokens, used for different things:
+ *  - GITLAB_TOKEN: a manually-configured Personal/Project Access Token
+ *    (CI/CD variable, or auto-injected by a Custom Flow's composite
+ *    identity — see .gitlab/duo/flows/vulnerability-analysis-flow.yaml).
+ *    Needed for anything that has to reach across projects (the
+ *    cross-project emergency response) or act with broader scope than a
+ *    single job.
+ *  - CI_JOB_TOKEN: automatically present in every GitLab CI job, zero
+ *    setup, scoped to that job's own project with the triggering user's
+ *    permissions. This is the right default for same-project, read-ish
+ *    calls (the activity feed, Orbit status) so a human never has to
+ *    manually paste a token just to make the dashboard's "what has the
+ *    agent done" section work.
+ *
+ * GITLAB_TOKEN takes priority when set (it's the more capable token);
+ * CI_JOB_TOKEN is the automatic fallback. If neither is present, callers
+ * get an empty auth header and should treat the resulting 401 as
+ * "unavailable", not invent data.
+ */
+
+function getAuthHeaders() {
+  if (process.env.GITLAB_TOKEN) {
+    return { 'PRIVATE-TOKEN': process.env.GITLAB_TOKEN };
+  }
+  if (process.env.CI_JOB_TOKEN) {
+    return { 'JOB-TOKEN': process.env.CI_JOB_TOKEN };
+  }
+  return {};
+}
+
+function hasAnyToken() {
+  return Boolean(process.env.GITLAB_TOKEN || process.env.CI_JOB_TOKEN);
+}
+
+module.exports = { getAuthHeaders, hasAnyToken };

package/src/httpRetry.js

@@ -0,0 +1,48 @@
+/**
+ * Shared retry/backoff helper for the HTTP calls this project makes to
+ * GitLab Orbit and package registries (npm, PyPI, Go proxy, Maven
+ * Central). A flaky network hiccup during a live demo or a CI run
+ * shouldn't read as "Orbit unavailable" / "registry lookup failed" when
+ * a second attempt would have succeeded — but a real rejection (a 404 for
+ * "this package doesn't exist," a 400 for a malformed query) must never
+ * be retried, since retrying a deterministic rejection just wastes time
+ * and risks masking a real bug as a transient one.
+ *
+ * Transient = no HTTP response at all (DNS failure, connection reset,
+ * timeout) or a 5xx from the server. Anything else (4xx, or a 2xx that
+ * the caller itself decides is wrong) is final on the first attempt.
+ */
+
+function isTransientError(error) {
+  const transientCodes = new Set(['ECONNABORTED', 'ETIMEDOUT', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN']);
+  if (error.code && transientCodes.has(error.code)) return true;
+  const status = error.response?.status;
+  // No response at all (network-level failure axios didn't tag with a
+  // known code) is treated the same as a 5xx: worth one retry.
+  return status === undefined || status >= 500;
+}
+
+/**
+ * @param {() => Promise<any>} fn - the call to attempt
+ * @param {Object} [options]
+ * @param {number} [options.retries=2] - additional attempts after the first
+ * @param {number} [options.baseDelayMs=300] - delay before the first retry; doubles each subsequent attempt
+ * @returns {Promise<any>}
+ */
+async function withRetry(fn, { retries = 2, baseDelayMs = 300 } = {}) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const isFinalAttempt = attempt === retries;
+      if (isFinalAttempt || !isTransientError(error)) throw error;
+      const delayMs = baseDelayMs * 2 ** attempt;
+      await new Promise(resolve => { setTimeout(resolve, delayMs); });
+    }
+  }
+  throw lastError;
+}
+
+module.exports = { withRetry, isTransientError };

package/src/impactReport.js

@@ -0,0 +1,92 @@
+/**
+ * Upgrade Impact Report.
+ *
+ * Answers "how painful will this upgrade actually be?" by combining:
+ *  - blast radius (files/services actually affected — from Orbit)
+ *  - semver distance (major/minor jump — from freshnessChecker)
+ *  - a breaking-change *flag*, not a guess: a major version bump is a
+ *    documented semver signal that breaking changes are allowed, so we
+ *    surface that as "likely breaking" with the reasoning shown, rather
+ *    than claiming to know which specific APIs changed. Actually
+ *    diffing APIs across 12 languages is out of scope — this is honest
+ *    about that limit instead of inventing a fake API diff.
+ */
+
+const { semverDistance } = require('./freshnessChecker');
+const { buildUpgradeImpactSimulation } = require('./upgradeImpactSimulator');
+
+const ECOSYSTEM_COMPLEXITY_WEIGHT = {
+  npm: 1.0,
+  PyPI: 1.1,
+  Go: 0.9,
+  Maven: 1.3, // XML/build-tool friction tends to add overhead
+};
+
+/**
+ * @param {Object} vulnerability - normalized vulnerability with riskScore/exposure
+ * @param {Object} freshness - result from freshnessChecker.checkFreshness (optional)
+ * @returns {Object} impact report
+ */
+function buildImpactReport(vulnerability, freshness = null) {
+  const affectedFiles = vulnerability.affectedFiles || [];
+  const distance = freshness?.versionsBehind
+    || semverDistance(vulnerability.currentVersion, vulnerability.fixedVersion);
+
+  const likelyBreaking = distance.comparable && distance.majors > 0;
+
+  // Effort estimate: base 30 minutes plus per-file review time, scaled by
+  // ecosystem friction and bumped if this crosses a major version. This is
+  // a heuristic estimate, not a measurement — labelled as such everywhere
+  // it's surfaced.
+  const weight = ECOSYSTEM_COMPLEXITY_WEIGHT[vulnerability.ecosystem] || 1.0;
+  const perFileMinutes = 8 * weight;
+  const baseMinutes = 30 * weight;
+  const majorBumpPenaltyMinutes = likelyBreaking ? 120 * weight : 0;
+  const estimatedMinutes = Math.round(baseMinutes + (affectedFiles.length * perFileMinutes) + majorBumpPenaltyMinutes);
+
+  const report = {
+    package: vulnerability.package,
+    ecosystem: vulnerability.ecosystem,
+    from: vulnerability.currentVersion,
+    to: vulnerability.fixedVersion,
+    affectedFilesCount: affectedFiles.length,
+    affectedFiles: affectedFiles.slice(0, 10).map(f => f.path || f),
+    exposureDataSource: vulnerability.riskScore?.exposureDataSource || 'unavailable',
+    versionsBehind: distance,
+    likelyBreaking,
+    breakingChangeReasoning: likelyBreaking
+      ? `Major version bump (${distance.majors} major version${distance.majors > 1 ? 's' : ''}) — semver allows breaking changes here. This flags the risk; it does not enumerate the specific API changes, since that requires per-language AST diffing this tool does not do.`
+      : 'No major version bump detected — breaking changes are possible but not signaled by semver.',
+    estimatedEffort: {
+      minutes: estimatedMinutes,
+      hours: Math.round((estimatedMinutes / 60) * 10) / 10,
+      basis: `${affectedFiles.length} affected file(s) × ~${Math.round(perFileMinutes)}min review${likelyBreaking ? ' + major-version-bump overhead' : ''} (${vulnerability.ecosystem} complexity weight ${weight})`,
+    },
+    freshness: freshness?.available ? freshness : null,
+  };
+
+  return {
+    ...report,
+    simulation: buildUpgradeImpactSimulation(vulnerability, report),
+  };
+}
+
+/**
+ * Render the impact report as markdown for an MR description or issue.
+ */
+function formatImpactReport(report) {
+  return `## Upgrade Impact Report: ${report.package}
+
+- **Version**: ${report.from} → ${report.to}${report.versionsBehind?.comparable ? ` (${report.versionsBehind.majors} major version(s) behind)` : ''}
+- **Affected files**: ${report.affectedFilesCount} (source: ${report.exposureDataSource === 'orbit' ? 'GitLab Orbit blast-radius query' : 'unavailable — Orbit not enabled/reachable'})
+${report.affectedFiles.map(f => `  - ${f}`).join('\n')}
+- **Likely breaking?**: ${report.likelyBreaking ? '⚠️ Yes' : 'Not signaled by semver'} — ${report.breakingChangeReasoning}
+- **Estimated effort**: ~${report.estimatedEffort.hours}h (${report.estimatedEffort.basis})
+${report.freshness ? `- **Registry freshness**: latest is ${report.freshness.latestVersion}, published ${report.freshness.latestAgeDays ?? '?'}d ago — ${report.freshness.stabilityNote}` : ''}
+`;
+}
+
+module.exports = {
+  buildImpactReport,
+  formatImpactReport,
+};