@getcodesentinel/codesentinel 1.12.1 → 1.14.0

package/dist/index.js

@@ -1524,9 +1524,7 @@ var compareSnapshots = (current, baseline) => {
   const hotspots = diffSets(currentHotspots, baselineHotspots);
   const cycles = diffSets(currentCycles, baselineCycles);
   return {
-    repositoryScoreDelta: round43(
-      current.analysis.risk.repositoryScore - baseline.analysis.risk.repositoryScore
-    ),
+    riskScoreDelta: round43(current.analysis.risk.riskScore - baseline.analysis.risk.riskScore),
     normalizedScoreDelta: round43(
       current.analysis.risk.normalizedScore - baseline.analysis.risk.normalizedScore
     ),
@@ -1652,9 +1650,9 @@ var createReport = (snapshot, diff) => {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     repository: {
       targetPath: snapshot.analysis.structural.targetPath,
-      repositoryScore: snapshot.analysis.risk.repositoryScore,
+      riskScore: snapshot.analysis.risk.riskScore,
       normalizedScore: snapshot.analysis.risk.normalizedScore,
-      riskTier: toRiskTier(snapshot.analysis.risk.repositoryScore),
+      riskTier: toRiskTier(snapshot.analysis.risk.riskScore),
       confidence: repositoryConfidence(snapshot),
       dimensionScores: repositoryDimensionScores(snapshot)
     },
@@ -1706,7 +1704,7 @@ var renderTextDiff = (report) => {
   return [
     "",
     "Diff",
-    `  repositoryScoreDelta: ${report.diff.repositoryScoreDelta}`,
+    `  riskScoreDelta: ${report.diff.riskScoreDelta}`,
     `  normalizedScoreDelta: ${report.diff.normalizedScoreDelta}`,
     `  newHotspots: ${report.diff.newHotspots.join(", ") || "none"}`,
     `  resolvedHotspots: ${report.diff.resolvedHotspots.join(", ") || "none"}`,
@@ -1718,7 +1716,7 @@ var renderTextReport = (report) => {
   const lines = [];
   lines.push("Repository Summary");
   lines.push(`  target: ${report.repository.targetPath}`);
-  lines.push(`  repositoryScore: ${report.repository.repositoryScore}`);
+  lines.push(`  riskScore: ${report.repository.riskScore}`);
   lines.push(`  normalizedScore: ${report.repository.normalizedScore}`);
   lines.push(`  riskTier: ${report.repository.riskTier}`);
   lines.push(`  confidence: ${report.repository.confidence ?? "n/a"}`);
@@ -1738,8 +1736,7 @@ var renderTextReport = (report) => {
       );
       lines.push(`    evidence: ${factor.evidence}`);
     }
-    lines.push(`    actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
-    lines.push(`    levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+    lines.push(`    priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
   }
   lines.push("");
   lines.push("Structural Observations");
@@ -1780,7 +1777,7 @@ var renderMarkdownDiff = (report) => {
   return [
     "",
     "## Diff",
-    `- repositoryScoreDelta: \`${report.diff.repositoryScoreDelta}\``,
+    `- riskScoreDelta: \`${report.diff.riskScoreDelta}\``,
     `- normalizedScoreDelta: \`${report.diff.normalizedScoreDelta}\``,
     `- newHotspots: ${report.diff.newHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
     `- resolvedHotspots: ${report.diff.resolvedHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
@@ -1794,7 +1791,7 @@ var renderMarkdownReport = (report) => {
   lines.push("");
   lines.push("## Repository Summary");
   lines.push(`- target: \`${report.repository.targetPath}\``);
-  lines.push(`- repositoryScore: \`${report.repository.repositoryScore}\``);
+  lines.push(`- riskScore: \`${report.repository.riskScore}\``);
   lines.push(`- normalizedScore: \`${report.repository.normalizedScore}\``);
   lines.push(`- riskTier: \`${report.repository.riskTier}\``);
   lines.push(`- confidence: \`${report.repository.confidence ?? "n/a"}\``);
@@ -1815,8 +1812,7 @@ var renderMarkdownReport = (report) => {
       );
       lines.push(`  - evidence: \`${factor.evidence}\``);
     }
-    lines.push(`  - Suggested actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
-    lines.push(`  - Biggest levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+    lines.push(`  - Priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
   }
   lines.push("");
   lines.push("## Structural Observations");
@@ -1973,7 +1969,7 @@ var evaluateGates = (input) => {
   const evaluatedGates = [];
   if (config.maxRepoScore !== void 0) {
     evaluatedGates.push("max-repo-score");
-    const current = input.current.analysis.risk.repositoryScore;
+    const current = input.current.analysis.risk.riskScore;
     if (current > config.maxRepoScore) {
       violations.push(
         makeViolation(
@@ -1981,7 +1977,7 @@ var evaluateGates = (input) => {
           "error",
           `Repository score ${current} exceeds configured max ${config.maxRepoScore}.`,
           [input.current.analysis.structural.targetPath],
-          [{ kind: "repository_metric", metric: "repositoryScore" }]
+          [{ kind: "repository_metric", metric: "riskScore" }]
         )
       );
     }
@@ -2093,7 +2089,7 @@ var renderCheckText = (snapshot, result) => {
   const lines = [];
   lines.push("CodeSentinel Check");
   lines.push(`target: ${snapshot.analysis.structural.targetPath}`);
-  lines.push(`repositoryScore: ${snapshot.analysis.risk.repositoryScore}`);
+  lines.push(`riskScore: ${snapshot.analysis.risk.riskScore}`);
   lines.push(`evaluatedGates: ${result.evaluatedGates.join(", ") || "none"}`);
   lines.push(`violations: ${result.violations.length}`);
   lines.push(`exitCode: ${result.exitCode}`);
@@ -2112,7 +2108,7 @@ var renderCheckMarkdown = (snapshot, result) => {
   const lines = [];
   lines.push("## CodeSentinel CI Summary");
   lines.push(`- target: \`${snapshot.analysis.structural.targetPath}\``);
-  lines.push(`- repositoryScore: \`${snapshot.analysis.risk.repositoryScore}\``);
+  lines.push(`- riskScore: \`${snapshot.analysis.risk.riskScore}\``);
   lines.push(
     `- evaluatedGates: ${result.evaluatedGates.map((item) => `\`${item}\``).join(", ") || "none"}`
   );
@@ -2463,6 +2459,7 @@ var resolveAutoBaselineRef = async (input) => {
 
 // src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
+import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname2, resolve as resolve5 } from "path";
 import { fileURLToPath } from "url";
 
@@ -2495,7 +2492,7 @@ var createSummaryShape = (summary) => ({
     reason: summary.external.reason
   },
   risk: {
-    repositoryScore: summary.risk.repositoryScore,
+    riskScore: summary.risk.riskScore,
     normalizedScore: summary.risk.normalizedScore,
     hotspotsTop: summary.risk.hotspots.slice(0, 5).map((hotspot) => ({
       file: hotspot.file,
@@ -2546,6 +2543,7 @@ var formatFactorLabel = (factorId) => factorLabelById2[factorId] ?? factorId;
 var formatNumber = (value) => value === null || value === void 0 ? "n/a" : `${value}`;
 var formatDimension = (value) => value === null ? "n/a" : `${value}`;
 var formatFactorSummary = (factor) => `${formatFactorLabel(factor.factorId)} (+${factor.contribution}, confidence=${factor.confidence})`;
+var formatFactorContribution = (factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`;
 var formatFactorEvidence = (factor) => {
   if (factor.factorId === "repository.structural") {
     return `structural dimension=${formatNumber(factor.rawMetrics["structuralDimension"])}`;
@@ -2560,7 +2558,7 @@ var formatFactorEvidence = (factor) => {
     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"])}`;
+    return `fanIn=${formatNumber(factor.rawMetrics["fanIn"])}, fanOut=${formatNumber(factor.rawMetrics["fanOut"])}, depth=${formatNumber(factor.rawMetrics["depth"])}, inCycle=${formatNumber(factor.rawMetrics["cycleParticipation"])}, structuralAttenuation=${formatNumber(factor.rawMetrics["structuralAttenuation"])}`;
   }
   if (factor.factorId === "file.evolution") {
     return `commitCount=${formatNumber(factor.rawMetrics["commitCount"])}, churnTotal=${formatNumber(factor.rawMetrics["churnTotal"])}, recentVolatility=${formatNumber(factor.rawMetrics["recentVolatility"])}`;
@@ -2667,8 +2665,8 @@ var renderText = (payload) => {
   const dimensionScores = repositoryDimensionScores2(repositoryTarget);
   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(`riskScore: ${payload.summary.risk.riskScore}`);
+  lines.push(`riskBand: ${toRiskBand(payload.summary.risk.riskScore)}`);
   lines.push(`selectedTargets: ${payload.selectedTargets.length}`);
   lines.push("dimensionScores:");
   lines.push(`  structural: ${formatDimension(dimensionScores.structural)}`);
@@ -2678,20 +2676,15 @@ var renderText = (payload) => {
   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"}`
+    `  key drivers: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
   );
   lines.push(
-    `  dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
+    `  contributions: ${repositoryTopFactors.map(formatFactorContribution).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(" ")}`
+    `  interaction effects: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
   );
+  lines.push(`  priority actions: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`);
   lines.push("");
   for (const target of payload.selectedTargets) {
     lines.push(renderTargetText(target));
@@ -2707,8 +2700,8 @@ var renderMarkdown = (payload) => {
   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(`- riskScore: \`${payload.summary.risk.riskScore}\``);
+  lines.push(`- riskBand: \`${toRiskBand(payload.summary.risk.riskScore)}\``);
   lines.push(`- selectedTargets: \`${payload.selectedTargets.length}\``);
   lines.push("");
   lines.push("## Dimension Scores (0-100)");
@@ -2719,25 +2712,19 @@ var renderMarkdown = (payload) => {
   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"}`
+    `- key drivers: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
   );
   lines.push(
-    `- intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
+    `- contributions: ${repositoryTopFactors.map(formatFactorContribution).join(", ") || "insufficient data"}`
   );
   lines.push(
-    `- what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+    `- interaction effects: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
   );
+  lines.push(`- priority actions: ${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(
@@ -4308,6 +4295,17 @@ var DEFAULT_RISK_ENGINE_CONFIG = {
   externalDimension: {
     topDependencyPercentile: 0.85,
     dependencyDepthHalfLife: 6
+  },
+  // Reduce false positives for thin aggregation hubs (for example, barrel/index re-export files)
+  // that are structurally central but have low churn density and no cycle participation.
+  aggregatorAttenuation: {
+    enabled: true,
+    minFanIn: 6,
+    minFanOut: 4,
+    minCommitCount: 4,
+    maxChurnPerCommit: 24,
+    maxChurnPerDependency: 10,
+    maxStructuralReduction: 0.3
   }
 };
 var toUnitInterval = (value) => Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
@@ -4400,6 +4398,35 @@ var normalizeWithScale = (value, scale) => {
   return toUnitInterval((value - scale.lower) / (scale.upper - scale.lower));
 };
 var normalizePath2 = (path) => path.replaceAll("\\", "/");
+var computeAggregatorAttenuation = (input) => {
+  const { fanIn, fanOut, inCycle, evolutionMetrics, config } = input;
+  if (!config.enabled || inCycle > 0) {
+    return 1;
+  }
+  if (fanIn < config.minFanIn || fanOut < config.minFanOut) {
+    return 1;
+  }
+  if (evolutionMetrics === void 0 || evolutionMetrics.commitCount < config.minCommitCount) {
+    return 1;
+  }
+  const churnPerCommit = evolutionMetrics.churnTotal / Math.max(1, evolutionMetrics.commitCount);
+  const churnPerDependency = evolutionMetrics.churnTotal / Math.max(1, fanOut);
+  if (churnPerCommit > config.maxChurnPerCommit || churnPerDependency > config.maxChurnPerDependency) {
+    return 1;
+  }
+  const fanInSignal = toUnitInterval((fanIn - config.minFanIn) / Math.max(1, config.minFanIn));
+  const fanOutSignal = toUnitInterval((fanOut - config.minFanOut) / Math.max(1, config.minFanOut));
+  const lowChurnPerCommitSignal = 1 - toUnitInterval(churnPerCommit / config.maxChurnPerCommit);
+  const lowChurnPerDependencySignal = 1 - toUnitInterval(churnPerDependency / config.maxChurnPerDependency);
+  const attenuationConfidence = average([
+    fanInSignal,
+    fanOutSignal,
+    lowChurnPerCommitSignal,
+    lowChurnPerDependencySignal
+  ]);
+  const reduction = toUnitInterval(config.maxStructuralReduction) * attenuationConfidence;
+  return round45(toUnitInterval(1 - reduction));
+};
 var dependencySignalWeights = {
   single_maintainer: 0.3,
   abandoned: 0.3,
@@ -4824,10 +4851,10 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     const fanOutRisk = normalizeWithScale(logScale(file.fanOut), fanOutScale);
     const depthRisk = normalizeWithScale(file.depth, depthScale);
     const structuralWeights = config.structuralFactorWeights;
-    const structuralFactor = toUnitInterval(
+    const structuralFactorRaw = toUnitInterval(
       fanInRisk * structuralWeights.fanIn + fanOutRisk * structuralWeights.fanOut + depthRisk * structuralWeights.depth + inCycle * structuralWeights.cycleParticipation
     );
-    const structuralCentrality = toUnitInterval((fanInRisk + fanOutRisk) / 2);
+    const structuralCentralityRaw = toUnitInterval((fanInRisk + fanOutRisk) / 2);
     let evolutionFactor = 0;
     let frequencyRisk = 0;
     let churnRisk = 0;
@@ -4854,6 +4881,15 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         frequencyRisk * evolutionWeights.frequency + churnRisk * evolutionWeights.churn + volatilityRisk * evolutionWeights.recentVolatility + ownershipConcentrationRisk * evolutionWeights.ownershipConcentration + busFactorRisk * evolutionWeights.busFactorRisk
       );
     }
+    const structuralAttenuation = computeAggregatorAttenuation({
+      fanIn: file.fanIn,
+      fanOut: file.fanOut,
+      inCycle,
+      evolutionMetrics,
+      config: config.aggregatorAttenuation
+    });
+    const structuralFactor = toUnitInterval(structuralFactorRaw * structuralAttenuation);
+    const structuralCentrality = toUnitInterval(structuralCentralityRaw * structuralAttenuation);
     const dependencyAffinity = toUnitInterval(structuralCentrality * 0.6 + evolutionFactor * 0.4);
     const externalFactor = external.available ? toUnitInterval(dependencyComputation.repositoryExternalPressure * dependencyAffinity) : 0;
     const structuralBase = structuralFactor * dimensionWeights.structural;
@@ -4898,7 +4934,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         topAuthorShare: evolutionMetrics?.topAuthorShare ?? null,
         busFactor: evolutionMetrics?.busFactor ?? null,
         dependencyAffinity: round45(dependencyAffinity),
-        repositoryExternalPressure: round45(dependencyComputation.repositoryExternalPressure)
+        repositoryExternalPressure: round45(dependencyComputation.repositoryExternalPressure),
+        structuralAttenuation: round45(structuralAttenuation)
       },
       normalizedMetrics: {
         fanInRisk: round45(fanInRisk),
@@ -4941,7 +4978,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
             fanIn: context.rawMetrics.fanIn,
             fanOut: context.rawMetrics.fanOut,
             depth: context.rawMetrics.depth,
-            cycleParticipation: context.rawMetrics.cycleParticipation
+            cycleParticipation: context.rawMetrics.cycleParticipation,
+            structuralAttenuation: context.rawMetrics.structuralAttenuation
           },
           normalizedMetrics: {
             fanInRisk: context.normalizedMetrics.fanInRisk,
@@ -5227,9 +5265,9 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     criticalInstability * config.interactionWeights.centralInstability,
     dependencyAmplification * config.interactionWeights.dependencyAmplification
   ]);
-  const repositoryScore = round45(repositoryNormalizedScore * 100);
+  const riskScore = round45(repositoryNormalizedScore * 100);
   if (collector !== void 0) {
-    const repositoryFactors = buildFactorTraces(repositoryScore, [
+    const repositoryFactors = buildFactorTraces(riskScore, [
       {
         factorId: "repository.structural",
         family: "structural",
@@ -5292,14 +5330,14 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
       buildTargetTrace(
         "repository",
         structural.targetPath,
-        repositoryScore,
+        riskScore,
         repositoryNormalizedScore,
         repositoryFactors
       )
     );
   }
   return {
-    repositoryScore,
+    riskScore,
     normalizedScore: round45(repositoryNormalizedScore),
     hotspots,
     fragileClusters,
@@ -5390,6 +5428,10 @@ var mergeConfig = (overrides) => {
     externalDimension: {
       ...DEFAULT_RISK_ENGINE_CONFIG.externalDimension,
       ...overrides.externalDimension
+    },
+    aggregatorAttenuation: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.aggregatorAttenuation,
+      ...overrides.aggregatorAttenuation
     }
   };
 };
@@ -5421,6 +5463,21 @@ var evaluateRepositoryRisk = (input, options = {}) => {
 
 // src/application/run-analyze-command.ts
 var resolveTargetPath = (inputPath, cwd) => resolve3(cwd, inputPath ?? ".");
+var riskProfileConfig = {
+  default: void 0,
+  personal: {
+    evolutionFactorWeights: {
+      frequency: 0.26,
+      churn: 0.24,
+      recentVolatility: 0.2,
+      ownershipConcentration: 0.08,
+      busFactorRisk: 0.04
+    }
+  }
+};
+var resolveRiskConfigForProfile = (riskProfile) => {
+  return riskProfileConfig[riskProfile ?? "default"];
+};
 var createExternalProgressReporter = (logger) => {
   let lastLoggedProgress = 0;
   return (event) => {
@@ -5588,8 +5645,12 @@ var runAnalyzeCommand = async (inputPath, authorIdentityMode, options = {}, logg
     logger
   );
   logger.info("computing risk summary");
-  const risk = computeRepositoryRiskSummary(analysisInputs);
-  logger.info(`analysis completed (repositoryScore=${risk.repositoryScore})`);
+  const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
+  const risk = computeRepositoryRiskSummary({
+    ...analysisInputs,
+    ...riskConfig === void 0 ? {} : { config: riskConfig }
+  });
+  logger.info(`analysis completed (riskScore=${risk.riskScore})`);
   return {
     ...analysisInputs,
     risk
@@ -5609,7 +5670,14 @@ var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logge
     },
     logger
   );
-  const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: options.includeTrace });
+  const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
+  const evaluation = evaluateRepositoryRisk(
+    {
+      ...analysisInputs,
+      ...riskConfig === void 0 ? {} : { config: riskConfig }
+    },
+    { explain: options.includeTrace }
+  );
   const summary = {
     ...analysisInputs,
     risk: evaluation.summary
@@ -5620,6 +5688,7 @@ var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logge
     analysisConfig: {
       authorIdentityMode,
       includeTrace: options.includeTrace,
+      riskProfile: options.riskProfile ?? "default",
       recentWindowDays: analysisInputs.evolution.available ? analysisInputs.evolution.metrics.recentWindowDays : options.recentWindowDays ?? null
     }
   });
@@ -5654,6 +5723,7 @@ var runCheckCommand = async (inputPath, authorIdentityMode, options, logger = cr
     authorIdentityMode,
     {
       includeTrace: options.includeTrace,
+      ...options.riskProfile === void 0 ? {} : { riskProfile: options.riskProfile },
       ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
     },
     logger
@@ -5722,6 +5792,7 @@ var runCiCommand = async (inputPath, authorIdentityMode, options, logger = creat
     authorIdentityMode,
     {
       includeTrace: options.includeTrace,
+      ...options.riskProfile === void 0 ? {} : { riskProfile: options.riskProfile },
       ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
     },
     logger
@@ -5780,6 +5851,7 @@ var runCiCommand = async (inputPath, authorIdentityMode, options, logger = creat
             authorIdentityMode,
             {
               includeTrace: options.includeTrace,
+              ...options.riskProfile === void 0 ? {} : { riskProfile: options.riskProfile },
               ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
             },
             logger
@@ -5855,6 +5927,7 @@ var runReportCommand = async (inputPath, authorIdentityMode, options, logger = c
     authorIdentityMode,
     {
       includeTrace: options.includeTrace,
+      ...options.riskProfile === void 0 ? {} : { riskProfile: options.riskProfile },
       ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
     },
     logger
@@ -5911,7 +5984,14 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
     logger
   );
   logger.info("computing explainable risk summary");
-  const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: true });
+  const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
+  const evaluation = evaluateRepositoryRisk(
+    {
+      ...analysisInputs,
+      ...riskConfig === void 0 ? {} : { config: riskConfig }
+    },
+    { explain: true }
+  );
   if (evaluation.trace === void 0) {
     throw new Error("risk trace unavailable");
   }
@@ -5919,7 +5999,7 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
     ...analysisInputs,
     risk: evaluation.summary
   };
-  logger.info(`explanation completed (repositoryScore=${summary.risk.repositoryScore})`);
+  logger.info(`explanation completed (riskScore=${summary.risk.riskScore})`);
   return {
     summary,
     trace: evaluation.trace,
@@ -5938,8 +6018,124 @@ var parseRecentWindowDays = (value) => {
   }
   return parsed;
 };
+var stripLeadingMarkdownHeading = (value, heading) => {
+  const prefix = `${heading}
+`;
+  if (value.startsWith(prefix)) {
+    return value.slice(prefix.length).trimStart();
+  }
+  return value;
+};
+var extractExplainTextSummary = (text) => {
+  const splitIndex = text.search(/\n\n(?:file|module|dependency|repository): /);
+  if (splitIndex < 0) {
+    return text.trim();
+  }
+  return text.slice(0, splitIndex).trim();
+};
+var extractExplainMarkdownSummary = (markdown) => {
+  const splitIndex = markdown.search(/\n\n## (?:file|module|dependency|repository): /);
+  if (splitIndex < 0) {
+    return markdown.trim();
+  }
+  return markdown.slice(0, splitIndex).trim();
+};
+var extractSummaryValue = (summary, key) => {
+  const prefix = `${key}: `;
+  for (const rawLine of summary.split("\n")) {
+    const line = rawLine.trimStart();
+    if (line.startsWith(prefix)) {
+      return line.slice(prefix.length).trim();
+    }
+  }
+  return void 0;
+};
+var renderReportHighlightsText = (report) => {
+  const lines = [];
+  lines.push("Repository Summary");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  riskScore: ${report.repository.riskScore}`);
+  lines.push(`  normalizedScore: ${report.repository.normalizedScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 5)) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+    lines.push(`    priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+  }
+  return lines.join("\n");
+};
+var renderReportHighlightsMarkdown = (report) => {
+  const lines = [];
+  lines.push("## Repository Summary");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- riskScore: \`${report.repository.riskScore}\``);
+  lines.push(`- normalizedScore: \`${report.repository.normalizedScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 5)) {
+    lines.push(`- **${hotspot.target}** (score: \`${hotspot.score}\`)`);
+    lines.push(`  - priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+  }
+  return lines.join("\n");
+};
+var renderCompactText = (report, explainSummary) => {
+  const lines = [];
+  lines.push("CodeSentinel Run (compact)");
+  lines.push("");
+  lines.push("Repository");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  riskScore: ${report.repository.riskScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push(
+    `  dimensions: structural=${report.repository.dimensionScores.structural ?? "n/a"}, evolution=${report.repository.dimensionScores.evolution ?? "n/a"}, external=${report.repository.dimensionScores.external ?? "n/a"}, interactions=${report.repository.dimensionScores.interactions ?? "n/a"}`
+  );
+  lines.push("");
+  lines.push(
+    `Key Drivers: ${extractSummaryValue(explainSummary, "key drivers") ?? "insufficient data"}`
+  );
+  lines.push(
+    `Priority Actions: ${extractSummaryValue(explainSummary, "priority actions") ?? "insufficient data"}`
+  );
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 3)) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+  }
+  return lines.join("\n");
+};
+var renderCompactMarkdown = (report, explainSummary) => {
+  const lines = [];
+  lines.push("# CodeSentinel Run (compact)");
+  lines.push("");
+  lines.push("## Repository");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- riskScore: \`${report.repository.riskScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push(
+    `- dimensions: structural=\`${report.repository.dimensionScores.structural ?? "n/a"}\`, evolution=\`${report.repository.dimensionScores.evolution ?? "n/a"}\`, external=\`${report.repository.dimensionScores.external ?? "n/a"}\`, interactions=\`${report.repository.dimensionScores.interactions ?? "n/a"}\``
+  );
+  lines.push("");
+  lines.push(
+    `- key drivers: ${extractSummaryValue(explainSummary, "- key drivers") ?? "insufficient data"}`
+  );
+  lines.push(
+    `- priority actions: ${extractSummaryValue(explainSummary, "- priority actions") ?? "insufficient data"}`
+  );
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 3)) {
+    lines.push(`- \`${hotspot.target}\` (score: \`${hotspot.score}\`)`);
+  }
+  return lines.join("\n");
+};
+var riskProfileOption = () => new Option(
+  "--risk-profile <profile>",
+  "risk profile: default (balanced) or personal (down-weights single-maintainer ownership penalties)"
+).choices(["default", "personal"]).default("default");
 program.name("codesentinel").description("Structural and evolutionary risk analysis for TypeScript/JavaScript codebases").version(version);
-program.command("analyze").argument("[path]", "path to the project to analyze").addOption(
+program.command("analyze").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
   new Option(
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
@@ -5962,7 +6158,7 @@ program.command("analyze").argument("[path]", "path to the project to analyze").
     const summary = await runAnalyzeCommand(
       path,
       options.authorIdentity,
-      { recentWindowDays: options.recentWindowDays },
+      { recentWindowDays: options.recentWindowDays, riskProfile: options.riskProfile },
       logger
     );
     const outputMode = options.json === true ? "json" : options.output;
@@ -5970,7 +6166,7 @@ program.command("analyze").argument("[path]", "path to the project to analyze").
 `);
   }
 );
-program.command("explain").argument("[path]", "path to the project to analyze").addOption(
+program.command("explain").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
   new Option(
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
@@ -5996,6 +6192,7 @@ program.command("explain").argument("[path]", "path to the project to analyze").
       ...options.module === void 0 ? {} : { module: options.module },
       top: Number.isFinite(top) ? top : 5,
       recentWindowDays: options.recentWindowDays,
+      riskProfile: options.riskProfile,
       format: options.format
     };
     const result = await runExplainCommand(path, options.authorIdentity, explainOptions, logger);
@@ -6033,7 +6230,7 @@ program.command("dependency-risk").argument("<dependency>", "dependency spec to
 `);
   }
 );
-program.command("report").argument("[path]", "path to the project to analyze").addOption(
+program.command("report").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
   new Option(
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
@@ -6062,6 +6259,7 @@ program.command("report").argument("[path]", "path to the project to analyze").a
         ...options.compare === void 0 ? {} : { comparePath: options.compare },
         ...options.snapshot === void 0 ? {} : { snapshotPath: options.snapshot },
         includeTrace: options.trace,
+        riskProfile: options.riskProfile,
         recentWindowDays: options.recentWindowDays
       },
       logger
@@ -6072,6 +6270,219 @@ program.command("report").argument("[path]", "path to the project to analyze").a
     }
   }
 );
+program.command("run").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).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>", "combined output format: text, md, json").choices(["text", "md", "json"]).default("text")
+).addOption(
+  new Option("--detail <level>", "run detail level: compact (default), standard, full").choices(["compact", "standard", "full"]).default("compact")
+).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").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").addOption(
+  new Option(
+    "--recent-window-days <days>",
+    "git recency window in days used for evolution volatility metrics"
+  ).argParser(parseRecentWindowDays).default(30)
+).action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const top = Number.parseInt(options.top, 10);
+    const explain = await runExplainCommand(
+      path,
+      options.authorIdentity,
+      {
+        ...options.file === void 0 ? {} : { file: options.file },
+        ...options.module === void 0 ? {} : { module: options.module },
+        top: Number.isFinite(top) ? top : 5,
+        format: options.format,
+        recentWindowDays: options.recentWindowDays,
+        riskProfile: options.riskProfile
+      },
+      logger
+    );
+    const snapshot = createSnapshot({
+      analysis: explain.summary,
+      ...options.trace === true ? { trace: explain.trace } : {}
+    });
+    if (options.snapshot !== void 0) {
+      await writeFile5(options.snapshot, JSON.stringify(snapshot, null, 2), "utf8");
+      logger.info(`snapshot written: ${options.snapshot}`);
+    }
+    const report = options.compare === void 0 ? createReport(snapshot) : createReport(
+      snapshot,
+      compareSnapshots(snapshot, parseSnapshot(await readFile5(options.compare, "utf8")))
+    );
+    if (options.format === "json") {
+      const analyzeSummaryOutput = formatAnalyzeOutput(explain.summary, "summary");
+      if (options.detail === "compact") {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              schemaVersion: "codesentinel.run.v1",
+              generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              repository: report.repository,
+              keyDrivers: extractSummaryValue(
+                extractExplainTextSummary(formatExplainOutput(explain, "text")),
+                "key drivers"
+              ),
+              priorityActions: extractSummaryValue(
+                extractExplainTextSummary(formatExplainOutput(explain, "text")),
+                "priority actions"
+              ),
+              topHotspots: report.hotspots.slice(0, 3).map((hotspot) => ({
+                target: hotspot.target,
+                score: hotspot.score
+              }))
+            },
+            null,
+            2
+          )}
+`
+        );
+        return;
+      }
+      if (options.detail === "standard") {
+        const analyzeSummaryPayload = JSON.parse(analyzeSummaryOutput);
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              schemaVersion: "codesentinel.run.v1",
+              generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              analyze: analyzeSummaryPayload,
+              explain: {
+                summary: extractExplainTextSummary(formatExplainOutput(explain, "text"))
+              },
+              report: {
+                repository: report.repository,
+                hotspots: report.hotspots.slice(0, 5),
+                structural: report.structural,
+                external: report.external
+              }
+            },
+            null,
+            2
+          )}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            schemaVersion: "codesentinel.run.v1",
+            generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            analyze: explain.summary,
+            explain,
+            report
+          },
+          null,
+          2
+        )}
+`
+      );
+      return;
+    }
+    const analyzeRendered = formatAnalyzeOutput(explain.summary, "summary");
+    const explainRendered = formatExplainOutput(explain, options.format);
+    if (options.detail === "compact") {
+      if (options.format === "md") {
+        process.stdout.write(
+          `${renderCompactMarkdown(
+            report,
+            extractExplainMarkdownSummary(formatExplainOutput(explain, "md"))
+          )}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `${renderCompactText(report, extractExplainTextSummary(formatExplainOutput(explain, "text")))}
+`
+      );
+      return;
+    }
+    if (options.detail === "standard") {
+      if (options.format === "md") {
+        process.stdout.write(
+          `# CodeSentinel Run
+
+## Analyze
+\`\`\`json
+${analyzeRendered}
+\`\`\`
+
+## Explain
+${extractExplainMarkdownSummary(
+            formatExplainOutput(explain, "md")
+          )}
+
+${renderReportHighlightsMarkdown(report)}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `CodeSentinel Run
+
+Analyze
+${analyzeRendered}
+
+Explain
+${extractExplainTextSummary(
+          formatExplainOutput(explain, "text")
+        )}
+
+Report
+${renderReportHighlightsText(report)}
+`
+      );
+      return;
+    }
+    const reportRendered = formatReport(report, options.format);
+    if (options.format === "md") {
+      const explainSection = stripLeadingMarkdownHeading(
+        explainRendered,
+        "# CodeSentinel Explanation"
+      );
+      const reportSection = stripLeadingMarkdownHeading(reportRendered, "# CodeSentinel Report");
+      process.stdout.write(
+        `# CodeSentinel Run
+
+## Analyze
+\`\`\`json
+${analyzeRendered}
+\`\`\`
+
+## Explain
+${explainSection}
+
+## Report
+${reportSection}
+`
+      );
+      return;
+    }
+    process.stdout.write(
+      `CodeSentinel Run
+
+Analyze
+${analyzeRendered}
+
+Explain
+${explainRendered}
+
+Report
+${reportRendered}
+`
+    );
+  }
+);
 var parseGateNumber = (value, optionName) => {
   if (value === void 0) {
     return void 0;
@@ -6113,7 +6524,7 @@ var buildGateConfigFromOptions = (options) => {
     failOn: options.failOn
   };
 };
-program.command("check").argument("[path]", "path to the project to analyze").addOption(
+program.command("check").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
   new Option(
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
@@ -6143,6 +6554,7 @@ program.command("check").argument("[path]", "path to the project to analyze").ad
         {
           ...options.compare === void 0 ? {} : { baselinePath: options.compare },
           includeTrace: options.trace,
+          riskProfile: options.riskProfile,
           recentWindowDays: options.recentWindowDays,
           gateConfig,
           outputFormat: options.format,
@@ -6166,7 +6578,7 @@ program.command("check").argument("[path]", "path to the project to analyze").ad
     }
   }
 );
-program.command("ci").argument("[path]", "path to the project to analyze").addOption(
+program.command("ci").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
   new Option(
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
@@ -6215,6 +6627,7 @@ program.command("ci").argument("[path]", "path to the project to analyze").addOp
           ...options.report === void 0 ? {} : { reportPath: options.report },
           ...options.jsonOutput === void 0 ? {} : { jsonOutputPath: options.jsonOutput },
           includeTrace: options.trace,
+          riskProfile: options.riskProfile,
           recentWindowDays: options.recentWindowDays,
           gateConfig
         },