dependencyiq 2.0.0

package/src/mrReviewer.js

@@ -0,0 +1,245 @@
+/**
+ * MR Safety Review — DependencyIQ as the safety layer for *incoming*
+ * dependency merge requests (from Dependabot, Renovate, or a human),
+ * not just a tool that opens its own.
+ *
+ * The unique lever: when an MR changes a dependency, query GitLab Orbit
+ * for that package's real blast radius and turn it into an
+ * approve / review / block verdict — "this bumps axios, imported by 5
+ * public-API files; major version → blocked, verify first" vs "patch
+ * bump, internal usage only → safe". This makes DependencyIQ
+ * complementary to update bots rather than competing: it makes their MRs
+ * trustworthy.
+ *
+ * This module is pure (manifest contents + an exposure lookup in, verdict
+ * out) so it's fully testable; the CLI/CI layer (agent.js `review-mr`)
+ * supplies the real base/head manifests and the Orbit exposure lookup.
+ */
+
+const { semverDistance } = require('./freshnessChecker');
+
+const VERDICT_RANK = { safe: 0, review: 1, blocked: 2 };
+
+function parseJsonSafe(content) {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+function npmDependencyMap(pkg) {
+  const map = {};
+  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    for (const [name, range] of Object.entries(pkg[section] || {})) {
+      map[name] = { range: String(range), version: String(range).replace(/^[~^>=<\s]+/, ''), section };
+    }
+  }
+  return map;
+}
+
+/**
+ * Diff two package.json contents into a list of dependency changes.
+ * @returns {Array} [{ package, ecosystem, kind, fromVersion, toVersion }]
+ *   kind: 'added' | 'removed' | 'changed' | 'override-added'
+ */
+function diffNpmManifests(baseContent, headContent) {
+  const base = parseJsonSafe(baseContent);
+  const head = parseJsonSafe(headContent);
+  const baseMap = npmDependencyMap(base);
+  const headMap = npmDependencyMap(head);
+  const changes = [];
+
+  const names = new Set([...Object.keys(baseMap), ...Object.keys(headMap)]);
+  for (const name of names) {
+    const b = baseMap[name];
+    const h = headMap[name];
+    if (b && !h) {
+      changes.push({ package: name, ecosystem: 'npm', kind: 'removed', fromVersion: b.version, toVersion: null });
+    } else if (!b && h) {
+      changes.push({ package: name, ecosystem: 'npm', kind: 'added', fromVersion: null, toVersion: h.version });
+    } else if (b && h && b.range !== h.range) {
+      changes.push({ package: name, ecosystem: 'npm', kind: 'changed', fromVersion: b.version, toVersion: h.version });
+    }
+  }
+
+  // `overrides` changes are security-relevant (transitive pins).
+  const baseOv = base.overrides || {};
+  const headOv = head.overrides || {};
+  for (const [name, value] of Object.entries(headOv)) {
+    if (baseOv[name] !== value) {
+      changes.push({ package: name, ecosystem: 'npm', kind: 'override-added', fromVersion: baseOv[name] || null, toVersion: String(value) });
+    }
+  }
+
+  return changes;
+}
+
+function worse(a, b) {
+  return VERDICT_RANK[a] >= VERDICT_RANK[b] ? a : b;
+}
+
+/**
+ * Turn one dependency change + its Orbit exposure into a safety verdict.
+ * @param {Object} change - from diffNpmManifests
+ * @param {Object} exposure - { available, affectedFilesCount, isInPublicAPI,
+ *   source } from blastRadius.analyzeExposure (or { available:false })
+ * @returns {Object} { package, kind, fromVersion, toVersion, semver,
+ *   verdict, reasons, exposureSource }
+ */
+function reviewChange(change, exposure = {}) {
+  const reasons = [];
+  let verdict = 'safe';
+  const orbitReal = exposure.source === 'orbit';
+  const fileCount = orbitReal ? (exposure.affectedFilesCount || 0) : null;
+  const publicApi = orbitReal && exposure.isInPublicAPI;
+
+  if (change.kind === 'removed') {
+    reasons.push('Dependency removed — reduces attack surface. No upgrade risk.');
+    return finalize(change, 'safe', reasons, exposure);
+  }
+
+  if (change.kind === 'override-added') {
+    reasons.push(`Adds an \`overrides\` pin for **${change.package}** (${change.toVersion}) — forces a patched floor on a transitive package. This is a security hardening change.`);
+    return finalize(change, 'safe', reasons, exposure);
+  }
+
+  if (change.kind === 'added') {
+    verdict = 'review';
+    reasons.push(`New dependency **${change.package}@${change.toVersion}** added — review supply-chain trust (maintainer, install scripts) and whether it's necessary.`);
+    return finalize(change, verdict, reasons, exposure);
+  }
+
+  // 'changed' — the main case.
+  const dist = semverDistance(change.fromVersion, change.toVersion);
+  if (dist.comparable && dist.majors < 0) {
+    verdict = worse(verdict, 'review');
+    reasons.push(`Version **downgrade** ${change.fromVersion} → ${change.toVersion} — confirm this is intentional, not an accidental regression.`);
+  } else if (dist.comparable && dist.majors > 0) {
+    if (publicApi) {
+      verdict = worse(verdict, 'blocked');
+      reasons.push(`**Major** bump ${change.fromVersion} → ${change.toVersion} in a package imported by ${fileCount} file(s), including public-API code — high risk of breaking production-facing behaviour. Verify call sites and run the full suite before merging.`);
+    } else {
+      verdict = worse(verdict, 'review');
+      reasons.push(`**Major** bump ${change.fromVersion} → ${change.toVersion} — semver allows breaking changes${orbitReal ? `; ${fileCount} file(s) import it` : ''}. Review the changelog and affected call sites.`);
+    }
+  } else if (dist.comparable) {
+    // minor / patch
+    if (publicApi) {
+      verdict = worse(verdict, 'review');
+      reasons.push(`Minor/patch bump ${change.fromVersion} → ${change.toVersion}, but the package is imported by public-API code (${fileCount} file(s)) — a quick smoke check is worthwhile.`);
+    } else {
+      reasons.push(`Minor/patch bump ${change.fromVersion} → ${change.toVersion}${orbitReal ? `, used by ${fileCount} internal/test file(s)` : ''} — low risk.`);
+    }
+  } else {
+    verdict = worse(verdict, 'review');
+    reasons.push(`Version change ${change.fromVersion} → ${change.toVersion} is not comparable as semver — review manually.`);
+  }
+
+  // Honesty: if Orbit couldn't tell us the blast radius, don't bless a
+  // change as fully "safe" on faith — nudge to at least a review and say so.
+  if (!orbitReal) {
+    reasons.push('GitLab Orbit exposure was unavailable for this run, so this verdict is based on the version change alone, not real import-graph evidence.');
+    if (verdict === 'safe' && change.kind === 'changed') verdict = 'review';
+  }
+
+  return finalize(change, verdict, reasons, exposure);
+}
+
+function finalize(change, verdict, reasons, exposure) {
+  return {
+    package: change.package,
+    kind: change.kind,
+    fromVersion: change.fromVersion,
+    toVersion: change.toVersion,
+    semver: semverDistance(change.fromVersion, change.toVersion),
+    verdict,
+    reasons,
+    exposureSource: exposure.source === 'orbit' ? 'orbit' : 'unavailable',
+  };
+}
+
+/**
+ * Map a Supply-Chain Trust classification (see
+ * scanners/supplyChainTrustSignals.js) onto the same safe/review/blocked
+ * vocabulary as the semver verdict, so the two can be combined with the
+ * same `worse()` rule — without ever blending their underlying numbers.
+ * A package can be CRITICAL on trust with zero CVEs; this is what lets
+ * that show up in the overall verdict without touching the CVSS-driven
+ * risk score anywhere else in the codebase.
+ */
+function classifyTrustVerdict(trust) {
+  if (!trust) return null;
+  if (trust.classification === 'CRITICAL') return 'blocked';
+  if (trust.classification === 'ELEVATED') return 'review';
+  return 'safe';
+}
+
+/**
+ * @param {Object} review - one reviewChange() result
+ * @param {Object} trustByPackage - { [packageName]: assessSupplyChainTrust() result }
+ */
+function effectiveVerdict(review, trustByPackage = {}) {
+  const trustVerdict = classifyTrustVerdict(trustByPackage[review.package]);
+  return trustVerdict ? worse(review.verdict, trustVerdict) : review.verdict;
+}
+
+/**
+ * Roll individual change reviews into an overall MR verdict.
+ * `trustByPackage` is optional and additive — omitting it reproduces the
+ * exact semver-only behaviour this function always had.
+ */
+function summarizeReview(reviews, trustByPackage = {}) {
+  const counts = { safe: 0, review: 0, blocked: 0 };
+  let overall = 'safe';
+  for (const r of reviews) {
+    const v = effectiveVerdict(r, trustByPackage);
+    counts[v] += 1;
+    overall = worse(overall, v);
+  }
+  return { overall, counts, total: reviews.length };
+}
+
+const VERDICT_ICON = { safe: '✅', review: '🟡', blocked: '🔴' };
+const TRUST_ICON = { CRITICAL: '🔴', ELEVATED: '🟡', NORMAL: '✅' };
+
+/**
+ * Build the markdown review note posted to the MR.
+ * @param {Array} reviews - reviewChange() results
+ * @param {Object} trustByPackage - optional { [packageName]: assessSupplyChainTrust() result },
+ *   rendered as a separate "Supply-chain trust" line per change — never
+ *   merged into the semver-based reasons above it.
+ */
+function buildReviewNote(reviews, trustByPackage = {}) {
+  if (reviews.length === 0) {
+    return '### 🛡️ DependencyIQ MR Safety Review\n\nNo dependency changes detected in this merge request.';
+  }
+  const summary = summarizeReview(reviews, trustByPackage);
+  const header = `### 🛡️ DependencyIQ MR Safety Review\n\n**Overall: ${VERDICT_ICON[summary.overall]} ${summary.overall.toUpperCase()}** — ${summary.total} dependency change(s): ${summary.counts.blocked} blocked, ${summary.counts.review} to review, ${summary.counts.safe} safe.`;
+
+  const rows = reviews.map(r => {
+    const change = r.kind === 'removed' ? `removed (was ${r.fromVersion})`
+      : r.kind === 'added' ? `added @ ${r.toVersion}`
+        : r.kind === 'override-added' ? `override → ${r.toVersion}`
+          : `${r.fromVersion} → ${r.toVersion}`;
+    const verdict = effectiveVerdict(r, trustByPackage);
+    const trust = trustByPackage[r.package];
+    const trustLine = trust
+      ? `\n- **Supply-chain trust: ${TRUST_ICON[trust.classification]} ${trust.classification} (${trust.score}/100)** — ${trust.reasons.filter((_, i) => trust.classification !== 'NORMAL' || i === 0).join(' ')}`
+      : '';
+    return `\n#### ${VERDICT_ICON[verdict]} \`${r.package}\` — ${change}\n${r.reasons.map(x => `- ${x}`).join('\n')}${trustLine}`;
+  }).join('\n');
+
+  const footer = `\n\n---\nExposure evidence: ${reviews.some(r => r.exposureSource === 'orbit') ? 'GitLab Orbit blast-radius query' : 'unavailable — Orbit not reachable for this run'}. ${summary.overall === 'blocked' ? '**Recommend blocking merge until the flagged items are verified.**' : summary.overall === 'review' ? 'Recommend a quick human review of the flagged items before merge.' : 'No blast-radius concerns — safe to merge once CI is green.'}`;
+
+  return `${header}\n${rows}${footer}`;
+}
+
+module.exports = {
+  diffNpmManifests,
+  reviewChange,
+  summarizeReview,
+  buildReviewNote,
+  classifyTrustVerdict,
+  effectiveVerdict,
+};

package/src/orbitClient.js

@@ -0,0 +1,214 @@
+/**
+ * GitLab Orbit REST client.
+ *
+ * Public API docs confirm:
+ * - POST /api/v4/orbit/query takes { query, query_type, response_format }.
+ * - `search` uses a singular `node`.
+ * - joins use `traversal` with `nodes` and `relationships`.
+ * - result rows are flattened by alias, for example `f_path`, not
+ *   necessarily nested as `row.f.path`.
+ *
+ * The exact source-code relationship names can evolve with the schema,
+ * so this client asks Orbit schema first and falls back through a small
+ * set of likely edge names. If Orbit rejects every candidate, callers
+ * fall back to "exposure unavailable" rather than inventing data.
+ */
+
+const axios = require('axios');
+const { getAuthHeaders: authHeaders } = require('./gitlabAuth');
+const { withRetry } = require('./httpRetry');
+
+const GITLAB_API = process.env.GITLAB_API_URL
+  || (process.env.GITLAB_BASE_URL ? `${process.env.GITLAB_BASE_URL}/api/v4` : 'https://gitlab.com/api/v4');
+const ORBIT_BASE = `${GITLAB_API}/orbit`;
+
+const IMPORT_TO_FILE_EDGE_CANDIDATES = [
+  'IN_FILE',
+  'IMPORTED_IN',
+  'DEFINED_IN',
+  'REFERENCED_IN',
+  'BELONGS_TO',
+];
+
+const FILE_TO_PROJECT_EDGE_CANDIDATES = [
+  'IN_PROJECT',
+  'BELONGS_TO',
+];
+
+let expandedSourceSchema = null;
+
+async function getStatus() {
+  const response = await withRetry(() => axios.get(`${ORBIT_BASE}/status`, {
+    headers: authHeaders(),
+    timeout: 5000,
+  }));
+  return response.data;
+}
+
+async function getSchema(expand) {
+  const response = await withRetry(() => axios.get(`${ORBIT_BASE}/schema`, {
+    headers: authHeaders(),
+    params: expand ? { expand } : undefined,
+    timeout: 10000,
+  }));
+  return response.data;
+}
+
+async function getSourceSchema() {
+  if (!expandedSourceSchema) {
+    expandedSourceSchema = await getSchema('ImportedSymbol,File,Project');
+  }
+  return expandedSourceSchema;
+}
+
+async function listTools() {
+  const response = await withRetry(() => axios.get(`${ORBIT_BASE}/tools`, {
+    headers: authHeaders(),
+    timeout: 10000,
+  }));
+  return response.data;
+}
+
+async function query(queryDsl, options = {}) {
+  const response = await withRetry(() => axios.post(
+    `${ORBIT_BASE}/query`,
+    {
+      query: queryDsl,
+      query_type: 'json',
+      response_format: options.responseFormat || 'raw',
+    },
+    { headers: authHeaders(), timeout: 15000 }
+  ));
+  return response.data;
+}
+
+function edgeName(edge) {
+  return edge?.type || edge?.name || edge?.relationship_type;
+}
+
+function edgeEndpoint(edge, keys) {
+  for (const key of keys) {
+    if (edge?.[key]) return String(edge[key]);
+  }
+  return null;
+}
+
+function edgeMatches(edge, fromEntity, toEntity) {
+  const from = edgeEndpoint(edge, ['from', 'source', 'source_node', 'source_type', 'from_node', 'from_entity']);
+  const to = edgeEndpoint(edge, ['to', 'target', 'target_node', 'target_type', 'to_node', 'to_entity']);
+  if (!from || !to) return false;
+  return from.includes(fromEntity) && to.includes(toEntity);
+}
+
+async function relationshipCandidates(fromEntity, toEntity, fallback) {
+  try {
+    const schema = await getSourceSchema();
+    const schemaEdges = (schema.edges || [])
+      .filter(edge => edgeMatches(edge, fromEntity, toEntity))
+      .map(edgeName)
+      .filter(Boolean);
+    return [...new Set([...schemaEdges, ...fallback])];
+  } catch {
+    return fallback;
+  }
+}
+
+function rowValue(row, alias, field) {
+  return row?.[`${alias}_${field}`] ?? row?.[alias]?.[field] ?? row?.[field];
+}
+
+async function queryWithRelationshipFallback(buildQuery, relationshipSets) {
+  let lastError = null;
+  const [firstSet, secondSet = [null]] = relationshipSets;
+  for (const first of firstSet) {
+    for (const second of secondSet) {
+      try {
+        return await query(buildQuery(first, second));
+      } catch (error) {
+        lastError = error;
+      }
+    }
+  }
+  throw lastError;
+}
+
+async function findPackageImporters(projectId, packageName) {
+  const importToFileEdges = await relationshipCandidates('ImportedSymbol', 'File', IMPORT_TO_FILE_EDGE_CANDIDATES);
+  const fileToProjectEdges = await relationshipCandidates('File', 'Project', FILE_TO_PROJECT_EDGE_CANDIDATES);
+  const result = await queryWithRelationshipFallback(
+    (importToFileEdge, fileToProjectEdge) => ({
+      query_type: 'traversal',
+      nodes: [
+        { id: 'p', entity: 'Project', node_ids: [Number(projectId)] },
+        {
+          id: 'imp',
+          entity: 'ImportedSymbol',
+          filters: { import_path: { contains: packageName } },
+        },
+        { id: 'f', entity: 'File', columns: ['path', 'language'] },
+      ],
+      relationships: [
+        { type: importToFileEdge, from: 'imp', to: 'f' },
+        { type: fileToProjectEdge, from: 'f', to: 'p' },
+      ],
+      limit: 200,
+    }),
+    [importToFileEdges, fileToProjectEdges]
+  );
+
+  return (result.result || []).map(row => ({
+    path: rowValue(row, 'f', 'path'),
+    language: rowValue(row, 'f', 'language'),
+    importPath: rowValue(row, 'imp', 'import_path') || packageName,
+  }));
+}
+
+async function findProjectsImportingPackage(groupId, packageName) {
+  const importToFileEdges = await relationshipCandidates('ImportedSymbol', 'File', IMPORT_TO_FILE_EDGE_CANDIDATES);
+  const fileToProjectEdges = await relationshipCandidates('File', 'Project', FILE_TO_PROJECT_EDGE_CANDIDATES);
+  const result = await queryWithRelationshipFallback(
+    (importToFileEdge, fileToProjectEdge) => ({
+      query_type: 'traversal',
+      nodes: [
+        {
+          id: 'imp',
+          entity: 'ImportedSymbol',
+          filters: { import_path: { contains: packageName } },
+        },
+        { id: 'f', entity: 'File', columns: ['path', 'language'] },
+        { id: 'p', entity: 'Project', columns: ['id', 'full_path'], filters: { group_id: String(groupId) } },
+      ],
+      relationships: [
+        { type: importToFileEdge, from: 'imp', to: 'f' },
+        { type: fileToProjectEdge, from: 'f', to: 'p' },
+      ],
+      limit: 500,
+    }),
+    [importToFileEdges, fileToProjectEdges]
+  );
+
+  const byProject = new Map();
+  for (const row of result.result || []) {
+    const projectId = rowValue(row, 'p', 'id');
+    if (projectId) {
+      if (!byProject.has(projectId)) {
+        byProject.set(projectId, { projectId, projectPath: rowValue(row, 'p', 'full_path'), files: [] });
+      }
+      byProject.get(projectId).files.push({
+        path: rowValue(row, 'f', 'path'),
+        language: rowValue(row, 'f', 'language'),
+        importPath: rowValue(row, 'imp', 'import_path') || packageName,
+      });
+    }
+  }
+  return Array.from(byProject.values());
+}
+
+module.exports = {
+  getStatus,
+  getSchema,
+  listTools,
+  query,
+  findPackageImporters,
+  findProjectsImportingPackage,
+};

package/src/prGenerator.js

@@ -0,0 +1,228 @@
+/**
+ * PR Generator
+ * Commits an applied dependency fix and opens a real merge request for it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const axios = require('axios');
+const { getAuthHeaders, hasAnyToken } = require('./gitlabAuth');
+
+// GITLAB_API_URL: manual override for standalone CLI/CI use.
+// GITLAB_BASE_URL: auto-injected by GitLab when this runs inside a Duo
+// Custom Flow (see .gitlab/duo/flows/vulnerability-analysis-flow.yaml).
+const GITLAB_API = process.env.GITLAB_API_URL
+  || (process.env.GITLAB_BASE_URL ? `${process.env.GITLAB_BASE_URL}/api/v4` : 'https://gitlab.com/api/v4');
+
+function apiConfig() {
+  return {
+    headers: {
+      ...getAuthHeaders(),
+      'Content-Type': 'application/json',
+    },
+  };
+}
+
+/**
+ * Commit one or more already-edited files and open a merge request.
+ * @param {string} projectId - GitLab project ID
+ * @param {string} repoPath - local checkout path the files were edited in
+ * @param {Object} vulnerability - vulnerability being fixed
+ * @param {Object} fixResult - result from ecosystemFixers.applyFix (must have filePath)
+ * @param {string} description - MR description (markdown)
+ * @returns {Object} created MR info
+ */
+async function createAutomatedPR(projectId, repoPath, vulnerability, fixResult, description = '') {
+  if (!hasAnyToken()) {
+    console.warn('   ⚠️  No GITLAB_TOKEN or CI_JOB_TOKEN available. Skipping PR creation.');
+    return { success: false, reason: 'No GitLab API token available', web_url: '#' };
+  }
+
+  if (!fixResult?.applied || !fixResult.filePath) {
+    return { success: false, reason: 'No applied fix to commit (run with --fix first)' };
+  }
+
+  console.log(`📝 Creating merge request for ${vulnerability.package}...`);
+  const branchName = `security/upgrade-${slug(vulnerability.package)}-${Date.now()}`;
+
+  try {
+    await axios.post(
+      `${GITLAB_API}/projects/${projectId}/repository/branches`,
+      { branch: branchName, ref: 'main' },
+      apiConfig()
+    );
+    console.log(`   ✓ Created branch: ${branchName}`);
+  } catch (error) {
+    if (error.response?.status !== 400) throw error;
+  }
+
+  const fileContent = fs.readFileSync(path.join(repoPath, fixResult.filePath), 'utf-8');
+
+  await axios.post(
+    `${GITLAB_API}/projects/${projectId}/repository/commits`,
+    {
+      branch: branchName,
+      commit_message: fixResult.action === 'remove'
+        ? `chore: remove unused dependency ${vulnerability.package} (${vulnerability.id}, Orbit found zero importers)`
+        : `security: upgrade ${vulnerability.package} to ${vulnerability.fixedVersion} (${vulnerability.id})`,
+      actions: [
+        {
+          action: 'update',
+          file_path: fixResult.filePath.replace(/\\/g, '/'),
+          content: fileContent,
+        },
+      ],
+    },
+    apiConfig()
+  );
+  console.log(`   ✓ Committed ${fixResult.filePath} to ${branchName}`);
+
+  const mrResponse = await axios.post(
+    `${GITLAB_API}/projects/${projectId}/merge_requests`,
+    {
+      source_branch: branchName,
+      target_branch: 'main',
+      title: fixResult.action === 'remove'
+        ? `Cleanup: Remove unused dependency ${vulnerability.package}`
+        : `Security: Upgrade ${vulnerability.package} (${vulnerability.severity})`,
+      description,
+      labels: fixResult.action === 'remove'
+        ? ['cleanup', 'automated', 'dependencies', 'dependencyiq']
+        : ['security', 'automated', 'dependencies', 'dependencyiq'],
+      allow_collaboration: true,
+      squash_commits: true,
+    },
+    apiConfig()
+  );
+
+  const mr = mrResponse.data;
+  console.log(`   ✓ MR created: ${mr.web_url}`);
+
+  return {
+    success: true,
+    id: mr.iid,
+    url: mr.web_url,
+    title: mr.title,
+    branch: branchName,
+    followUp: fixResult.followUp,
+  };
+}
+
+/**
+ * Open a merge request for a branch that's already been committed to
+ * (e.g. by remoteFixer.js for a cross-project emergency response, where
+ * the commit happens via the API with no local checkout at all).
+ * @param {string} projectId - GitLab project ID
+ * @param {Object} vulnerability - vulnerability being fixed
+ * @param {Object} fixResult - result from remoteFixer.applyRemoteFix (must have branch + action)
+ * @param {string} description - MR description (markdown)
+ */
+async function openMergeRequestForBranch(projectId, vulnerability, fixResult, description = '') {
+  const mrResponse = await axios.post(
+    `${GITLAB_API}/projects/${projectId}/merge_requests`,
+    {
+      source_branch: fixResult.branch,
+      target_branch: 'main',
+      title: fixResult.action === 'remove'
+        ? `Cleanup: Remove unused dependency ${vulnerability.package}`
+        : `Security: Upgrade ${vulnerability.package} (${vulnerability.severity})`,
+      description,
+      labels: fixResult.action === 'remove'
+        ? ['cleanup', 'automated', 'dependencies', 'dependencyiq']
+        : ['security', 'automated', 'dependencies', 'dependencyiq'],
+      allow_collaboration: true,
+      squash_commits: true,
+    },
+    apiConfig()
+  );
+
+  const mr = mrResponse.data;
+  return { success: true, id: mr.iid, url: mr.web_url, title: mr.title, branch: fixResult.branch, followUp: fixResult.followUp };
+}
+
+/**
+ * Create a tracking issue in a project — used for every affected project
+ * in an emergency response, even ones where an automated fix wasn't
+ * applied (e.g. transitive dependency, or --fix-all wasn't passed).
+ */
+async function createTrackingIssue(projectId, title, description, labels = ['security', 'automated', 'dependencyiq']) {
+  const response = await axios.post(
+    `${GITLAB_API}/projects/${projectId}/issues`,
+    { title, description, labels: labels.join(',') },
+    apiConfig()
+  );
+  return { success: true, iid: response.data.iid, url: response.data.web_url };
+}
+
+/**
+ * Post a note (comment) on a merge request — used by the MR Safety Review
+ * to attach its Orbit-grounded verdict to an incoming dependency MR.
+ */
+async function postMergeRequestNote(projectId, mrIid, body) {
+  if (!hasAnyToken()) {
+    return { success: false, reason: 'No GITLAB_TOKEN or CI_JOB_TOKEN available' };
+  }
+  const response = await axios.post(
+    `${GITLAB_API}/projects/${encodeURIComponent(projectId)}/merge_requests/${mrIid}/notes`,
+    { body },
+    apiConfig()
+  );
+  return { success: true, id: response.data.id };
+}
+
+function slug(name) {
+  return name.replace(/[^a-zA-Z0-9]+/g, '-').toLowerCase();
+}
+
+/**
+ * Format PR/analysis report as markdown
+ * @param {Array} vulnerabilities - Vulnerabilities analyzed
+ * @returns {string} Formatted report
+ */
+function formatRiskReport(vulnerabilities = []) {
+  let report = '# Dependency Vulnerability Report\n\n';
+
+  report += '## Summary\n\n';
+  report += `Found **${vulnerabilities.length}** vulnerabilities\n\n`;
+
+  const urgent = vulnerabilities.filter(v => v.riskScore?.priority === 'URGENT');
+  const high = vulnerabilities.filter(v => v.riskScore?.priority === 'HIGH');
+  const medium = vulnerabilities.filter(v => v.riskScore?.priority === 'MEDIUM');
+
+  if (urgent.length > 0) report += `- **🔴 URGENT**: ${urgent.length}\n`;
+  if (high.length > 0) report += `- **🟠 HIGH**: ${high.length}\n`;
+  if (medium.length > 0) report += `- **🟡 MEDIUM**: ${medium.length}\n`;
+
+  report += '\n## Vulnerabilities by Risk\n\n';
+
+  const sorted = [...vulnerabilities].sort((a, b) => (b.riskScore?.score || 0) - (a.riskScore?.score || 0));
+
+  for (let i = 0; i < Math.min(5, sorted.length); i += 1) {
+    const v = sorted[i];
+    const emoji = v.riskScore?.priority === 'URGENT' ? '🔴'
+      : v.riskScore?.priority === 'HIGH' ? '🟠'
+      : v.riskScore?.priority === 'MEDIUM' ? '🟡' : '🟢';
+
+    report += `\n### ${emoji} ${i + 1}. ${v.package} (${v.ecosystem || 'unknown ecosystem'})\n`;
+    report += `- **Version**: ${v.currentVersion} → ${v.fixedVersion}\n`;
+    report += `- **Severity**: ${v.severity} (CVSS ${v.cvss})\n`;
+    report += `- **Risk Score**: ${v.riskScore?.score ?? 'N/A'}/100\n`;
+    report += `- **Exposure data**: ${v.riskScore?.exposureDataSource === 'orbit' ? 'GitLab Orbit blast-radius query' : 'unavailable (Orbit not enabled/reachable)'}\n`;
+    report += `- **Issue**: ${v.vulnerability}\n`;
+  }
+
+  report += '\n## Recommended Actions\n\n';
+  report += '1. Review URGENT/HIGH vulnerabilities first\n';
+  report += '2. Run with `--fix --create-pr` for the top vulnerability to open a real MR\n';
+  report += '3. Schedule remaining MEDIUM/LOW items for a follow-up sprint\n';
+
+  return report;
+}
+
+module.exports = {
+  createAutomatedPR,
+  openMergeRequestForBranch,
+  createTrackingIssue,
+  postMergeRequestNote,
+  formatRiskReport,
+};