@getcodesentinel/codesentinel 1.6.5 → 1.7.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,60 @@ 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-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 +4098,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>",