@getcodesentinel/codesentinel 1.6.5 → 1.8.0

package/dist/index.js

@@ -1392,6 +1392,223 @@ var createSummaryShape = (summary) => ({
 });
 var formatAnalyzeOutput = (summary, mode) => mode === "json" ? JSON.stringify(summary, null, 2) : JSON.stringify(createSummaryShape(summary), null, 2);
 
+// src/application/format-explain-output.ts
+var sortFactorByContribution = (left, right) => right.contribution - left.contribution || left.factorId.localeCompare(right.factorId);
+var toRiskBand = (score) => {
+  if (score < 25) {
+    return "low";
+  }
+  if (score < 50) {
+    return "moderate";
+  }
+  if (score < 75) {
+    return "high";
+  }
+  return "very_high";
+};
+var factorLabelById = {
+  "repository.structural": "Structural complexity",
+  "repository.evolution": "Change volatility",
+  "repository.external": "External dependency pressure",
+  "repository.composite.interactions": "Intersection amplification",
+  "file.structural": "File structural complexity",
+  "file.evolution": "File change volatility",
+  "file.external": "File external pressure",
+  "file.composite.interactions": "File interaction amplification",
+  "module.average_file_risk": "Average file risk",
+  "module.peak_file_risk": "Peak file risk",
+  "dependency.signals": "Dependency risk signals",
+  "dependency.staleness": "Dependency staleness",
+  "dependency.maintainer_concentration": "Maintainer concentration",
+  "dependency.topology": "Dependency topology pressure",
+  "dependency.bus_factor": "Dependency bus factor",
+  "dependency.popularity_dampening": "Popularity dampening"
+};
+var formatFactorLabel = (factorId) => factorLabelById[factorId] ?? factorId;
+var formatNumber = (value) => value === null || value === void 0 ? "n/a" : `${value}`;
+var formatFactorSummary = (factor) => `${formatFactorLabel(factor.factorId)} (+${factor.contribution}, confidence=${factor.confidence})`;
+var formatFactorEvidence = (factor) => {
+  if (factor.factorId === "repository.structural") {
+    return `structural dimension=${formatNumber(factor.rawMetrics["structuralDimension"])}`;
+  }
+  if (factor.factorId === "repository.evolution") {
+    return `evolution dimension=${formatNumber(factor.rawMetrics["evolutionDimension"])}`;
+  }
+  if (factor.factorId === "repository.external") {
+    return `external dimension=${formatNumber(factor.rawMetrics["externalDimension"])}`;
+  }
+  if (factor.factorId === "repository.composite.interactions") {
+    return `structural\xD7evolution=${formatNumber(factor.rawMetrics["structuralEvolution"])}, central instability=${formatNumber(factor.rawMetrics["centralInstability"])}, dependency amplification=${formatNumber(factor.rawMetrics["dependencyAmplification"])}`;
+  }
+  if (factor.factorId === "file.structural") {
+    return `fanIn=${formatNumber(factor.rawMetrics["fanIn"])}, fanOut=${formatNumber(factor.rawMetrics["fanOut"])}, depth=${formatNumber(factor.rawMetrics["depth"])}, inCycle=${formatNumber(factor.rawMetrics["cycleParticipation"])}`;
+  }
+  if (factor.factorId === "file.evolution") {
+    return `commitCount=${formatNumber(factor.rawMetrics["commitCount"])}, churnTotal=${formatNumber(factor.rawMetrics["churnTotal"])}, recentVolatility=${formatNumber(factor.rawMetrics["recentVolatility"])}`;
+  }
+  if (factor.factorId === "file.external") {
+    return `repositoryExternalPressure=${formatNumber(factor.rawMetrics["repositoryExternalPressure"])}, dependencyAffinity=${formatNumber(factor.rawMetrics["dependencyAffinity"])}`;
+  }
+  if (factor.factorId === "file.composite.interactions") {
+    return `structural\xD7evolution=${formatNumber(factor.rawMetrics["structuralEvolutionInteraction"])}, central instability=${formatNumber(factor.rawMetrics["centralInstabilityInteraction"])}, dependency amplification=${formatNumber(factor.rawMetrics["dependencyAmplificationInteraction"])}`;
+  }
+  return "evidence available in trace";
+};
+var findRepositoryTarget = (targets) => targets.find((target) => target.targetType === "repository");
+var buildRepositoryActions = (payload, repositoryTarget) => {
+  if (repositoryTarget === void 0) {
+    return ["No repository trace available."];
+  }
+  const topHotspots = payload.summary.risk.hotspots.slice(0, 3).map((hotspot) => hotspot.file);
+  const highRiskDependencies = payload.summary.external.available ? payload.summary.external.highRiskDependencies.slice(0, 3) : [];
+  const actions = [];
+  for (const lever of repositoryTarget.reductionLevers) {
+    if (lever.factorId === "repository.evolution") {
+      actions.push(
+        `Reduce volatility/churn in top hotspots first: ${topHotspots.join(", ") || "no hotspots available"}.`
+      );
+      continue;
+    }
+    if (lever.factorId === "repository.structural") {
+      actions.push(
+        `Lower fan-in/fan-out and break cycles in central files: ${topHotspots.join(", ") || "no hotspots available"}.`
+      );
+      continue;
+    }
+    if (lever.factorId === "repository.composite.interactions") {
+      actions.push(
+        "Stabilize central files before refactors; interaction effects are amplifying risk."
+      );
+      continue;
+    }
+    if (lever.factorId === "repository.external") {
+      actions.push(
+        `Review high-risk direct dependencies: ${highRiskDependencies.join(", ") || "none detected"}.`
+      );
+      continue;
+    }
+  }
+  if (actions.length === 0) {
+    actions.push("No clear reduction levers available from current trace.");
+  }
+  return actions.slice(0, 3);
+};
+var renderTargetText = (target) => {
+  const lines = [];
+  lines.push(`${target.targetType}: ${target.targetId}`);
+  lines.push(`  score: ${target.totalScore} (${target.normalizedScore})`);
+  lines.push("  top factors:");
+  const topFactors = [...target.factors].sort(sortFactorByContribution).slice(0, 5);
+  for (const factor of topFactors) {
+    lines.push(
+      `    - ${formatFactorSummary(factor)}`
+    );
+    lines.push(
+      `      evidence: ${formatFactorEvidence(factor)}`
+    );
+  }
+  lines.push("  reduction levers:");
+  for (const lever of target.reductionLevers) {
+    lines.push(
+      `    - ${formatFactorLabel(lever.factorId)} | estimatedImpact=${lever.estimatedImpact}`
+    );
+  }
+  return lines.join("\n");
+};
+var renderText = (payload) => {
+  const lines = [];
+  const repositoryTarget = findRepositoryTarget(payload.selectedTargets) ?? findRepositoryTarget(payload.trace.targets);
+  const repositoryTopFactors = repositoryTarget === void 0 ? [] : [...repositoryTarget.factors].sort(sortFactorByContribution).slice(0, 3);
+  const compositeFactors = repositoryTopFactors.filter((factor) => factor.family === "composite");
+  lines.push(`target: ${payload.summary.structural.targetPath}`);
+  lines.push(`repositoryScore: ${payload.summary.risk.repositoryScore}`);
+  lines.push(`riskBand: ${toRiskBand(payload.summary.risk.repositoryScore)}`);
+  lines.push(`selectedTargets: ${payload.selectedTargets.length}`);
+  lines.push("");
+  lines.push("explanation:");
+  lines.push(
+    `  why risky: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
+  );
+  lines.push(
+    `  what specifically contributed: ${repositoryTopFactors.map((factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`).join(", ") || "insufficient data"}`
+  );
+  lines.push(
+    `  dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
+  );
+  lines.push(
+    `  intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
+  );
+  lines.push(
+    `  what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+  );
+  lines.push("");
+  for (const target of payload.selectedTargets) {
+    lines.push(renderTargetText(target));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+};
+var renderMarkdown = (payload) => {
+  const lines = [];
+  const repositoryTarget = findRepositoryTarget(payload.selectedTargets) ?? findRepositoryTarget(payload.trace.targets);
+  const repositoryTopFactors = repositoryTarget === void 0 ? [] : [...repositoryTarget.factors].sort(sortFactorByContribution).slice(0, 3);
+  const compositeFactors = repositoryTopFactors.filter((factor) => factor.family === "composite");
+  lines.push(`# CodeSentinel Explanation`);
+  lines.push(`- target: \`${payload.summary.structural.targetPath}\``);
+  lines.push(`- repositoryScore: \`${payload.summary.risk.repositoryScore}\``);
+  lines.push(`- riskBand: \`${toRiskBand(payload.summary.risk.repositoryScore)}\``);
+  lines.push(`- selectedTargets: \`${payload.selectedTargets.length}\``);
+  lines.push("");
+  lines.push(`## Summary`);
+  lines.push(
+    `- why risky: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
+  );
+  lines.push(
+    `- what specifically contributed: ${repositoryTopFactors.map((factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`).join(", ") || "insufficient data"}`
+  );
+  lines.push(
+    `- dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
+  );
+  lines.push(
+    `- intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
+  );
+  lines.push(
+    `- what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+  );
+  lines.push("");
+  for (const target of payload.selectedTargets) {
+    lines.push(`## ${target.targetType}: \`${target.targetId}\``);
+    lines.push(`- score: \`${target.totalScore}\` (\`${target.normalizedScore}\`)`);
+    lines.push(`- dominantFactors: \`${target.dominantFactors.join(", ")}\``);
+    lines.push(`- Top factors:`);
+    for (const factor of [...target.factors].sort(sortFactorByContribution).slice(0, 5)) {
+      lines.push(
+        `  - \`${formatFactorLabel(factor.factorId)}\` contribution=\`${factor.contribution}\` confidence=\`${factor.confidence}\``
+      );
+      lines.push(
+        `    - evidence: \`${formatFactorEvidence(factor)}\``
+      );
+    }
+    lines.push(`- Reduction levers:`);
+    for (const lever of target.reductionLevers) {
+      lines.push(
+        `  - \`${formatFactorLabel(lever.factorId)}\` estimatedImpact=\`${lever.estimatedImpact}\``
+      );
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+};
+var formatExplainOutput = (payload, format) => {
+  if (format === "json") {
+    return JSON.stringify(payload, null, 2);
+  }
+  if (format === "md") {
+    return renderMarkdown(payload);
+  }
+  return renderText(payload);
+};
+
 // src/application/format-dependency-risk-output.ts
 var createSummaryShape2 = (result) => {
   if (!result.available) {
@@ -1401,18 +1618,19 @@ var createSummaryShape2 = (result) => {
       dependency: result.dependency
     };
   }
-  const direct = result.external.dependencies[0];
+  const direct = result.external.available ? result.external.dependencies[0] : void 0;
   return {
     available: true,
     dependency: result.dependency,
     graph: result.graph,
     assumptions: result.assumptions,
     external: {
-      metrics: result.external.metrics,
+      available: result.external.available,
+      metrics: result.external.available ? result.external.metrics : null,
       ownRiskSignals: direct?.ownRiskSignals ?? [],
       inheritedRiskSignals: direct?.inheritedRiskSignals ?? [],
-      highRiskDependenciesTop: result.external.highRiskDependencies.slice(0, 10),
-      transitiveExposureDependenciesTop: result.external.transitiveExposureDependencies.slice(0, 10)
+      highRiskDependenciesTop: result.external.available ? result.external.highRiskDependencies.slice(0, 10) : [],
+      transitiveExposureDependenciesTop: result.external.available ? result.external.transitiveExposureDependencies.slice(0, 10) : []
     }
   };
 };
@@ -2696,11 +2914,86 @@ var computeDependencySignalScore = (ownSignals, inheritedSignals, inheritedSigna
   }
   return toUnitInterval(weightedTotal / maxWeightedTotal);
 };
+var clampConfidence = (value) => round44(toUnitInterval(value));
+var buildFactorTraces = (totalScore, inputs) => {
+  const positiveInputs = inputs.filter((input) => input.strength > 0);
+  const strengthTotal = positiveInputs.reduce((sum, input) => sum + input.strength, 0);
+  const traces = inputs.map((input) => ({
+    factorId: input.factorId,
+    family: input.family,
+    contribution: 0,
+    rawMetrics: input.rawMetrics,
+    normalizedMetrics: input.normalizedMetrics,
+    weight: input.weight,
+    amplification: input.amplification,
+    evidence: input.evidence,
+    confidence: clampConfidence(input.confidence)
+  }));
+  if (strengthTotal <= 0 || totalScore <= 0) {
+    return traces;
+  }
+  const scored = positiveInputs.map((input) => ({
+    factorId: input.factorId,
+    contribution: totalScore * input.strength / strengthTotal
+  }));
+  let distributed = 0;
+  for (let index = 0; index < scored.length; index += 1) {
+    const current = scored[index];
+    if (current === void 0) {
+      continue;
+    }
+    const traceIndex = traces.findIndex((trace) => trace.factorId === current.factorId);
+    if (traceIndex < 0) {
+      continue;
+    }
+    const existing = traces[traceIndex];
+    if (existing === void 0) {
+      continue;
+    }
+    if (index === scored.length - 1) {
+      const remaining = round44(totalScore - distributed);
+      traces[traceIndex] = {
+        ...existing,
+        contribution: Math.max(0, remaining)
+      };
+      distributed += Math.max(0, remaining);
+      continue;
+    }
+    const rounded = round44(current.contribution);
+    traces[traceIndex] = {
+      ...existing,
+      contribution: rounded
+    };
+    distributed += rounded;
+  }
+  return traces;
+};
+var buildReductionLevers = (factors) => factors.filter((factor) => factor.contribution > 0).sort(
+  (a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)
+).slice(0, 3).map((factor) => ({
+  factorId: factor.factorId,
+  estimatedImpact: round44(factor.contribution)
+}));
+var buildTargetTrace = (targetType, targetId, totalScore, normalizedScore, factors) => {
+  const dominantFactors = [...factors].filter((factor) => factor.contribution > 0).sort(
+    (a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)
+  ).slice(0, 3).map((factor) => factor.factorId);
+  return {
+    targetType,
+    targetId,
+    totalScore: round44(totalScore),
+    normalizedScore: round44(normalizedScore),
+    factors,
+    dominantFactors,
+    reductionLevers: buildReductionLevers(factors)
+  };
+};
 var computeDependencyScores = (external, config) => {
   if (!external.available) {
     return {
       dependencyScores: [],
-      repositoryExternalPressure: 0
+      repositoryExternalPressure: 0,
+      dependencyContexts: /* @__PURE__ */ new Map()
     };
   }
   const transitiveCounts = external.dependencies.map(
@@ -2723,6 +3016,7 @@ var computeDependencyScores = (external, config) => {
     config.quantileClamp.lower,
     config.quantileClamp.upper
   );
+  const dependencyContexts = /* @__PURE__ */ new Map();
   const dependencyScores = external.dependencies.map((dependency) => {
     const signalScore = computeDependencySignalScore(
       dependency.ownRiskSignals,
@@ -2751,6 +3045,33 @@ var computeDependencyScores = (external, config) => {
       config.dependencySignals.popularityHalfLifeDownloads
     ) * config.dependencySignals.popularityMaxDampening;
     const normalizedScore = toUnitInterval(baseScore * popularityDampener);
+    const availableMetricCount = [
+      dependency.daysSinceLastRelease,
+      dependency.maintainerCount,
+      dependency.busFactor,
+      dependency.weeklyDownloads
+    ].filter((value) => value !== null).length;
+    const confidence = toUnitInterval(0.5 + availableMetricCount * 0.125);
+    dependencyContexts.set(dependency.name, {
+      signalScore: round44(signalScore),
+      stalenessRisk: round44(stalenessRisk),
+      maintainerConcentrationRisk: round44(maintainerConcentrationRisk),
+      transitiveBurdenRisk: round44(transitiveBurdenRisk),
+      centralityRisk: round44(centralityRisk),
+      chainDepthRisk: round44(chainDepthRisk),
+      busFactorRisk: round44(busFactorRisk),
+      popularityDampener: round44(popularityDampener),
+      rawMetrics: {
+        daysSinceLastRelease: dependency.daysSinceLastRelease,
+        maintainerCount: dependency.maintainerCount,
+        transitiveCount: dependency.transitiveDependencies.length,
+        dependents: dependency.dependents,
+        dependencyDepth: dependency.dependencyDepth,
+        busFactor: dependency.busFactor,
+        weeklyDownloads: dependency.weeklyDownloads
+      },
+      confidence: round44(confidence)
+    });
     return {
       dependency: dependency.name,
       score: round44(normalizedScore * 100),
@@ -2773,7 +3094,8 @@ var computeDependencyScores = (external, config) => {
   );
   return {
     dependencyScores,
-    repositoryExternalPressure: round44(repositoryExternalPressure)
+    repositoryExternalPressure: round44(repositoryExternalPressure),
+    dependencyContexts
   };
 };
 var mapEvolutionByFile = (evolution) => {
@@ -2925,7 +3247,8 @@ var buildFragileClusters = (structural, evolution, fileScoresByFile, config) =>
     (a, b) => b.score - a.score || a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id)
   );
 };
-var computeRiskSummary = (structural, evolution, external, config) => {
+var computeRiskSummary = (structural, evolution, external, config, traceCollector) => {
+  const collector = traceCollector;
   const dependencyComputation = computeDependencyScores(external, config);
   const evolutionByFile = mapEvolutionByFile(evolution);
   const evolutionScales = computeEvolutionScales(evolutionByFile, config);
@@ -2964,19 +3287,20 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     );
     const structuralCentrality = toUnitInterval((fanInRisk + fanOutRisk) / 2);
     let evolutionFactor = 0;
+    let frequencyRisk = 0;
+    let churnRisk = 0;
+    let volatilityRisk = 0;
+    let ownershipConcentrationRisk = 0;
+    let busFactorRisk = 0;
     const evolutionMetrics = evolutionByFile.get(filePath);
     if (evolution.available && evolutionMetrics !== void 0) {
-      const frequencyRisk = normalizeWithScale(
-        logScale(evolutionMetrics.commitCount),
-        evolutionScales.commitCount
+      frequencyRisk = normalizeWithScale(logScale(evolutionMetrics.commitCount), evolutionScales.commitCount);
+      churnRisk = normalizeWithScale(logScale(evolutionMetrics.churnTotal), evolutionScales.churnTotal);
+      volatilityRisk = toUnitInterval(evolutionMetrics.recentVolatility);
+      ownershipConcentrationRisk = toUnitInterval(evolutionMetrics.topAuthorShare);
+      busFactorRisk = toUnitInterval(
+        1 - normalizeWithScale(evolutionMetrics.busFactor, evolutionScales.busFactor)
       );
-      const churnRisk = normalizeWithScale(
-        logScale(evolutionMetrics.churnTotal),
-        evolutionScales.churnTotal
-      );
-      const volatilityRisk = toUnitInterval(evolutionMetrics.recentVolatility);
-      const ownershipConcentrationRisk = toUnitInterval(evolutionMetrics.topAuthorShare);
-      const busFactorRisk = toUnitInterval(1 - normalizeWithScale(evolutionMetrics.busFactor, evolutionScales.busFactor));
       const evolutionWeights = config.evolutionFactorWeights;
       evolutionFactor = toUnitInterval(
         frequencyRisk * evolutionWeights.frequency + churnRisk * evolutionWeights.churn + volatilityRisk * evolutionWeights.recentVolatility + ownershipConcentrationRisk * evolutionWeights.ownershipConcentration + busFactorRisk * evolutionWeights.busFactorRisk
@@ -2984,11 +3308,17 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     }
     const dependencyAffinity = toUnitInterval(structuralCentrality * 0.6 + evolutionFactor * 0.4);
     const externalFactor = external.available ? toUnitInterval(dependencyComputation.repositoryExternalPressure * dependencyAffinity) : 0;
-    const baseline = structuralFactor * dimensionWeights.structural + evolutionFactor * dimensionWeights.evolution + externalFactor * dimensionWeights.external;
+    const structuralBase = structuralFactor * dimensionWeights.structural;
+    const evolutionBase = evolutionFactor * dimensionWeights.evolution;
+    const externalBase = externalFactor * dimensionWeights.external;
+    const baseline = structuralBase + evolutionBase + externalBase;
+    const interactionStructuralEvolution = structuralFactor * evolutionFactor * config.interactionWeights.structuralEvolution;
+    const interactionCentralInstability = structuralCentrality * evolutionFactor * config.interactionWeights.centralInstability;
+    const interactionDependencyAmplification = externalFactor * Math.max(structuralFactor, evolutionFactor) * config.interactionWeights.dependencyAmplification;
     const interactions = [
-      structuralFactor * evolutionFactor * config.interactionWeights.structuralEvolution,
-      structuralCentrality * evolutionFactor * config.interactionWeights.centralInstability,
-      externalFactor * Math.max(structuralFactor, evolutionFactor) * config.interactionWeights.dependencyAmplification
+      interactionStructuralEvolution,
+      interactionCentralInstability,
+      interactionDependencyAmplification
     ];
     const normalizedScore = saturatingComposite(baseline, interactions);
     return {
@@ -3000,7 +3330,38 @@ var computeRiskSummary = (structural, evolution, external, config) => {
         evolution: round44(evolutionFactor),
         external: round44(externalFactor)
       },
-      structuralCentrality: round44(structuralCentrality)
+      structuralCentrality: round44(structuralCentrality),
+      traceTerms: {
+        structuralBase: round44(structuralBase),
+        evolutionBase: round44(evolutionBase),
+        externalBase: round44(externalBase),
+        interactionStructuralEvolution: round44(interactionStructuralEvolution),
+        interactionCentralInstability: round44(interactionCentralInstability),
+        interactionDependencyAmplification: round44(interactionDependencyAmplification)
+      },
+      rawMetrics: {
+        fanIn: file.fanIn,
+        fanOut: file.fanOut,
+        depth: file.depth,
+        cycleParticipation: inCycle,
+        commitCount: evolutionMetrics?.commitCount ?? null,
+        churnTotal: evolutionMetrics?.churnTotal ?? null,
+        recentVolatility: evolutionMetrics?.recentVolatility ?? null,
+        topAuthorShare: evolutionMetrics?.topAuthorShare ?? null,
+        busFactor: evolutionMetrics?.busFactor ?? null,
+        dependencyAffinity: round44(dependencyAffinity),
+        repositoryExternalPressure: round44(dependencyComputation.repositoryExternalPressure)
+      },
+      normalizedMetrics: {
+        fanInRisk: round44(fanInRisk),
+        fanOutRisk: round44(fanOutRisk),
+        depthRisk: round44(depthRisk),
+        frequencyRisk: round44(frequencyRisk),
+        churnRisk: round44(churnRisk),
+        volatilityRisk: round44(volatilityRisk),
+        ownershipConcentrationRisk: round44(ownershipConcentrationRisk),
+        busFactorRisk: round44(busFactorRisk)
+      }
     };
   }).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
   const fileScores = fileRiskContexts.map((context) => ({
@@ -3009,6 +3370,103 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     normalizedScore: context.normalizedScore,
     factors: context.factors
   }));
+  if (collector !== void 0) {
+    for (const context of fileRiskContexts) {
+      const evidence = [
+        { kind: "file_metric", target: context.file, metric: "fanIn" },
+        { kind: "file_metric", target: context.file, metric: "fanOut" },
+        { kind: "file_metric", target: context.file, metric: "depth" }
+      ];
+      if (context.rawMetrics.cycleParticipation > 0) {
+        evidence.push({
+          kind: "graph_cycle",
+          cycleId: `file:${context.file}`,
+          files: [context.file]
+        });
+      }
+      const fileFactors = buildFactorTraces(context.score, [
+        {
+          factorId: "file.structural",
+          family: "structural",
+          strength: context.traceTerms.structuralBase,
+          rawMetrics: {
+            fanIn: context.rawMetrics.fanIn,
+            fanOut: context.rawMetrics.fanOut,
+            depth: context.rawMetrics.depth,
+            cycleParticipation: context.rawMetrics.cycleParticipation
+          },
+          normalizedMetrics: {
+            fanInRisk: context.normalizedMetrics.fanInRisk,
+            fanOutRisk: context.normalizedMetrics.fanOutRisk,
+            depthRisk: context.normalizedMetrics.depthRisk,
+            structuralFactor: context.factors.structural
+          },
+          weight: dimensionWeights.structural,
+          amplification: null,
+          evidence,
+          confidence: 1
+        },
+        {
+          factorId: "file.evolution",
+          family: "evolution",
+          strength: context.traceTerms.evolutionBase,
+          rawMetrics: {
+            commitCount: context.rawMetrics.commitCount,
+            churnTotal: context.rawMetrics.churnTotal,
+            recentVolatility: context.rawMetrics.recentVolatility,
+            topAuthorShare: context.rawMetrics.topAuthorShare,
+            busFactor: context.rawMetrics.busFactor
+          },
+          normalizedMetrics: {
+            frequencyRisk: context.normalizedMetrics.frequencyRisk,
+            churnRisk: context.normalizedMetrics.churnRisk,
+            volatilityRisk: context.normalizedMetrics.volatilityRisk,
+            ownershipConcentrationRisk: context.normalizedMetrics.ownershipConcentrationRisk,
+            busFactorRisk: context.normalizedMetrics.busFactorRisk,
+            evolutionFactor: context.factors.evolution
+          },
+          weight: dimensionWeights.evolution,
+          amplification: null,
+          evidence: [{ kind: "file_metric", target: context.file, metric: "commitCount" }],
+          confidence: evolution.available ? 1 : 0
+        },
+        {
+          factorId: "file.external",
+          family: "external",
+          strength: context.traceTerms.externalBase,
+          rawMetrics: {
+            repositoryExternalPressure: context.rawMetrics.repositoryExternalPressure,
+            dependencyAffinity: context.rawMetrics.dependencyAffinity
+          },
+          normalizedMetrics: {
+            externalFactor: context.factors.external
+          },
+          weight: dimensionWeights.external,
+          amplification: null,
+          evidence: [{ kind: "repository_metric", metric: "repositoryExternalPressure" }],
+          confidence: external.available ? 0.7 : 0
+        },
+        {
+          factorId: "file.composite.interactions",
+          family: "composite",
+          strength: context.traceTerms.interactionStructuralEvolution + context.traceTerms.interactionCentralInstability + context.traceTerms.interactionDependencyAmplification,
+          rawMetrics: {
+            structuralEvolutionInteraction: context.traceTerms.interactionStructuralEvolution,
+            centralInstabilityInteraction: context.traceTerms.interactionCentralInstability,
+            dependencyAmplificationInteraction: context.traceTerms.interactionDependencyAmplification
+          },
+          normalizedMetrics: {},
+          weight: null,
+          amplification: config.interactionWeights.structuralEvolution + config.interactionWeights.centralInstability + config.interactionWeights.dependencyAmplification,
+          evidence: [{ kind: "repository_metric", metric: "interactionWeights" }],
+          confidence: 0.9
+        }
+      ]);
+      collector.record(
+        buildTargetTrace("file", context.file, context.score, context.normalizedScore, fileFactors)
+      );
+    }
+  }
   const fileScoresByFile = new Map(fileScores.map((fileScore) => [fileScore.file, fileScore]));
   const hotspotsCount = Math.min(
     config.hotspotMaxFiles,
@@ -3037,6 +3495,39 @@ var computeRiskSummary = (structural, evolution, external, config) => {
       fileCount: values.length
     };
   }).sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
+  if (collector !== void 0) {
+    for (const [module, values] of moduleFiles.entries()) {
+      const averageScore = average(values);
+      const peakScore = values.reduce((max, value) => Math.max(max, value), 0);
+      const normalizedScore = toUnitInterval(averageScore * 0.65 + peakScore * 0.35);
+      const totalScore = round44(normalizedScore * 100);
+      const factors = buildFactorTraces(totalScore, [
+        {
+          factorId: "module.average_file_risk",
+          family: "composite",
+          strength: averageScore * 0.65,
+          rawMetrics: { averageFileRisk: round44(averageScore), fileCount: values.length },
+          normalizedMetrics: { normalizedModuleRisk: round44(normalizedScore) },
+          weight: 0.65,
+          amplification: null,
+          evidence: [{ kind: "repository_metric", metric: "moduleAggregation.average" }],
+          confidence: 1
+        },
+        {
+          factorId: "module.peak_file_risk",
+          family: "composite",
+          strength: peakScore * 0.35,
+          rawMetrics: { peakFileRisk: round44(peakScore), fileCount: values.length },
+          normalizedMetrics: { normalizedModuleRisk: round44(normalizedScore) },
+          weight: 0.35,
+          amplification: null,
+          evidence: [{ kind: "repository_metric", metric: "moduleAggregation.peak" }],
+          confidence: 1
+        }
+      ]);
+      collector.record(buildTargetTrace("module", module, totalScore, normalizedScore, factors));
+    }
+  }
   const fragileClusters = buildFragileClusters(structural, evolution, fileScoresByFile, config);
   const externalPressures = fileScores.map((fileScore) => fileScore.factors.external);
   const pressureThreshold = Math.max(
@@ -3057,6 +3548,107 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     ...zone,
     externalPressure: round44(zone.externalPressure)
   }));
+  if (collector !== void 0 && external.available) {
+    const dependencyByName = new Map(external.dependencies.map((dependency) => [dependency.name, dependency]));
+    for (const dependencyScore of dependencyComputation.dependencyScores) {
+      const dependency = dependencyByName.get(dependencyScore.dependency);
+      const context = dependencyComputation.dependencyContexts.get(dependencyScore.dependency);
+      if (dependency === void 0 || context === void 0) {
+        continue;
+      }
+      const hasMetadata = context.rawMetrics.daysSinceLastRelease !== null && context.rawMetrics.maintainerCount !== null;
+      const factors = buildFactorTraces(dependencyScore.score, [
+        {
+          factorId: "dependency.signals",
+          family: "external",
+          strength: context.signalScore * config.dependencyFactorWeights.signals,
+          rawMetrics: {
+            ownSignals: dependency.ownRiskSignals.length,
+            inheritedSignals: dependency.inheritedRiskSignals.length
+          },
+          normalizedMetrics: { signalScore: context.signalScore },
+          weight: config.dependencyFactorWeights.signals,
+          amplification: config.dependencySignals.inheritedSignalMultiplier,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "riskSignals" }],
+          confidence: 0.95
+        },
+        {
+          factorId: "dependency.staleness",
+          family: "external",
+          strength: context.stalenessRisk * config.dependencyFactorWeights.staleness,
+          rawMetrics: { daysSinceLastRelease: context.rawMetrics.daysSinceLastRelease },
+          normalizedMetrics: { stalenessRisk: context.stalenessRisk },
+          weight: config.dependencyFactorWeights.staleness,
+          amplification: null,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "daysSinceLastRelease" }],
+          confidence: hasMetadata ? 0.9 : 0.5
+        },
+        {
+          factorId: "dependency.maintainer_concentration",
+          family: "external",
+          strength: context.maintainerConcentrationRisk * config.dependencyFactorWeights.maintainerConcentration,
+          rawMetrics: { maintainerCount: context.rawMetrics.maintainerCount },
+          normalizedMetrics: {
+            maintainerConcentrationRisk: context.maintainerConcentrationRisk
+          },
+          weight: config.dependencyFactorWeights.maintainerConcentration,
+          amplification: null,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "maintainerCount" }],
+          confidence: hasMetadata ? 0.9 : 0.5
+        },
+        {
+          factorId: "dependency.topology",
+          family: "external",
+          strength: context.transitiveBurdenRisk * config.dependencyFactorWeights.transitiveBurden + context.centralityRisk * config.dependencyFactorWeights.centrality + context.chainDepthRisk * config.dependencyFactorWeights.chainDepth,
+          rawMetrics: {
+            transitiveCount: context.rawMetrics.transitiveCount,
+            dependents: context.rawMetrics.dependents,
+            dependencyDepth: context.rawMetrics.dependencyDepth
+          },
+          normalizedMetrics: {
+            transitiveBurdenRisk: context.transitiveBurdenRisk,
+            centralityRisk: context.centralityRisk,
+            chainDepthRisk: context.chainDepthRisk
+          },
+          weight: config.dependencyFactorWeights.transitiveBurden + config.dependencyFactorWeights.centrality + config.dependencyFactorWeights.chainDepth,
+          amplification: null,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "dependencyDepth" }],
+          confidence: 1
+        },
+        {
+          factorId: "dependency.bus_factor",
+          family: "external",
+          strength: context.busFactorRisk * config.dependencyFactorWeights.busFactorRisk,
+          rawMetrics: { busFactor: context.rawMetrics.busFactor },
+          normalizedMetrics: { busFactorRisk: context.busFactorRisk },
+          weight: config.dependencyFactorWeights.busFactorRisk,
+          amplification: null,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "busFactor" }],
+          confidence: context.rawMetrics.busFactor === null ? 0.5 : 0.85
+        },
+        {
+          factorId: "dependency.popularity_dampening",
+          family: "composite",
+          strength: 1 - context.popularityDampener,
+          rawMetrics: { weeklyDownloads: context.rawMetrics.weeklyDownloads },
+          normalizedMetrics: { popularityDampener: context.popularityDampener },
+          weight: config.dependencySignals.popularityMaxDampening,
+          amplification: null,
+          evidence: [{ kind: "dependency_metric", target: dependency.name, metric: "weeklyDownloads" }],
+          confidence: context.rawMetrics.weeklyDownloads === null ? 0.4 : 0.9
+        }
+      ]);
+      collector.record(
+        buildTargetTrace(
+          "dependency",
+          dependencyScore.dependency,
+          dependencyScore.score,
+          dependencyScore.normalizedScore,
+          factors
+        )
+      );
+    }
+  }
   const structuralDimension = average(fileScores.map((fileScore) => fileScore.factors.structural));
   const evolutionDimension = average(fileScores.map((fileScore) => fileScore.factors.evolution));
   const externalDimension = dependencyComputation.repositoryExternalPressure;
@@ -3077,8 +3669,79 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     criticalInstability * config.interactionWeights.centralInstability,
     dependencyAmplification * config.interactionWeights.dependencyAmplification
   ]);
+  const repositoryScore = round44(repositoryNormalizedScore * 100);
+  if (collector !== void 0) {
+    const repositoryFactors = buildFactorTraces(repositoryScore, [
+      {
+        factorId: "repository.structural",
+        family: "structural",
+        strength: structuralDimension * dimensionWeights.structural,
+        rawMetrics: { structuralDimension: round44(structuralDimension) },
+        normalizedMetrics: { dimensionWeight: round44(dimensionWeights.structural) },
+        weight: dimensionWeights.structural,
+        amplification: null,
+        evidence: [{ kind: "repository_metric", metric: "structuralDimension" }],
+        confidence: 1
+      },
+      {
+        factorId: "repository.evolution",
+        family: "evolution",
+        strength: evolutionDimension * dimensionWeights.evolution,
+        rawMetrics: { evolutionDimension: round44(evolutionDimension) },
+        normalizedMetrics: { dimensionWeight: round44(dimensionWeights.evolution) },
+        weight: dimensionWeights.evolution,
+        amplification: null,
+        evidence: [{ kind: "repository_metric", metric: "evolutionDimension" }],
+        confidence: evolution.available ? 1 : 0
+      },
+      {
+        factorId: "repository.external",
+        family: "external",
+        strength: externalDimension * dimensionWeights.external,
+        rawMetrics: { externalDimension: round44(externalDimension) },
+        normalizedMetrics: { dimensionWeight: round44(dimensionWeights.external) },
+        weight: dimensionWeights.external,
+        amplification: null,
+        evidence: [{ kind: "repository_metric", metric: "externalDimension" }],
+        confidence: external.available ? 0.8 : 0
+      },
+      {
+        factorId: "repository.composite.interactions",
+        family: "composite",
+        strength: structuralDimension * evolutionDimension * config.interactionWeights.structuralEvolution + criticalInstability * config.interactionWeights.centralInstability + dependencyAmplification * config.interactionWeights.dependencyAmplification,
+        rawMetrics: {
+          structuralEvolution: round44(
+            structuralDimension * evolutionDimension * config.interactionWeights.structuralEvolution
+          ),
+          centralInstability: round44(
+            criticalInstability * config.interactionWeights.centralInstability
+          ),
+          dependencyAmplification: round44(
+            dependencyAmplification * config.interactionWeights.dependencyAmplification
+          )
+        },
+        normalizedMetrics: {
+          criticalInstability: round44(criticalInstability),
+          dependencyAmplification: round44(dependencyAmplification)
+        },
+        weight: null,
+        amplification: config.interactionWeights.structuralEvolution + config.interactionWeights.centralInstability + config.interactionWeights.dependencyAmplification,
+        evidence: [{ kind: "repository_metric", metric: "interactionTerms" }],
+        confidence: 0.9
+      }
+    ]);
+    collector.record(
+      buildTargetTrace(
+        "repository",
+        structural.targetPath,
+        repositoryScore,
+        repositoryNormalizedScore,
+        repositoryFactors
+      )
+    );
+  }
   return {
-    repositoryScore: round44(repositoryNormalizedScore * 100),
+    repositoryScore,
     normalizedScore: round44(repositoryNormalizedScore),
     hotspots,
     fragileClusters,
@@ -3088,6 +3751,37 @@ var computeRiskSummary = (structural, evolution, external, config) => {
     dependencyScores: dependencyComputation.dependencyScores
   };
 };
+var NoopTraceCollector = class {
+  record(_target) {
+  }
+  build() {
+    return void 0;
+  }
+};
+var RecordingTraceCollector = class {
+  targets = [];
+  record(target) {
+    this.targets.push(target);
+  }
+  build() {
+    const orderedTargets = [...this.targets].sort((a, b) => {
+      if (a.targetType !== b.targetType) {
+        return a.targetType.localeCompare(b.targetType);
+      }
+      if (b.totalScore !== a.totalScore) {
+        return b.totalScore - a.totalScore;
+      }
+      return a.targetId.localeCompare(b.targetId);
+    });
+    return {
+      schemaVersion: "1",
+      contributionTolerance: 1e-4,
+      targets: orderedTargets
+    };
+  }
+};
+var noopCollectorSingleton = new NoopTraceCollector();
+var createTraceCollector = (enabled) => enabled ? new RecordingTraceCollector() : noopCollectorSingleton;
 var mergeConfig = (overrides) => {
   if (overrides === void 0) {
     return DEFAULT_RISK_ENGINE_CONFIG;
@@ -3142,8 +3836,29 @@ var mergeConfig = (overrides) => {
   };
 };
 var computeRepositoryRiskSummary = (input) => {
+  return evaluateRepositoryRisk(input, { explain: false }).summary;
+};
+var evaluateRepositoryRisk = (input, options = {}) => {
   const config = mergeConfig(input.config);
-  return computeRiskSummary(input.structural, input.evolution, input.external, config);
+  const collector = createTraceCollector(options.explain === true);
+  const summary = computeRiskSummary(
+    input.structural,
+    input.evolution,
+    input.external,
+    config,
+    collector
+  );
+  const trace = collector.build();
+  if (options.explain !== true) {
+    return { summary };
+  }
+  if (trace === void 0) {
+    return { summary };
+  }
+  return {
+    summary,
+    trace
+  };
 };
 
 // src/application/run-analyze-command.ts
@@ -3259,7 +3974,7 @@ var createEvolutionProgressReporter = (logger) => {
     }
   };
 };
-var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
+var collectAnalysisInputs = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
   const invocationCwd = process.env["INIT_CWD"] ?? process.cwd();
   const targetPath = resolveTargetPath(inputPath, invocationCwd);
   logger.info(`analyzing repository: ${targetPath}`);
@@ -3272,10 +3987,13 @@ var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSil
     `structural metrics: nodes=${structural.metrics.nodeCount}, edges=${structural.metrics.edgeCount}, cycles=${structural.metrics.cycleCount}`
   );
   logger.info(`analyzing git evolution (author identity: ${authorIdentityMode})`);
-  const evolution = analyzeRepositoryEvolutionFromGit({
-    repositoryPath: targetPath,
-    config: { authorIdentityMode }
-  }, createEvolutionProgressReporter(logger));
+  const evolution = analyzeRepositoryEvolutionFromGit(
+    {
+      repositoryPath: targetPath,
+      config: { authorIdentityMode }
+    },
+    createEvolutionProgressReporter(logger)
+  );
   if (evolution.available) {
     logger.debug(
       `evolution metrics: commits=${evolution.metrics.totalCommits}, files=${evolution.metrics.totalFiles}, hotspotThreshold=${evolution.metrics.hotspotThresholdCommitCount}`
@@ -3295,20 +4013,528 @@ var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSil
   } else {
     logger.warn(`external analysis unavailable: ${external.reason}`);
   }
-  logger.info("computing risk summary");
-  const risk = computeRepositoryRiskSummary({
+  return {
     structural,
     evolution,
     external
-  });
+  };
+};
+var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
+  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  logger.info("computing risk summary");
+  const risk = computeRepositoryRiskSummary(analysisInputs);
   logger.info(`analysis completed (repositoryScore=${risk.repositoryScore})`);
-  const summary = {
-    structural,
-    evolution,
-    external,
+  return {
+    ...analysisInputs,
     risk
   };
-  return summary;
+};
+
+// src/application/run-report-command.ts
+import { readFile, writeFile } from "fs/promises";
+
+// ../reporter/dist/index.js
+var SNAPSHOT_SCHEMA_VERSION = "codesentinel.snapshot.v1";
+var REPORT_SCHEMA_VERSION = "codesentinel.report.v1";
+var RISK_MODEL_VERSION = "deterministic-v1";
+var round45 = (value) => Number(value.toFixed(4));
+var toRiskTier = (score) => {
+  if (score < 20) {
+    return "low";
+  }
+  if (score < 40) {
+    return "moderate";
+  }
+  if (score < 60) {
+    return "elevated";
+  }
+  if (score < 80) {
+    return "high";
+  }
+  return "very_high";
+};
+var factorLabelById2 = {
+  "repository.structural": "Structural complexity",
+  "repository.evolution": "Change volatility",
+  "repository.external": "External dependency pressure",
+  "repository.composite.interactions": "Intersection amplification",
+  "file.structural": "File structural complexity",
+  "file.evolution": "File change volatility",
+  "file.external": "File external pressure",
+  "file.composite.interactions": "File interaction amplification",
+  "module.average_file_risk": "Average file risk",
+  "module.peak_file_risk": "Peak file risk",
+  "dependency.signals": "Dependency risk signals",
+  "dependency.staleness": "Dependency staleness",
+  "dependency.maintainer_concentration": "Maintainer concentration",
+  "dependency.topology": "Dependency topology pressure",
+  "dependency.bus_factor": "Dependency bus factor",
+  "dependency.popularity_dampening": "Popularity dampening"
+};
+var factorLabel = (factorId) => factorLabelById2[factorId] ?? factorId;
+var summarizeEvidence = (factor) => {
+  const entries = Object.entries(factor.rawMetrics).filter(([, value]) => value !== null).sort((a, b) => a[0].localeCompare(b[0])).slice(0, 3).map(([key, value]) => `${key}=${value}`);
+  if (entries.length > 0) {
+    return entries.join(", ");
+  }
+  const evidence = [...factor.evidence].map((entry) => {
+    if (entry.kind === "file_metric") {
+      return `${entry.target}:${entry.metric}`;
+    }
+    if (entry.kind === "dependency_metric") {
+      return `${entry.target}:${entry.metric}`;
+    }
+    if (entry.kind === "repository_metric") {
+      return entry.metric;
+    }
+    if (entry.kind === "graph_cycle") {
+      return `cycle:${entry.cycleId}`;
+    }
+    return `${entry.fileA}<->${entry.fileB}`;
+  }).sort((a, b) => a.localeCompare(b));
+  return evidence.join(", ");
+};
+var diffSets = (current, baseline) => {
+  const currentSet = new Set(current);
+  const baselineSet = new Set(baseline);
+  const added = [...currentSet].filter((item) => !baselineSet.has(item)).sort((a, b) => a.localeCompare(b));
+  const removed = [...baselineSet].filter((item) => !currentSet.has(item)).sort((a, b) => a.localeCompare(b));
+  return { added, removed };
+};
+var diffScoreMap = (current, baseline) => {
+  const keys = [.../* @__PURE__ */ new Set([...current.keys(), ...baseline.keys()])].sort((a, b) => a.localeCompare(b));
+  return keys.map((key) => {
+    const before = baseline.get(key) ?? 0;
+    const after = current.get(key) ?? 0;
+    const delta = round45(after - before);
+    return {
+      target: key,
+      before: round45(before),
+      after: round45(after),
+      delta
+    };
+  }).filter((entry) => entry.delta !== 0).sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta) || a.target.localeCompare(b.target));
+};
+var cycleKey = (nodes) => [...nodes].sort((a, b) => a.localeCompare(b)).join(" -> ");
+var compareSnapshots = (current, baseline) => {
+  const currentFileScores = new Map(
+    current.analysis.risk.fileScores.map((item) => [item.file, item.score])
+  );
+  const baselineFileScores = new Map(
+    baseline.analysis.risk.fileScores.map((item) => [item.file, item.score])
+  );
+  const currentModuleScores = new Map(
+    current.analysis.risk.moduleScores.map((item) => [item.module, item.score])
+  );
+  const baselineModuleScores = new Map(
+    baseline.analysis.risk.moduleScores.map((item) => [item.module, item.score])
+  );
+  const currentHotspots = current.analysis.risk.hotspots.slice(0, 10).map((item) => item.file);
+  const baselineHotspots = baseline.analysis.risk.hotspots.slice(0, 10).map((item) => item.file);
+  const currentCycles = current.analysis.structural.cycles.map((cycle) => cycleKey(cycle.nodes));
+  const baselineCycles = baseline.analysis.structural.cycles.map((cycle) => cycleKey(cycle.nodes));
+  const currentExternal = current.analysis.external.available ? current.analysis.external : {
+    highRiskDependencies: [],
+    singleMaintainerDependencies: [],
+    abandonedDependencies: []
+  };
+  const baselineExternal = baseline.analysis.external.available ? baseline.analysis.external : {
+    highRiskDependencies: [],
+    singleMaintainerDependencies: [],
+    abandonedDependencies: []
+  };
+  const highRisk = diffSets(currentExternal.highRiskDependencies, baselineExternal.highRiskDependencies);
+  const singleMaintainer = diffSets(
+    currentExternal.singleMaintainerDependencies,
+    baselineExternal.singleMaintainerDependencies
+  );
+  const abandoned = diffSets(currentExternal.abandonedDependencies, baselineExternal.abandonedDependencies);
+  const hotspots = diffSets(currentHotspots, baselineHotspots);
+  const cycles = diffSets(currentCycles, baselineCycles);
+  return {
+    repositoryScoreDelta: round45(current.analysis.risk.repositoryScore - baseline.analysis.risk.repositoryScore),
+    normalizedScoreDelta: round45(current.analysis.risk.normalizedScore - baseline.analysis.risk.normalizedScore),
+    fileRiskChanges: diffScoreMap(currentFileScores, baselineFileScores),
+    moduleRiskChanges: diffScoreMap(currentModuleScores, baselineModuleScores),
+    newHotspots: hotspots.added,
+    resolvedHotspots: hotspots.removed,
+    newCycles: cycles.added,
+    resolvedCycles: cycles.removed,
+    externalChanges: {
+      highRiskAdded: highRisk.added,
+      highRiskRemoved: highRisk.removed,
+      singleMaintainerAdded: singleMaintainer.added,
+      singleMaintainerRemoved: singleMaintainer.removed,
+      abandonedAdded: abandoned.added,
+      abandonedRemoved: abandoned.removed
+    }
+  };
+};
+var findTraceTarget = (snapshot, targetType, targetId) => snapshot.trace?.targets.find(
+  (target) => target.targetType === targetType && target.targetId === targetId
+);
+var toRenderedFactors = (target) => {
+  if (target === void 0) {
+    return [];
+  }
+  return [...target.factors].sort((a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)).slice(0, 4).map((factor) => ({
+    id: factor.factorId,
+    label: factorLabel(factor.factorId),
+    contribution: round45(factor.contribution),
+    confidence: round45(factor.confidence),
+    evidence: summarizeEvidence(factor)
+  }));
+};
+var suggestedActions = (target) => {
+  if (target === void 0) {
+    return [];
+  }
+  const actions = [];
+  for (const lever of target.reductionLevers) {
+    switch (lever.factorId) {
+      case "file.evolution":
+      case "repository.evolution":
+        actions.push("Reduce recent churn and volatile edit frequency in this area.");
+        break;
+      case "file.structural":
+      case "repository.structural":
+        actions.push("Reduce fan-in/fan-out concentration and simplify deep dependency paths.");
+        break;
+      case "file.composite.interactions":
+      case "repository.composite.interactions":
+        actions.push("Stabilize central files before concurrent structural changes.");
+        break;
+      case "file.external":
+      case "repository.external":
+        actions.push("Review external dependency pressure for this hotspot.");
+        break;
+      default:
+        actions.push(`Reduce ${factorLabel(lever.factorId).toLowerCase()} influence.`);
+        break;
+    }
+  }
+  return [...new Set(actions)].slice(0, 3);
+};
+var hotspotItems = (snapshot) => snapshot.analysis.risk.hotspots.slice(0, 10).map((hotspot) => {
+  const fileScore = snapshot.analysis.risk.fileScores.find((item) => item.file === hotspot.file);
+  const traceTarget = findTraceTarget(snapshot, "file", hotspot.file);
+  const factors = toRenderedFactors(traceTarget);
+  return {
+    target: hotspot.file,
+    score: hotspot.score,
+    normalizedScore: fileScore?.normalizedScore ?? round45(hotspot.score / 100),
+    topFactors: factors,
+    suggestedActions: suggestedActions(traceTarget),
+    biggestLevers: (traceTarget?.reductionLevers ?? []).slice(0, 3).map((lever) => `${factorLabel(lever.factorId)} (${lever.estimatedImpact})`)
+  };
+});
+var repositoryConfidence = (snapshot) => {
+  const target = findTraceTarget(snapshot, "repository", snapshot.analysis.structural.targetPath);
+  if (target === void 0 || target.factors.length === 0) {
+    return null;
+  }
+  const weight = target.factors.reduce((sum, factor) => sum + factor.contribution, 0);
+  if (weight <= 0) {
+    return null;
+  }
+  const weighted = target.factors.reduce(
+    (sum, factor) => sum + factor.confidence * factor.contribution,
+    0
+  );
+  return round45(weighted / weight);
+};
+var createReport = (snapshot, diff) => {
+  const external = snapshot.analysis.external;
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repository: {
+      targetPath: snapshot.analysis.structural.targetPath,
+      repositoryScore: snapshot.analysis.risk.repositoryScore,
+      normalizedScore: snapshot.analysis.risk.normalizedScore,
+      riskTier: toRiskTier(snapshot.analysis.risk.repositoryScore),
+      confidence: repositoryConfidence(snapshot)
+    },
+    hotspots: hotspotItems(snapshot),
+    structural: {
+      cycleCount: snapshot.analysis.structural.metrics.cycleCount,
+      cycles: snapshot.analysis.structural.cycles.map(
+        (cycle) => [...cycle.nodes].sort((a, b) => a.localeCompare(b)).join(" -> ")
+      ),
+      fragileClusters: snapshot.analysis.risk.fragileClusters.map((cluster) => ({
+        id: cluster.id,
+        kind: cluster.kind,
+        score: cluster.score,
+        files: [...cluster.files].sort((a, b) => a.localeCompare(b))
+      }))
+    },
+    external: !external.available ? {
+      available: false,
+      reason: external.reason
+    } : {
+      available: true,
+      highRiskDependencies: [...external.highRiskDependencies].sort((a, b) => a.localeCompare(b)),
+      highRiskDevelopmentDependencies: [...external.highRiskDevelopmentDependencies].sort((a, b) => a.localeCompare(b)),
+      singleMaintainerDependencies: [...external.singleMaintainerDependencies].sort((a, b) => a.localeCompare(b)),
+      abandonedDependencies: [...external.abandonedDependencies].sort((a, b) => a.localeCompare(b))
+    },
+    appendix: {
+      snapshotSchemaVersion: snapshot.schemaVersion,
+      riskModelVersion: snapshot.riskModelVersion,
+      timestamp: snapshot.generatedAt,
+      normalization: "Scores are deterministic 0-100 outputs from risk-engine normalized factors and interaction terms.",
+      ...snapshot.analysisConfig === void 0 ? {} : { analysisConfig: snapshot.analysisConfig }
+    },
+    ...diff === void 0 ? {} : { diff }
+  };
+};
+var renderTextDiff = (report) => {
+  if (report.diff === void 0) {
+    return [];
+  }
+  return [
+    "",
+    "Diff",
+    `  repositoryScoreDelta: ${report.diff.repositoryScoreDelta}`,
+    `  normalizedScoreDelta: ${report.diff.normalizedScoreDelta}`,
+    `  newHotspots: ${report.diff.newHotspots.join(", ") || "none"}`,
+    `  resolvedHotspots: ${report.diff.resolvedHotspots.join(", ") || "none"}`,
+    `  newCycles: ${report.diff.newCycles.join(", ") || "none"}`,
+    `  resolvedCycles: ${report.diff.resolvedCycles.join(", ") || "none"}`
+  ];
+};
+var renderTextReport = (report) => {
+  const lines = [];
+  lines.push("Repository Summary");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  repositoryScore: ${report.repository.repositoryScore}`);
+  lines.push(`  normalizedScore: ${report.repository.normalizedScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push(`  confidence: ${report.repository.confidence ?? "n/a"}`);
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+    for (const factor of hotspot.topFactors) {
+      lines.push(
+        `    factor: ${factor.label} contribution=${factor.contribution} confidence=${factor.confidence}`
+      );
+      lines.push(`    evidence: ${factor.evidence}`);
+    }
+    lines.push(`    actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+    lines.push(`    levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("Structural Observations");
+  lines.push(`  cycleCount: ${report.structural.cycleCount}`);
+  lines.push(`  cycles: ${report.structural.cycles.join(" ; ") || "none"}`);
+  lines.push(`  fragileClusters: ${report.structural.fragileClusters.length}`);
+  lines.push("");
+  lines.push("External Exposure");
+  if (!report.external.available) {
+    lines.push(`  unavailable: ${report.external.reason}`);
+  } else {
+    lines.push(`  highRiskDependencies: ${report.external.highRiskDependencies.join(", ") || "none"}`);
+    lines.push(
+      `  highRiskDevelopmentDependencies: ${report.external.highRiskDevelopmentDependencies.join(", ") || "none"}`
+    );
+    lines.push(
+      `  singleMaintainerDependencies: ${report.external.singleMaintainerDependencies.join(", ") || "none"}`
+    );
+    lines.push(`  abandonedDependencies: ${report.external.abandonedDependencies.join(", ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("Appendix");
+  lines.push(`  snapshotSchemaVersion: ${report.appendix.snapshotSchemaVersion}`);
+  lines.push(`  riskModelVersion: ${report.appendix.riskModelVersion}`);
+  lines.push(`  timestamp: ${report.appendix.timestamp}`);
+  lines.push(`  normalization: ${report.appendix.normalization}`);
+  lines.push(...renderTextDiff(report));
+  return lines.join("\n");
+};
+var renderMarkdownDiff = (report) => {
+  if (report.diff === void 0) {
+    return [];
+  }
+  return [
+    "",
+    "## Diff",
+    `- repositoryScoreDelta: \`${report.diff.repositoryScoreDelta}\``,
+    `- normalizedScoreDelta: \`${report.diff.normalizedScoreDelta}\``,
+    `- newHotspots: ${report.diff.newHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- resolvedHotspots: ${report.diff.resolvedHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- newCycles: ${report.diff.newCycles.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- resolvedCycles: ${report.diff.resolvedCycles.map((item) => `\`${item}\``).join(", ") || "none"}`
+  ];
+};
+var renderMarkdownReport = (report) => {
+  const lines = [];
+  lines.push("# CodeSentinel Report");
+  lines.push("");
+  lines.push("## Repository Summary");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- repositoryScore: \`${report.repository.repositoryScore}\``);
+  lines.push(`- normalizedScore: \`${report.repository.normalizedScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push(`- confidence: \`${report.repository.confidence ?? "n/a"}\``);
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots) {
+    lines.push(`- **${hotspot.target}** (score: \`${hotspot.score}\`)`);
+    lines.push(`  - Top factors:`);
+    for (const factor of hotspot.topFactors) {
+      lines.push(
+        `  - ${factor.label}: contribution=\`${factor.contribution}\`, confidence=\`${factor.confidence}\``
+      );
+      lines.push(`  - evidence: \`${factor.evidence}\``);
+    }
+    lines.push(`  - Suggested actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+    lines.push(`  - Biggest levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("## Structural Observations");
+  lines.push(`- cycles detected: \`${report.structural.cycleCount}\``);
+  lines.push(`- cycles: ${report.structural.cycles.map((cycle) => `\`${cycle}\``).join(", ") || "none"}`);
+  lines.push(`- fragile clusters: \`${report.structural.fragileClusters.length}\``);
+  lines.push("");
+  lines.push("## External Exposure Summary");
+  if (!report.external.available) {
+    lines.push(`- unavailable: \`${report.external.reason}\``);
+  } else {
+    lines.push(`- high-risk dependencies: ${report.external.highRiskDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`);
+    lines.push(
+      `- high-risk development dependencies: ${report.external.highRiskDevelopmentDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`
+    );
+    lines.push(
+      `- single maintainer dependencies: ${report.external.singleMaintainerDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`
+    );
+    lines.push(`- abandoned dependencies: ${report.external.abandonedDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("## Appendix");
+  lines.push(`- snapshot schema: \`${report.appendix.snapshotSchemaVersion}\``);
+  lines.push(`- risk model version: \`${report.appendix.riskModelVersion}\``);
+  lines.push(`- timestamp: \`${report.appendix.timestamp}\``);
+  lines.push(`- normalization: ${report.appendix.normalization}`);
+  lines.push(...renderMarkdownDiff(report));
+  return lines.join("\n");
+};
+var createSnapshot = (input) => ({
+  schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+  generatedAt: input.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+  riskModelVersion: RISK_MODEL_VERSION,
+  source: {
+    targetPath: input.analysis.structural.targetPath
+  },
+  analysis: input.analysis,
+  ...input.trace === void 0 ? {} : { trace: input.trace },
+  ...input.analysisConfig === void 0 ? {} : { analysisConfig: input.analysisConfig }
+});
+var parseSnapshot = (raw) => {
+  const parsed = JSON.parse(raw);
+  if (parsed.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+    throw new Error("unsupported_snapshot_schema");
+  }
+  if (typeof parsed.generatedAt !== "string") {
+    throw new Error("invalid_snapshot_generated_at");
+  }
+  if (parsed.analysis === void 0 || parsed.analysis === null) {
+    throw new Error("invalid_snapshot_analysis");
+  }
+  if (parsed.source === void 0 || typeof parsed.source.targetPath !== "string") {
+    throw new Error("invalid_snapshot_source");
+  }
+  return parsed;
+};
+var formatReport = (report, format) => {
+  if (format === "json") {
+    return JSON.stringify(report, null, 2);
+  }
+  if (format === "md") {
+    return renderMarkdownReport(report);
+  }
+  return renderTextReport(report);
+};
+
+// src/application/run-report-command.ts
+var buildSnapshot = async (inputPath, authorIdentityMode, includeTrace, logger) => {
+  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: includeTrace });
+  const summary = {
+    ...analysisInputs,
+    risk: evaluation.summary
+  };
+  return createSnapshot({
+    analysis: summary,
+    ...evaluation.trace === void 0 ? {} : { trace: evaluation.trace },
+    analysisConfig: {
+      authorIdentityMode,
+      includeTrace
+    }
+  });
+};
+var runReportCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
+  logger.info("building analysis snapshot");
+  const current = await buildSnapshot(inputPath, authorIdentityMode, options.includeTrace, logger);
+  if (options.snapshotPath !== void 0) {
+    await writeFile(options.snapshotPath, JSON.stringify(current, null, 2), "utf8");
+    logger.info(`snapshot written: ${options.snapshotPath}`);
+  }
+  let report;
+  if (options.comparePath === void 0) {
+    report = createReport(current);
+  } else {
+    logger.info(`loading baseline snapshot: ${options.comparePath}`);
+    const baselineRaw = await readFile(options.comparePath, "utf8");
+    const baseline = parseSnapshot(baselineRaw);
+    const diff = compareSnapshots(current, baseline);
+    report = createReport(current, diff);
+  }
+  const rendered = formatReport(report, options.format);
+  if (options.outputPath !== void 0) {
+    await writeFile(options.outputPath, rendered, "utf8");
+    logger.info(`report written: ${options.outputPath}`);
+  }
+  return { report, rendered };
+};
+
+// src/application/run-explain-command.ts
+var selectTargets = (trace, summary, options) => {
+  if (options.file !== void 0) {
+    const normalized = options.file.replaceAll("\\", "/");
+    return trace.targets.filter(
+      (target) => target.targetType === "file" && target.targetId === normalized
+    );
+  }
+  if (options.module !== void 0) {
+    return trace.targets.filter(
+      (target) => target.targetType === "module" && target.targetId === options.module
+    );
+  }
+  const top = Math.max(1, options.top);
+  const topFiles = summary.risk.hotspots.slice(0, top).map((entry) => entry.file);
+  const fileSet = new Set(topFiles);
+  return trace.targets.filter(
+    (target) => target.targetType === "repository" || target.targetType === "file" && fileSet.has(target.targetId)
+  );
+};
+var runExplainCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
+  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  logger.info("computing explainable risk summary");
+  const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: true });
+  if (evaluation.trace === void 0) {
+    throw new Error("risk trace unavailable");
+  }
+  const summary = {
+    ...analysisInputs,
+    risk: evaluation.summary
+  };
+  logger.info(`explanation completed (repositoryScore=${summary.risk.repositoryScore})`);
+  return {
+    summary,
+    trace: evaluation.trace,
+    selectedTargets: selectTargets(evaluation.trace, summary, options)
+  };
 };
 
 // src/index.ts
@@ -3340,6 +4566,38 @@ program.command("analyze").argument("[path]", "path to the project to analyze").
 `);
   }
 );
+program.command("explain").argument("[path]", "path to the project to analyze").addOption(
+  new Option(
+    "--author-identity <mode>",
+    "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
+  ).choices(["likely_merge", "strict_email"]).default("likely_merge")
+).addOption(
+  new Option(
+    "--log-level <level>",
+    "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
+  ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
+).option("--file <path>", "explain a specific file target").option("--module <name>", "explain a specific module target").option("--top <count>", "number of top hotspots to explain when no target is selected", "5").addOption(
+  new Option("--format <mode>", "output format: text, json, md").choices(["text", "json", "md"]).default("text")
+).action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const top = Number.parseInt(options.top, 10);
+    const explainOptions = {
+      ...options.file === void 0 ? {} : { file: options.file },
+      ...options.module === void 0 ? {} : { module: options.module },
+      top: Number.isFinite(top) ? top : 5,
+      format: options.format
+    };
+    const result = await runExplainCommand(
+      path,
+      options.authorIdentity,
+      explainOptions,
+      logger
+    );
+    process.stdout.write(`${formatExplainOutput(result, options.format)}
+`);
+  }
+);
 program.command("dependency-risk").argument("<dependency>", "dependency spec to evaluate (for example: react or react@19.0.0)").addOption(
   new Option(
     "--log-level <level>",
@@ -3373,6 +4631,39 @@ program.command("dependency-risk").argument("<dependency>", "dependency spec to
 `);
   }
 );
+program.command("report").argument("[path]", "path to the project to analyze").addOption(
+  new Option(
+    "--author-identity <mode>",
+    "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
+  ).choices(["likely_merge", "strict_email"]).default("likely_merge")
+).addOption(
+  new Option(
+    "--log-level <level>",
+    "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
+  ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
+).addOption(
+  new Option("--format <mode>", "output format: text, json, md").choices(["text", "json", "md"]).default("text")
+).option("--output <path>", "write rendered report to a file path").option("--compare <baseline>", "compare against a baseline snapshot JSON file").option("--snapshot <path>", "write current snapshot JSON artifact").option("--no-trace", "disable trace embedding in generated snapshot").action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const result = await runReportCommand(
+      path,
+      options.authorIdentity,
+      {
+        format: options.format,
+        ...options.output === void 0 ? {} : { outputPath: options.output },
+        ...options.compare === void 0 ? {} : { comparePath: options.compare },
+        ...options.snapshot === void 0 ? {} : { snapshotPath: options.snapshot },
+        includeTrace: options.trace
+      },
+      logger
+    );
+    if (options.output === void 0) {
+      process.stdout.write(`${result.rendered}
+`);
+    }
+  }
+);
 if (process.argv.length <= 2) {
   program.outputHelp();
   process.exit(0);