dependencyiq 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name/Organization]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dependencyiq",
+  "version": "2.0.0",
+  "description": "Multi-language dependency vulnerability agent: OSV-Scanner + GitLab Orbit blast-radius analysis + automated MRs",
+  "main": "src/agent.js",
+  "bin": {
+    "dependencyiq": "src/agent.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "start": "node src/agent.js",
+    "test": "jest --coverage --coverageReporters=cobertura --coverageReporters=text",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/",
+    "validate-config": "node scripts/validate-config.js",
+    "dev": "node -r dotenv/config src/agent.js"
+  },
+  "keywords": [
+    "security",
+    "vulnerabilities",
+    "dependencies",
+    "gitlab",
+    "orbit",
+    "ai",
+    "automation"
+  ],
+  "author": "DependencyIQ Team",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^11.0.0",
+    "dotenv": "^16.3.0",
+    "js-yaml": "^4.2.0",
+    "toml": "^4.1.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.50.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-plugin-import": "^2.28.1",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/\\.tmp"
+    ]
+  }
+}

package/src/activityFetcher.js

@@ -0,0 +1,66 @@
+/**
+ * Agent activity feed — what DependencyIQ has actually suggested and
+ * done, sourced live from GitLab's own API rather than a separate log
+ * file this project would have to keep in sync. Every issue/MR the
+ * agent suite creates (src/prGenerator.js) is tagged with the
+ * `dependencyiq` label specifically so this can query for them: a real
+ * GitLab object with a real timestamp and URL, not a parallel record
+ * that could drift from what actually happened.
+ */
+
+const axios = require('axios');
+const { getAuthHeaders, hasAnyToken } = require('./gitlabAuth');
+
+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');
+
+/**
+ * @param {string} projectId
+ * @param {number} limit - max items per type (issues, MRs) to fetch
+ * @returns {Promise<Object>} { available, items: [...], reason? }
+ */
+async function getRecentActivity(projectId, limit = 20) {
+  if (!hasAnyToken()) {
+    return { available: false, reason: 'No GITLAB_TOKEN or CI_JOB_TOKEN available — cannot query issues/MRs', items: [] };
+  }
+
+  try {
+    const [issuesRes, mrsRes] = await Promise.all([
+      axios.get(`${GITLAB_API}/projects/${projectId}/issues`, {
+        headers: getAuthHeaders(),
+        params: { labels: 'dependencyiq', order_by: 'created_at', sort: 'desc', per_page: limit },
+        timeout: 10000,
+      }),
+      axios.get(`${GITLAB_API}/projects/${projectId}/merge_requests`, {
+        headers: getAuthHeaders(),
+        params: { labels: 'dependencyiq', order_by: 'created_at', sort: 'desc', per_page: limit },
+        timeout: 10000,
+      }),
+    ]);
+
+    const issueItems = issuesRes.data.map(issue => ({
+      type: 'issue',
+      title: issue.title,
+      url: issue.web_url,
+      state: issue.state,
+      createdAt: issue.created_at,
+      labels: issue.labels,
+    }));
+
+    const mrItems = mrsRes.data.map(mr => ({
+      type: 'merge_request',
+      title: mr.title,
+      url: mr.web_url,
+      state: mr.state,
+      createdAt: mr.created_at,
+      labels: mr.labels,
+    }));
+
+    const items = [...issueItems, ...mrItems].sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+    return { available: true, items };
+  } catch (error) {
+    return { available: false, reason: `Failed to fetch activity: ${error.message}`, items: [] };
+  }
+}
+
+module.exports = { getRecentActivity };

package/src/agent.js

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+
+/**
+ * DependencyIQ - Multi-language dependency vulnerability agent
+ *
+ * Orchestrates: scan (OSV-Scanner, any ecosystem) → blast-radius analysis
+ * (GitLab Orbit) → risk scoring → optional fix + merge request.
+ *
+ * Deeper strategy/migration-plan reasoning is generated by templates here
+ * (no AI call) and is meant to be handed to the GitLab Duo "DependencyIQ"
+ * agent in Chat for interactive, model-backed follow-up — see
+ * .gitlab/duo/agents/dependencyiq-agent.yaml.
+ */
+
+require('dotenv').config();
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const { detectVulnerabilities, detectEcosystems } = require('./scanners/osvScanner');
+const { applyFix } = require('./scanners/ecosystemFixers');
+const { calculateRiskScore, sortByRisk, findUnusedDependencies } = require('./riskCalculator');
+const {
+  generateRefactoringAnalysis, generateMigrationTimeline, generateAnalysisSummary,
+  formatVulnerabilityCard, generatePRDescription, generateStructuredMigrationPlan, formatMigrationPlan
+} = require('./strategyGenerator');
+const { analyzeExposure } = require('./blastRadius');
+const { createAutomatedPR, postMergeRequestNote } = require('./prGenerator');
+const { diffNpmManifests, reviewChange, buildReviewNote, summarizeReview } = require('./mrReviewer');
+const { assessSupplyChainTrust } = require('./scanners/supplyChainTrustSignals');
+const { getLockfileEntry } = require('./scanners/dependencyTreeBuilder');
+const { buildFleetSnapshot, writeFleetSnapshot } = require('./fleetSnapshot');
+const { buildFleetReport } = require('./fleetAggregator');
+const { generateFleetDashboardHtml } = require('./fleetDashboardGenerator');
+const { buildExecutiveSummary, formatExecutiveSummary } = require('./executiveSummary');
+const { checkFreshness, chooseSecureTargetVersion } = require('./freshnessChecker');
+const { buildImpactReport, formatImpactReport } = require('./impactReport');
+const { generateDashboardHtml, generateScanFailedHtml } = require('./dashboardGenerator');
+const { getRecentActivity } = require('./activityFetcher');
+const { resolveDependencyChain } = require('./scanners/dependencyTreeBuilder');
+const { runEmergencyResponse, formatRollup } = require('./crossProjectFanOut');
+const { listDirectDependencies } = require('./scanners/manifestParser');
+const { loadAgentsConfig } = require('./configLoader');
+const { runPolicyCheck } = require('./freshnessPolicy');
+
+/**
+ * Run complete vulnerability analysis
+ */
+async function analyzeRepository(repoPath, projectId, options = {}) {
+  console.log('\n═══════════════════════════════════════════════════════════');
+  console.log('🛡️  DependencyIQ — Multi-language Dependency Vulnerability Agent');
+  console.log('🔗 GitLab Orbit + GitLab Duo Agent Platform');
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  try {
+    const ecosystems = detectEcosystems(repoPath);
+    console.log(`📦 Detected ecosystems: ${ecosystems.length ? ecosystems.join(', ') : 'none found'}`);
+
+    const vulnerabilities = await detectVulnerabilities(repoPath);
+
+    if (vulnerabilities.length === 0) {
+      console.log('✅ No vulnerabilities found!');
+      return { success: true, vulnerabilities: [] };
+    }
+
+    // AGENTS.md path hints (public_api_paths/test_paths) let a project's
+    // own layout drive exposure classification instead of generic
+    // heuristics — see configLoader/blastRadius.
+    const projectConfig = loadAgentsConfig(repoPath);
+    const pathHints = { public_api_paths: projectConfig.public_api_paths, test_paths: projectConfig.test_paths };
+
+    console.log('\n📊 Analyzing blast radius with GitLab Orbit...');
+    for (const vuln of vulnerabilities) {
+      const exposure = await analyzeExposure(projectId, vuln.package, pathHints);
+
+      vuln.riskScore = calculateRiskScore(vuln, {
+        affectedFilesCount: exposure.affectedFilesCount,
+        usageCount: exposure.affectedFilesCount,
+        isInPublicAPI: exposure.isInPublicAPI,
+        isInBusinessLogic: !exposure.isInTests,
+        testCoverage: exposure.isInTests ? 0.8 : 0.3,
+        exposureDataSource: exposure.source,
+      });
+
+      vuln.affectedFiles = exposure.affectedFiles;
+      vuln.exposure = exposure;
+      vuln.recommendation = vuln.riskScore.recommendation;
+      vuln.dependencyChain = resolveDependencyChain(repoPath, vuln.ecosystem, vuln.package);
+    }
+
+    console.log('\n🎯 Ranking by actual risk...');
+    const ranked = sortByRisk(vulnerabilities);
+
+    for (let i = 0; i < Math.min(5, ranked.length); i += 1) {
+      const v = ranked[i];
+      console.log(`   ${i + 1}. [${v.ecosystem}] ${v.package}: Risk ${v.riskScore.score}/100 (${v.riskScore.priority})`);
+    }
+
+    const unused = findUnusedDependencies(ranked);
+    if (unused.length > 0) {
+      console.log('\n🧹 Cleanup opportunities (Orbit found zero importers — recommend removing, not patching):');
+      for (const v of unused) {
+        console.log(`   - [${v.ecosystem}] ${v.package} (${v.id})`);
+      }
+    }
+
+    console.log('\n📋 Generating analysis summary...');
+    const summary = generateAnalysisSummary(ranked);
+    console.log('\n' + summary);
+
+    const execSummary = buildExecutiveSummary(ranked);
+    console.log('\n' + formatExecutiveSummary(execSummary));
+
+    if (options.detailed) {
+      console.log('\n📌 DETAILED VULNERABILITY CARDS:\n');
+      for (let i = 0; i < Math.min(3, ranked.length); i += 1) {
+        console.log(formatVulnerabilityCard(ranked[i], i + 1));
+      }
+    }
+
+    if (ranked.length > 0 && options.strategies) {
+      console.log('\n═══════════════════════════════════════════════════════════');
+      console.log('💡 Ask GitLab Duo Chat (DependencyIQ agent) to expand this:');
+      console.log('═══════════════════════════════════════════════════════════\n');
+
+      const topVuln = ranked[0];
+      console.log(generateRefactoringAnalysis(topVuln, { affectedFiles: topVuln.affectedFiles }));
+    }
+
+    if (options.plan) {
+      console.log('\n═══════════════════════════════════════════════════════════');
+      console.log('📅 MIGRATION TIMELINE');
+      console.log('═══════════════════════════════════════════════════════════\n');
+      console.log(generateMigrationTimeline(ranked));
+    }
+
+    let impactReport = null;
+    let migrationPlan = null;
+    if (ranked.length > 0 && options.impact) {
+      console.log('\n═══════════════════════════════════════════════════════════');
+      console.log('🔬 UPGRADE IMPACT REPORT');
+      console.log('═══════════════════════════════════════════════════════════\n');
+
+      const topVuln = ranked[0];
+      const freshness = await checkFreshness(topVuln.ecosystem, topVuln.package, topVuln.currentVersion)
+        .catch(() => ({ available: false, reason: 'lookup failed' }));
+
+      impactReport = buildImpactReport(topVuln, freshness);
+      migrationPlan = generateStructuredMigrationPlan(impactReport);
+
+      console.log(formatImpactReport(impactReport));
+      console.log(formatMigrationPlan(migrationPlan));
+    }
+
+    // Fix + PR (real, not simulated): edits the manifest locally, then
+    // commits it and opens an MR via the GitLab API.
+    let fixResult = null;
+    let prResult = null;
+    if (ranked.length > 0 && (options.fix || options.createPR)) {
+      const topVuln = ranked[0];
+
+      // "Which version?" decision (the part OSV alone can't answer): for an
+      // upgrade, don't blindly take OSV's minimum fixed version — pick the
+      // least-disruptive secure version (>= floor, settled, staying within
+      // the current major where possible). Preserve the OSV floor so the
+      // transitive-override path still pins against the security minimum.
+      if (topVuln.recommendation !== 'remove' && topVuln.fixedVersion && topVuln.fixedVersion !== 'unknown') {
+        const target = await chooseSecureTargetVersion(topVuln.ecosystem, topVuln.package, topVuln.currentVersion, topVuln.fixedVersion)
+          .catch(() => ({ available: false }));
+        topVuln.osvFloorVersion = topVuln.fixedVersion;
+        topVuln.versionSelection = target;
+        if (target.available && target.recommendedVersion !== topVuln.fixedVersion) {
+          console.log(`   🎯 Target version: ${topVuln.fixedVersion} (OSV floor) → ${target.recommendedVersion} — ${target.rationale}`);
+          topVuln.fixedVersion = target.recommendedVersion;
+        }
+        if (target.available && target.crossesMajor) {
+          console.log('   ⚠️  This fix crosses a major version — review for breaking changes.');
+        }
+      }
+
+      console.log(`\n🔧 Applying fix for ${topVuln.package}...`);
+      fixResult = applyFix(repoPath, topVuln);
+      if (fixResult.action === 'override') {
+        console.log(`   🔗 ${topVuln.package} is transitive — forced a secure version via package.json "overrides".`);
+      }
+
+      if (fixResult.applied) {
+        console.log(`   ✓ Updated ${fixResult.filePath}`);
+        if (fixResult.followUp) console.log(`   ℹ️  Follow-up needed: ${fixResult.followUp}`);
+      } else {
+        console.log(`   ⚠️  Could not auto-apply fix: ${fixResult.warning}`);
+      }
+
+      if (options.createPR && projectId && fixResult.applied) {
+        const description = generatePRDescription(topVuln, fixResult);
+        prResult = await createAutomatedPR(projectId, repoPath, topVuln, fixResult, description);
+      } else if (options.createPR && !fixResult.applied) {
+        console.log('   ⚠️  Skipping PR creation: no fix was applied to commit');
+      }
+    }
+
+    console.log('\n✅ Analysis complete!\n');
+
+    return {
+      success: true,
+      vulnerabilities: ranked,
+      summary,
+      fixResult,
+      prResult,
+      impactReport,
+      migrationPlan,
+    };
+  } catch (error) {
+    console.error('\n❌ Error during analysis:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * CLI Interface
+ */
+async function main() {
+  const program = new Command();
+
+  program
+    .name('dependencyiq')
+    .description('Multi-language dependency vulnerability agent (GitLab Orbit + Duo)')
+    .version('2.0.0');
+
+  program
+    .command('analyze <repoPath>')
+    .option('-p, --project-id <id>', 'GitLab project ID')
+    .option('--strategies', 'Print refactoring strategy analysis for the top vulnerability')
+    .option('--plan', 'Generate migration timeline')
+    .option('--impact', 'Generate an Upgrade Impact Report + structured migration plan for the top vulnerability')
+    .option('--fix', 'Apply the fix to the top vulnerability locally')
+    .option('--create-pr', 'Apply the fix, commit it, and open a merge request')
+    .option('--detailed', 'Show detailed vulnerability cards')
+    .option('--json-out <file>', 'Write a compact JSON snapshot (for Fleet Dashboard aggregation) to this path')
+    .description('Analyze repository for vulnerabilities')
+    .action(async (repoPath, options) => {
+      const projectId = options.projectId || process.env.GITLAB_PROJECT_ID;
+      const fullPath = path.resolve(repoPath);
+
+      const result = await analyzeRepository(fullPath, projectId, {
+        strategies: options.strategies ?? true,
+        plan: options.plan || false,
+        impact: options.impact || false,
+        fix: options.fix || false,
+        createPR: options.createPr || false,
+        detailed: options.detailed || false,
+      });
+
+      // Only write a snapshot on a real, successful scan — a failed scan
+      // must never produce an artifact that the Fleet Dashboard could
+      // misread as "this project ran cleanly with zero findings."
+      if (options.jsonOut && result.success) {
+        const snapshot = buildFleetSnapshot(result, {
+          projectId,
+          projectPath: process.env.CI_PROJECT_PATH || null,
+          ecosystems: detectEcosystems(fullPath),
+        });
+        writeFleetSnapshot(snapshot, options.jsonOut);
+        console.log(`\n📄 Fleet snapshot written to ${options.jsonOut}`);
+      }
+
+      if (!result.success) process.exit(1);
+    });
+
+  program
+    .command('emergency <groupId> <packageName>')
+    .option('-i, --vulnerability-id <id>', 'CVE/advisory ID for this incident', 'UNSPECIFIED')
+    .option('-e, --ecosystem <ecosystem>', 'npm | PyPI | Go | Maven', 'npm')
+    .option('-f, --fixed-version <version>', 'Version to upgrade direct dependents to')
+    .option('--remove', 'Treat this as a removal (e.g. the package itself is compromised, not just outdated)')
+    .option('--fix-all', 'Open real merge requests for every directly-affected project, not just issues')
+    .option('--dry-run', 'Query and classify only — create nothing', false)
+    .description('Org-wide emergency response: find every project in a group that imports a compromised package, and open issues/MRs across all of them')
+    .action(async (groupId, packageName, options) => {
+      const vulnerability = {
+        package: packageName,
+        ecosystem: options.ecosystem,
+        id: options.vulnerabilityId,
+        fixedVersion: options.fixedVersion || 'unknown',
+        recommendation: options.remove ? 'remove' : 'upgrade',
+        vulnerability: `Supply chain incident: ${packageName}`,
+      };
+
+      const rollup = await runEmergencyResponse(groupId, vulnerability, {
+        dryRun: options.dryRun,
+        fixDirect: options.fixAll || false,
+      });
+
+      console.log(formatRollup(rollup));
+    });
+
+  program
+    .command('freshness <repoPath>')
+    .description('Check every direct dependency (vulnerable or not) against AGENTS.md freshness policy — the tech-debt-prevention check, separate from CVE scanning')
+    .action(async (repoPath) => {
+      const fullPath = path.resolve(repoPath);
+      const config = loadAgentsConfig(fullPath);
+      console.log(`\n📐 Freshness policy loaded from: ${config.source}`);
+      if (config.freshness_policy.max_minor_versions_behind == null && config.freshness_policy.max_days_behind == null) {
+        console.log('   ⚠️  No freshness_policy thresholds set in AGENTS.md — nothing will be flagged as a violation, only reported.');
+      }
+
+      const dependencies = listDirectDependencies(fullPath);
+      console.log(`📦 Found ${dependencies.length} direct dependencies across all ecosystems\n`);
+
+      const withFreshness = [];
+      for (const dependency of dependencies) {
+        const freshness = await checkFreshness(dependency.ecosystem, dependency.package, dependency.currentVersion)
+          .catch(() => ({ available: false }));
+        withFreshness.push({ dependency, freshness });
+        if (freshness.available && freshness.currentVersion !== freshness.latestVersion) {
+          console.log(`   [${dependency.ecosystem}] ${dependency.package}: ${dependency.currentVersion} → ${freshness.latestVersion} (freshness ${freshness.freshnessScore ?? '?'}/100)`);
+        }
+      }
+
+      const policyResult = runPolicyCheck(withFreshness, config);
+      console.log(`\n✅ Compliant: ${policyResult.compliantCount}  |  ⚠️  Violations: ${policyResult.violationCount}\n`);
+      for (const v of policyResult.violations) {
+        console.log(`   🔴 ${v.package} (${v.ecosystem})`);
+        v.violations.forEach(msg => console.log(`      - ${msg}`));
+      }
+    });
+
+  program
+    .command('dashboard <repoPath>')
+    .option('-p, --project-id <id>', 'GitLab project ID')
+    .option('-o, --out <dir>', 'Output directory for the static site', 'public')
+    .description('Generate a static HTML dashboard of the analysis (publishable via GitLab Pages — no backend)')
+    .action(async (repoPath, options) => {
+      const projectId = options.projectId || process.env.GITLAB_PROJECT_ID;
+      const fullPath = path.resolve(repoPath);
+      const meta = {
+        projectName: process.env.CI_PROJECT_NAME || path.basename(fullPath),
+        generatedAt: new Date().toISOString(),
+        projectPath: process.env.CI_PROJECT_PATH,
+        serverUrl: process.env.CI_SERVER_URL,
+      };
+      const outDir = path.resolve(options.out);
+      fs.mkdirSync(outDir, { recursive: true });
+
+      const result = await analyzeRepository(fullPath, projectId, {
+        strategies: false, plan: false, impact: false, fix: false, createPR: false, detailed: false,
+      });
+
+      if (!result.success) {
+        // Still publish a page — an honest "scan failed" page, never a
+        // silent "no vulnerabilities found" one — and still fail the CI
+        // job (exit 1) so the pipeline visibly flags it red.
+        fs.writeFileSync(path.join(outDir, 'index.html'), generateScanFailedHtml(result.error, meta));
+        console.log(`\n📄 Scan-failed dashboard written to ${path.join(outDir, 'index.html')}`);
+        process.exit(1);
+      }
+
+      const activity = await getRecentActivity(projectId).catch(error => ({ available: false, reason: error.message, items: [] }));
+      const html = generateDashboardHtml(result, meta, activity);
+      fs.writeFileSync(path.join(outDir, 'index.html'), html);
+      console.log(`\n📄 Dashboard written to ${path.join(outDir, 'index.html')}`);
+    });
+
+  program
+    .command('fleet-dashboard <groupId>')
+    .option('-o, --out <dir>', 'Output directory for the static site', 'public/fleet')
+    .option('-n, --name <groupName>', 'Display name for the group (cosmetic only)')
+    .description('Generate a cross-project static dashboard for every project in a GitLab group, aggregated from each project\'s own analyze_vulnerabilities CI artifact (requires GITLAB_TOKEN)')
+    .action(async (groupId, options) => {
+      const outDir = path.resolve(options.out);
+      fs.mkdirSync(outDir, { recursive: true });
+
+      console.log(`\n🚀 Building Fleet Dashboard for group ${groupId}...`);
+      const report = await buildFleetReport(groupId);
+
+      if (!report.available) {
+        console.warn(`   ⚠️  ${report.reason}`);
+      } else {
+        console.log(`   ✓ ${report.rollup.onboardedCount}/${report.rollup.totalProjects} project(s) onboarded, ${report.rollup.totalFindings} total finding(s)`);
+      }
+
+      const html = generateFleetDashboardHtml(report, { groupId, groupName: options.name });
+      fs.writeFileSync(path.join(outDir, 'index.html'), html);
+      console.log(`\n📄 Fleet dashboard written to ${path.join(outDir, 'index.html')}`);
+
+      if (!report.available) process.exit(1);
+    });
+
+  program
+    .command('review-mr <repoPath>')
+    .option('-p, --project-id <id>', 'GitLab project ID')
+    .option('-b, --base <ref>', 'Git ref of the MR target/base to diff against (default: CI_MERGE_REQUEST_DIFF_BASE_SHA or origin/HEAD)')
+    .option('--post', 'Post the review as a note on the merge request (needs CI_MERGE_REQUEST_IID)')
+    .description('Safety-review an incoming dependency MR: diff the manifest, query Orbit for blast radius, and emit an approve/review/block verdict')
+    .action(async (repoPath, options) => {
+      const projectId = options.projectId || process.env.CI_PROJECT_ID || process.env.GITLAB_PROJECT_ID;
+      const fullPath = path.resolve(repoPath);
+      const manifestPath = path.join(fullPath, 'package.json');
+
+      if (!fs.existsSync(manifestPath)) {
+        console.log('No package.json found — MR Safety Review currently covers npm manifests.');
+        return;
+      }
+      const headContent = fs.readFileSync(manifestPath, 'utf-8');
+
+      // Base manifest = the MR target. Prefer GitLab's merge-base SHA in CI,
+      // else an explicit --base, else origin/HEAD. If we can't read it, treat
+      // base as empty (everything reads as "added") rather than crashing.
+      const baseRef = options.base || process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA
+        || (process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME ? `origin/${process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME}` : 'origin/HEAD');
+      let baseContent = '{}';
+      try {
+        baseContent = execFileSync('git', ['show', `${baseRef}:package.json`], { cwd: fullPath, encoding: 'utf-8' });
+      } catch (error) {
+        console.warn(`   ⚠️  Could not read base package.json at ${baseRef} (${error.message}) — reviewing all current dependencies as new.`);
+      }
+
+      const changes = diffNpmManifests(baseContent, headContent);
+      if (changes.length === 0) {
+        console.log('✅ No dependency changes in this MR — nothing to review.');
+        return;
+      }
+
+      console.log(`\n🛡️  MR Safety Review: ${changes.length} dependency change(s)\n`);
+      const reviews = [];
+      const trustByPackage = {};
+      for (const change of changes) {
+        // Removal/override don't need exposure to verdict; others query Orbit.
+        const needsExposure = change.kind === 'changed' || change.kind === 'added';
+        const exposure = needsExposure
+          ? await analyzeExposure(projectId, change.package).catch(() => ({ source: 'unavailable' }))
+          : { source: 'unavailable' };
+        reviews.push(reviewChange(change, exposure));
+
+        // Supply-Chain Trust signals: a separate, never-blended dimension
+        // (see scanners/supplyChainTrustSignals.js) — only meaningful for
+        // a package whose code is actually changing.
+        if (needsExposure) {
+          const lockEntry = getLockfileEntry(fullPath, change.package);
+          trustByPackage[change.package] = await assessSupplyChainTrust({
+            packageName: change.package,
+            ecosystem: 'npm',
+            targetVersion: change.toVersion,
+            previousVersion: change.kind === 'changed' ? change.fromVersion : undefined,
+            resolvedUrl: lockEntry?.resolved,
+          }).catch(() => null);
+        }
+      }
+
+      const note = buildReviewNote(reviews, trustByPackage);
+      const summary = summarizeReview(reviews, trustByPackage);
+      console.log(note);
+
+      const mrIid = process.env.CI_MERGE_REQUEST_IID;
+      if (options.post && projectId && mrIid) {
+        const posted = await postMergeRequestNote(projectId, mrIid, note).catch(e => ({ success: false, reason: e.message }));
+        console.log(posted.success ? `\n📝 Posted review to MR !${mrIid}` : `\n⚠️  Could not post review note: ${posted.reason}`);
+      }
+
+      // Exit non-zero on a blocking verdict so the CI job visibly fails —
+      // a real gate, not just a comment.
+      if (summary.overall === 'blocked') process.exit(1);
+    });
+
+  program
+    .command('scan <repoPath>')
+    .description('Scan repository for vulnerabilities only (no Orbit/risk scoring)')
+    .action(async (repoPath) => {
+      const vulns = await detectVulnerabilities(path.resolve(repoPath));
+      console.log(JSON.stringify(vulns, null, 2));
+    });
+
+  program
+    .command('quick <repoPath>')
+    .option('-p, --project-id <id>', 'GitLab project ID')
+    .description('Quick analysis (just risk scores, no detailed output)')
+    .action(async (repoPath, options) => {
+      const projectId = options.projectId || process.env.GITLAB_PROJECT_ID;
+      const result = await analyzeRepository(path.resolve(repoPath), projectId, {
+        strategies: false,
+        plan: false,
+        fix: false,
+        createPR: false,
+        detailed: false,
+      });
+
+      if (!result.success) process.exit(1);
+    });
+
+  program.parse(process.argv);
+
+  if (process.argv.length < 3) {
+    program.help();
+  }
+}
+
+module.exports = { analyzeRepository };
+
+if (require.main === module) {
+  main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}