dependencyiq 2.0.0

package/src/strategyGenerator.js

@@ -0,0 +1,384 @@
+/**
+ * Strategy Generator (GitLab-native)
+ * Generates analysis summaries and instructions for GitLab Duo Agentic Chat
+ * Uses GitLab's built-in AI models via the Agent Platform
+ */
+
+/**
+ * Generate refactoring strategy analysis for GitLab Chat
+ * @param {Object} vulnerability - Vulnerability object
+ * @param {Object} codeContext - Code usage information
+ * @returns {string} Analysis prompt for GitLab Chat
+ */
+function generateRefactoringAnalysis(vulnerability, codeContext = {}) {
+  const context = {
+    affectedFiles: [],
+    usageExamples: [],
+    ...codeContext
+  };
+
+  return `
+# Refactoring Analysis: ${vulnerability.package}
+
+## Vulnerability Details
+- **Package**: ${vulnerability.package}
+- **Current**: ${vulnerability.currentVersion}
+- **Target**: ${vulnerability.fixedVersion}
+- **Severity**: ${vulnerability.severity} (CVSS ${vulnerability.cvss})
+- **Issue**: ${vulnerability.vulnerability}
+
+## Code Impact
+- **Files affected**: ${context.affectedFiles?.length || 1}
+${context.affectedFiles?.map(f => `  - ${f.path || f}`).join('\n') || '  - no Orbit exposure data available'}
+
+## Usage Example
+\`\`\`javascript
+${context.usageExamples?.[0] || 'const merged = _.merge({}, defaults, userInput);'}
+\`\`\`
+
+## Task for GitLab Duo Chat
+
+Generate **3 upgrade strategies** ranked by safety vs speed:
+
+### Strategy 1: Safest Approach
+- What code changes are needed?
+- Why is this the safest?
+- What testing is required?
+- Estimated time to implement?
+- Best for: Large teams, critical services?
+
+### Strategy 2: Recommended Approach (Balanced)
+- What changes would you recommend?
+- Why balance safety and speed?
+- What's the testing strategy?
+- Estimated time?
+- Best for: Most development teams?
+
+### Strategy 3: Fastest Approach
+- What's the minimal viable change?
+- What risks exist with this approach?
+- How to mitigate those risks?
+- Estimated time?
+- Best for: Non-critical services, internal tools?
+
+For each strategy, provide:
+- Complete code examples
+- Rationale for the approach
+- Success criteria
+- Potential gotchas
+`;
+}
+
+/**
+ * Generate migration timeline analysis for GitLab Chat
+ * @param {Array} vulnerabilities - Vulnerabilities with risk scores
+ * @returns {string} Timeline planning prompt
+ */
+function generateMigrationTimeline(vulnerabilities = []) {
+  const vulnList = vulnerabilities
+    .slice(0, 5)
+    .map((v, i) => `${i + 1}. **${v.package}** (Risk ${v.riskScore?.score || '?'}/100, ${v.severity})\n   - Issue: ${v.vulnerability}`)
+    .join('\n');
+
+  return `
+# Vulnerability Migration Timeline
+
+## Vulnerabilities to Address (Priority Order)
+${vulnList}
+
+## Task: Create Phased Migration Plan
+
+### Phase 1: This Week (Most Urgent)
+- Which vulnerabilities should we fix first?
+- Why prioritize these?
+- Estimated team effort?
+- Testing and QA strategy?
+- Deployment approach (direct, canary, feature flag)?
+- What's the rollback procedure?
+
+### Phase 2: Next Week (High Priority)
+- Next batch of vulnerabilities?
+- Expected effort hours?
+- Testing approach?
+- Deployment strategy?
+- Any dependencies between Phase 1 & 2?
+
+### Phase 3: Following Week+ (Medium/Low Priority)
+- Remaining vulnerabilities to fix?
+- Nice-to-have improvements?
+- Documentation updates needed?
+- Estimated total effort?
+
+## For All Phases
+
+- Why prioritize in this specific order?
+- What risks if we delay any phase?
+- How do we measure success?
+- Team communication plan?
+- How to track completion?
+
+Provide realistic estimates based on:
+- Team size and velocity
+- Complexity of each change
+- Testing requirements
+- Deployment procedures
+`;
+}
+
+/**
+ * Generate executive summary of vulnerability analysis
+ * @param {Array} vulnerabilities - Analyzed vulnerabilities
+ * @returns {string} Summary for quick review
+ */
+function generateAnalysisSummary(vulnerabilities = []) {
+  if (!vulnerabilities || vulnerabilities.length === 0) {
+    return '✅ No vulnerabilities found in this project.';
+  }
+
+  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');
+
+  let summary = `
+# Vulnerability Analysis Summary
+
+## Overview
+- **Total Found**: ${vulnerabilities.length}
+- 🔴 **URGENT** (Risk 80-100): ${urgent.length}
+- 🟠 **HIGH** (Risk 50-79): ${high.length}
+- 🟡 **MEDIUM** (Risk 20-49): ${medium.length}
+
+## Top 3 Priorities
+
+${vulnerabilities.slice(0, 3).map((v, i) => `
+### ${i + 1}. ${v.package}
+- **Risk Score**: ${v.riskScore?.score}/100 (${v.riskScore?.priority})
+- **Issue**: ${v.vulnerability}
+- **Severity**: ${v.severity} (CVSS ${v.cvss})
+- **Files Affected**: ${v.affectedFiles?.length || 1}
+${v.affectedFiles?.slice(0, 2).map(f => `  - ${f.path || f}`).join('\n') || '  - internal usage'}
+`).join('\n')}
+
+## Recommendation
+
+✅ **Focus on URGENT vulnerabilities first** (${urgent.length} found)
+- These have actual code exposure in your project
+- Not just generic CVSS scores—real risk to your systems
+
+🎯 **Expect** to fix all urgents + highs in about 1-2 weeks
+  - Phase 1 (this week): URGENT items
+  - Phase 2 (next week): HIGH items
+  - Phase 3 (ongoing): MEDIUM + LOW
+
+💡 **Next Step**: Ask GitLab Duo Chat for specific upgrade strategies
+  - It will analyze your code and suggest safe refactoring approaches
+  - It can generate migration plans and timelines
+  - Ask it to create a draft MR for Phase 1
+`;
+
+  return summary;
+}
+
+/**
+ * Format a vulnerability for human-readable display
+ * @param {Object} vuln - Vulnerability object
+ * @param {number} index - Position in list
+ * @returns {string} Formatted display string
+ */
+function formatVulnerabilityCard(vuln, index = 1) {
+  const icon = vuln.riskScore?.priority === 'URGENT' ? '🔴'
+             : vuln.riskScore?.priority === 'HIGH' ? '🟠'
+             : vuln.riskScore?.priority === 'MEDIUM' ? '🟡' : '🟢';
+
+  return `
+${icon} **${index}. ${vuln.package} → ${vuln.fixedVersion}**
+
+| Field | Value |
+|-------|-------|
+| **Current** | ${vuln.currentVersion} |
+| **Issue** | ${vuln.vulnerability} |
+| **Severity** | ${vuln.severity} (CVSS ${vuln.cvss}) |
+| **Your Risk Score** | ${vuln.riskScore?.score || '?'}/100 (${vuln.riskScore?.priority}) |
+| **Files Affected** | ${vuln.affectedFiles?.length || 1} |
+| **Exposed to API?** | ${vuln.riskScore?.isInPublicAPI ? '✅ Yes' : '❌ No'} |
+| **Effort to Fix** | ${vuln.riskScore?.effortMinutes ? Math.ceil(vuln.riskScore.effortMinutes / 60) + 'h' : '?'} |
+`;
+}
+
+/**
+ * Generate a merge request description (deterministic template — no AI
+ * call). Deeper strategy reasoning is available interactively by asking
+ * the DependencyIQ GitLab Duo agent in Chat, which uses GitLab's managed
+ * model rather than an external API key.
+ * @param {Object} vulnerability - vulnerability being fixed
+ * @param {Object} fixResult - result from ecosystemFixers.applyFix
+ * @returns {string} PR description markdown
+ */
+function generatePRDescription(vulnerability, fixResult = {}) {
+  if (fixResult.action === 'remove') {
+    return `# Cleanup: Remove unused dependency ${vulnerability.package}
+
+## Summary
+\`${vulnerability.package}\` (${vulnerability.ecosystem}) has a known vulnerability — **${vulnerability.vulnerability}** (${vulnerability.id}) — but **GitLab Orbit confirms zero files in this project import it**. Patching a CVE in code nothing uses doesn't reduce real risk, so this removes the dependency entirely instead of bumping its version.
+
+- **Vulnerability that prompted this**: ${vulnerability.id} (${vulnerability.severity}, CVSS ${vulnerability.cvss})
+- **Exposure data**: GitLab Orbit blast-radius query — 0 importers found
+- **Why removal instead of upgrade**: nothing to break by removing it; upgrading would just carry a version of a package you don't use
+
+## Changes
+- Removed \`${vulnerability.package}\` from \`${fixResult.filePath || 'manifest'}\`.
+${fixResult.followUp ? `- **Follow-up required**: run \`${fixResult.followUp}\` to refresh the lockfile before merging.` : ''}
+${fixResult.warning ? `- ⚠️ ${fixResult.warning}` : ''}
+
+---
+Generated by DependencyIQ using a GitLab Orbit blast-radius query — not a guess based on CVSS alone.
+`;
+  }
+
+  const sel = vulnerability.versionSelection;
+  const floor = vulnerability.osvFloorVersion;
+  const isOverride = fixResult.action === 'override';
+
+  // "Which version?" section — only when a real decision was made (a smart
+  // target above the OSV floor, or a major-crossing flag). Shows the
+  // reasoning instead of silently taking OSV's minimum.
+  let versionSection = '';
+  if (sel?.available && (sel.recommendedVersion !== floor || sel.crossesMajor)) {
+    versionSection = `
+
+## Version selection
+- **OSV security floor**: ${floor} (minimum version that patches the advisory)
+- **Chosen target**: ${vulnerability.fixedVersion}${sel.settled ? ` — settled (${sel.ageDays}d since release)` : ' — note: recently published'}
+- **Reasoning**: ${sel.rationale}${sel.crossesMajor ? '\n- ⚠️ **Crosses a major version** — review for breaking changes before merging.' : ''}`;
+  }
+
+  const changesSection = isOverride
+    ? `## Changes
+- ${vulnerability.package} is a **transitive** dependency (pulled in via ${vulnerability.dependencyChain?.chain ? vulnerability.dependencyChain.chain.join(' → ') : 'another dependency'}), so there's no direct version line to bump.
+- Added an \`overrides\` entry in \`${fixResult.filePath || 'package.json'}\` forcing ${vulnerability.package} to \`>=${floor || vulnerability.fixedVersion}\` (the patched floor) regardless of what the parent declares — the standard fix for the Log4j/Axios class of transitive incident.
+${fixResult.followUp ? `- **Follow-up required**: run \`${fixResult.followUp}\`.` : ''}
+${fixResult.warning ? `- ⚠️ ${fixResult.warning}` : ''}`
+    : `## Changes
+- Updated \`${fixResult.filePath || 'manifest'}\` to pin ${vulnerability.package} to ${vulnerability.fixedVersion}.
+${fixResult.followUp ? `- **Follow-up required**: run \`${fixResult.followUp}\` to refresh the lockfile before merging.` : ''}
+${fixResult.warning ? `- ⚠️ ${fixResult.warning}` : ''}`;
+
+  return `# Security Update: ${vulnerability.package}
+
+## Summary
+Fixes **${vulnerability.vulnerability}** (${vulnerability.id}) in ${vulnerability.package} (${vulnerability.ecosystem})${isOverride ? ' — a transitive dependency, fixed via an npm override' : ''}
+
+- **Current**: ${vulnerability.currentVersion}
+- **Target**: ${isOverride ? `>=${floor || vulnerability.fixedVersion} (transitive override)` : vulnerability.fixedVersion}
+- **Severity**: ${vulnerability.severity} (CVSS ${vulnerability.cvss})
+- **Risk Score**: ${vulnerability.riskScore?.score ?? 'N/A'}/100 (${vulnerability.riskScore?.priority ?? 'unscored'})
+- **Exposure data**: ${vulnerability.riskScore?.exposureDataSource === 'orbit' ? 'GitLab Orbit blast-radius query' : 'unavailable — Orbit not enabled/reachable for this project'}${versionSection}
+
+${changesSection}
+
+## References
+${(vulnerability.references || []).slice(0, 3).map(r => `- ${r}`).join('\n') || '- ' + vulnerability.cveLink}
+
+---
+Generated by DependencyIQ. Ask the DependencyIQ agent in GitLab Duo Chat for upgrade strategies or a phased migration plan for the remaining findings.
+`;
+}
+
+/**
+ * Generate a structured, ordered migration plan for one upgrade, using
+ * the impact report's real affected-file count and effort estimate
+ * rather than a generic template. Deterministic — no AI call.
+ * @param {Object} impactReport - result from impactReport.buildImpactReport
+ * @returns {Object} { steps: [{order, title, detail}], estimatedHours }
+ */
+function generateStructuredMigrationPlan(impactReport) {
+  const steps = [];
+  let order = 0;
+  const nextOrder = () => { order += 1; return order; };
+  const { simulation } = impactReport;
+
+  if (simulation) {
+    steps.push({
+      order: nextOrder(),
+      title: 'Review upgrade impact simulation',
+      detail: `${simulation.difficulty} difficulty; ${simulation.relationship} dependency; ${simulation.affectedServicesCount} affected service area(s). Automation mode: ${simulation.automationMode}.`,
+    });
+  }
+
+  if (impactReport.affectedFilesCount > 0) {
+    steps.push({
+      order: nextOrder(),
+      title: 'Review affected call sites',
+      detail: `${impactReport.affectedFilesCount} file(s) import ${impactReport.package} — read each one to confirm how it's used before changing the version.`,
+    });
+  }
+
+  if (impactReport.likelyBreaking) {
+    steps.push({
+      order: nextOrder(),
+      title: 'Check for breaking changes',
+      detail: `${impactReport.breakingChangeReasoning} Read the package's changelog/release notes for ${impactReport.from} → ${impactReport.to} before touching code.`,
+    });
+    steps.push({
+      order: nextOrder(),
+      title: 'Update call sites for the new major version',
+      detail: 'Adjust any usages flagged in the previous step to match the new API surface, guided by the changelog, not a guess.',
+    });
+  }
+
+  steps.push({
+    order: nextOrder(),
+    title: `Bump ${impactReport.package} to ${impactReport.to}`,
+    detail: 'Update the manifest (already done automatically if this came from `--fix`) and refresh the lockfile.',
+  });
+
+  steps.push({
+    order: nextOrder(),
+    title: 'Run the test suite',
+    detail: simulation?.safetyChecks?.length
+      ? `Confirm nothing regressed before opening or merging the MR. Required checks: ${simulation.safetyChecks.join('; ')}.`
+      : 'Confirm nothing regressed before opening or merging the MR.',
+  });
+
+  if (impactReport.affectedFilesCount === 0) {
+    steps.unshift({
+      order: 0,
+      title: 'Confirm this dependency is actually unused',
+      detail: 'Orbit found zero importers — consider removing the dependency entirely instead of running this plan (see riskScore.recommendation).',
+    });
+  }
+
+  return {
+    package: impactReport.package,
+    from: impactReport.from,
+    to: impactReport.to,
+    steps,
+    estimatedHours: impactReport.estimatedEffort.hours,
+  };
+}
+
+/**
+ * Render a structured migration plan as markdown.
+ */
+function formatMigrationPlan(plan) {
+  const stepLines = plan.steps
+    .map(s => `${s.order}. **${s.title}**\n   ${s.detail}`)
+    .join('\n\n');
+
+  return `## Migration Plan: ${plan.package} ${plan.from} → ${plan.to}
+
+${stepLines}
+
+**Estimated effort**: ~${plan.estimatedHours}h
+`;
+}
+
+module.exports = {
+  generateRefactoringAnalysis,
+  generateMigrationTimeline,
+  generateAnalysisSummary,
+  formatVulnerabilityCard,
+  generatePRDescription,
+  generateStructuredMigrationPlan,
+  formatMigrationPlan
+};

package/src/upgradeImpactSimulator.js

@@ -0,0 +1,241 @@
+/**
+ * Upgrade Impact Simulator.
+ *
+ * Turns the raw impact report into the engineering question leaders ask:
+ * "How painful will this remediation be, and what work should happen
+ * before the MR is merged?"
+ *
+ * This is evidence-based, not an API-diff oracle. It uses Orbit-derived
+ * affected files, dependency-chain data, exposure categories, and semver
+ * distance to identify likely change areas, blockers, checks, and a
+ * phased migration plan.
+ */
+
+const SERVICE_ROOTS = ['services', 'apps', 'packages', 'workspaces'];
+
+function filePathOf(file) {
+  return String(file?.path || file || '');
+}
+
+function inferServiceName(filePath) {
+  const normalized = filePath.replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = normalized.split('/').filter(Boolean);
+  if (parts.length >= 2 && SERVICE_ROOTS.includes(parts[0])) {
+    return `${parts[0]}/${parts[1]}`;
+  }
+  return 'current repository';
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function hasPathMatch(paths, patterns) {
+  return paths.some(p => patterns.some(pattern => p.toLowerCase().includes(pattern)));
+}
+
+function dependencyRelationship(vulnerability) {
+  if (vulnerability.recommendation === 'remove') return 'unused';
+  const chain = vulnerability.dependencyChain;
+  if (!chain?.available) return 'unknown';
+  return chain.isDirect ? 'direct' : 'transitive';
+}
+
+function difficultyFor({
+  affectedFilesCount,
+  affectedServicesCount,
+  likelyBreaking,
+  relationship,
+  touchesPublicApi,
+  touchesAuth,
+  touchesConfig,
+}) {
+  if (relationship === 'unused') return 'low';
+  if (likelyBreaking && (affectedFilesCount >= 30 || affectedServicesCount >= 5)) return 'critical';
+  if (touchesPublicApi && (affectedServicesCount >= 2 || likelyBreaking)) return 'high';
+  if (touchesAuth && touchesConfig && affectedServicesCount >= 2) return 'high';
+  if (likelyBreaking || affectedFilesCount >= 15 || affectedServicesCount >= 3) return 'high';
+  if (affectedFilesCount >= 5 || affectedServicesCount >= 2 || relationship === 'transitive') return 'medium';
+  return 'low';
+}
+
+function automationMode({ relationship, likelyBreaking, exposureDataSource }) {
+  if (relationship === 'unused') return 'remove';
+  if (exposureDataSource !== 'orbit') return 'needs-orbit-validation';
+  if (relationship === 'transitive') return 'override-and-review';
+  if (likelyBreaking) return 'migration-mr-with-review';
+  return 'auto-mr-ready';
+}
+
+function buildRequiredChanges(vulnerability, impactReport, context) {
+  const changes = [];
+
+  if (context.relationship === 'unused') {
+    return [{
+      title: 'Remove the dependency instead of upgrading it',
+      detail: 'Orbit confirmed zero importing files, so the safest remediation is deleting the dependency and refreshing the lockfile.',
+      confidence: 'high',
+    }];
+  }
+
+  if (context.relationship === 'transitive') {
+    changes.push({
+      title: 'Patch the transitive dependency path',
+      detail: vulnerability.dependencyChain?.chain
+        ? `Resolved chain: ${vulnerability.dependencyChain.chain.join(' -> ')}. Use an ecosystem override or upgrade the parent dependency that pulls it in.`
+        : 'The package is transitive, so there is no direct manifest line to bump. Force a secure resolver version or upgrade the parent dependency.',
+      confidence: 'high',
+    });
+  }
+
+  if (impactReport.affectedFilesCount > 0) {
+    changes.push({
+      title: 'Review affected import sites',
+      detail: `${impactReport.affectedFilesCount} file(s) import this package across ${context.affectedServicesCount} service area(s). These are the files most likely to need code changes.`,
+      confidence: impactReport.exposureDataSource === 'orbit' ? 'high' : 'low',
+    });
+  }
+
+  if (impactReport.likelyBreaking) {
+    changes.push({
+      title: 'Check release notes for removed or renamed APIs',
+      detail: impactReport.breakingChangeReasoning,
+      confidence: 'medium',
+    });
+  }
+
+  if (context.touchesPublicApi) {
+    changes.push({
+      title: 'Validate public API compatibility',
+      detail: 'At least one importing file is classified as public API, so contract tests or consumer checks should run before merge.',
+      confidence: 'high',
+    });
+  }
+
+  if (context.touchesConfig) {
+    changes.push({
+      title: 'Review configuration and schema usage',
+      detail: 'Affected paths include config/schema/env-style files. Verify default values, renamed options, and deployment configuration.',
+      confidence: 'medium',
+    });
+  }
+
+  if (context.touchesAuth) {
+    changes.push({
+      title: 'Review authentication or authorization adapters',
+      detail: 'Affected paths include auth/security/session-style code. Prioritize regression tests around login, token handling, and permissions.',
+      confidence: 'medium',
+    });
+  }
+
+  if (changes.length === 0) {
+    changes.push({
+      title: 'Apply the version bump and run verification',
+      detail: 'No affected import sites were available, so treat this as a manifest-only remediation until Orbit data is present.',
+      confidence: 'low',
+    });
+  }
+
+  return changes;
+}
+
+function buildSafetyChecks(context) {
+  const checks = ['Run the project test suite after the manifest and lockfile update'];
+  if (context.touchesPublicApi) checks.push('Run API/contract tests for public entry points');
+  if (context.touchesAuth) checks.push('Run auth and permission regression tests');
+  if (context.touchesConfig) checks.push('Validate deployment config and environment defaults');
+  if (context.relationship === 'transitive') checks.push('Run dependency-tree verification to confirm the patched version resolves');
+  return checks;
+}
+
+function buildMigrationPhases(context) {
+  if (context.relationship === 'unused') {
+    return [
+      { phase: 1, title: 'Remove', detail: 'Delete the unused dependency from the manifest.' },
+      { phase: 2, title: 'Verify', detail: 'Refresh the lockfile and run tests to prove removal is safe.' },
+    ];
+  }
+
+  const phases = [
+    { phase: 1, title: 'Map exposure', detail: 'Use Orbit evidence to review each affected file and service area.' },
+  ];
+
+  if (context.likelyBreaking) {
+    phases.push({ phase: 2, title: 'Adapt code', detail: 'Apply any source changes required by the major-version migration notes.' });
+  }
+
+  phases.push(
+    { phase: phases.length + 1, title: 'Upgrade', detail: 'Apply the dependency fix and refresh the lockfile with the ecosystem package manager.' },
+    { phase: phases.length + 2, title: 'Verify and ship', detail: 'Run safety checks, open the MR, and let a human review before merge.' }
+  );
+
+  return phases;
+}
+
+function buildUpgradeImpactSimulation(vulnerability, impactReport) {
+  const paths = (vulnerability.affectedFiles || []).map(filePathOf);
+  const affectedServices = unique(paths.map(inferServiceName));
+  const relationship = dependencyRelationship(vulnerability);
+  const context = {
+    relationship,
+    affectedServices,
+    affectedServicesCount: affectedServices.length,
+    affectedFilesCount: impactReport.affectedFilesCount,
+    likelyBreaking: impactReport.likelyBreaking,
+    exposureDataSource: impactReport.exposureDataSource,
+    touchesPublicApi: (vulnerability.affectedFiles || []).some(f => f.category === 'public-api'),
+    touchesConfig: hasPathMatch(paths, ['config', 'schema', '.env', '.yaml', '.yml', '.json']),
+    touchesAuth: hasPathMatch(paths, ['auth', 'oauth', 'jwt', 'session', 'permission']),
+  };
+
+  return {
+    package: vulnerability.package,
+    from: vulnerability.currentVersion,
+    to: vulnerability.fixedVersion,
+    relationship,
+    difficulty: difficultyFor(context),
+    automationMode: automationMode(context),
+    affectedServicesCount: context.affectedServicesCount,
+    affectedServices,
+    affectedFilesCount: context.affectedFilesCount,
+    requiredChanges: buildRequiredChanges(vulnerability, impactReport, context),
+    safetyChecks: buildSafetyChecks(context),
+    migrationPhases: buildMigrationPhases(context),
+  };
+}
+
+function formatUpgradeImpactSimulation(simulation) {
+  const services = simulation.affectedServices.length
+    ? simulation.affectedServices.join(', ')
+    : 'none confirmed';
+  const changes = simulation.requiredChanges
+    .map(change => `  - ${change.title} (${change.confidence} confidence): ${change.detail}`)
+    .join('\n');
+  const checks = simulation.safetyChecks.map(check => `  - ${check}`).join('\n');
+  const phases = simulation.migrationPhases
+    .map(phase => `  ${phase.phase}. ${phase.title}: ${phase.detail}`)
+    .join('\n');
+
+  return `## Upgrade Impact Simulator
+
+- **Dependency relationship**: ${simulation.relationship}
+- **Upgrade difficulty**: ${simulation.difficulty}
+- **Automation mode**: ${simulation.automationMode}
+- **Affected services**: ${simulation.affectedServicesCount} (${services})
+- **Affected files**: ${simulation.affectedFilesCount}
+
+### Required changes
+${changes}
+
+### Safety checks
+${checks}
+
+### Migration phases
+${phases}
+`;
+}
+
+module.exports = {
+  buildUpgradeImpactSimulation,
+  formatUpgradeImpactSimulation,
+};