@getcodesentinel/codesentinel 1.19.1 → 1.21.0

package/dist/index.js

@@ -1753,6 +1753,7 @@ var analyzeDependencyCandidateFromRegistry = async (input) => {
 };
 
 // ../reporter/dist/index.js
+import { basename, posix } from "path";
 var SNAPSHOT_SCHEMA_VERSION = "codesentinel.snapshot.v1";
 var REPORT_SCHEMA_VERSION = "codesentinel.report.v1";
 var RISK_MODEL_VERSION = "deterministic-v1";
@@ -1914,6 +1915,11 @@ var compareSnapshots = (current, baseline) => {
     }
   };
 };
+var toPosixDirname = (value) => {
+  const normalized = value.replaceAll("\\", "/");
+  const directory = posix.dirname(normalized);
+  return directory === "." ? "root" : directory;
+};
 var findTraceTarget = (snapshot, targetType, targetId) => snapshot.trace?.targets.find(
   (target) => target.targetType === targetType && target.targetId === targetId
 );
@@ -1959,14 +1965,27 @@ var suggestedActions = (target) => {
   }
   return [...new Set(actions)].slice(0, 3);
 };
-var hotspotItems = (snapshot) => snapshot.analysis.risk.hotspots.slice(0, 10).map((hotspot) => {
+var hotspotReason = (factors) => {
+  if (factors.length === 0) {
+    return "Limited trace data available for this hotspot.";
+  }
+  return factors.slice(0, 2).map((factor) => `${factor.label} (${factor.contribution})`).join(" + ");
+};
+var hotspotItems = (snapshot) => snapshot.analysis.risk.hotspots.slice(0, 10).map((hotspot, index) => {
   const fileScore = snapshot.analysis.risk.fileScores.find((item) => item.file === hotspot.file);
+  const evolutionMetrics = snapshot.analysis.evolution.available ? snapshot.analysis.evolution.files.find((item) => item.filePath === hotspot.file) : void 0;
   const traceTarget = findTraceTarget(snapshot, "file", hotspot.file);
   const factors = toRenderedFactors(traceTarget);
   return {
+    rank: index + 1,
     target: hotspot.file,
+    module: toPosixDirname(hotspot.file),
     score: hotspot.score,
     normalizedScore: fileScore?.normalizedScore ?? round43(hotspot.score / 100),
+    commitCount: evolutionMetrics?.commitCount ?? null,
+    churnTotal: evolutionMetrics?.churnTotal ?? null,
+    riskContributions: hotspot.factors,
+    reason: hotspotReason(factors),
     topFactors: factors,
     suggestedActions: suggestedActions(traceTarget),
     biggestLevers: (traceTarget?.reductionLevers ?? []).slice(0, 3).map((lever) => `${factorLabel(lever.factorId)} (${lever.estimatedImpact})`)
@@ -1987,6 +2006,51 @@ var repositoryConfidence = (snapshot) => {
   );
   return round43(weighted / weight);
 };
+var normalizeDependencyScope = (scope) => {
+  switch (scope) {
+    case "prod":
+    case "dev":
+      return scope;
+    default:
+      return "unknown";
+  }
+};
+var topStructuralFiles = (snapshot, selector) => [...snapshot.analysis.structural.files].sort((a, b) => selector(b) - selector(a) || a.relativePath.localeCompare(b.relativePath)).slice(0, 5).map((file) => ({
+  file: file.relativePath,
+  module: toPosixDirname(file.relativePath),
+  value: selector(file)
+}));
+var cycleDetails = (snapshot) => snapshot.analysis.structural.cycles.map((cycle, index) => {
+  const nodes = [...cycle.nodes].sort((a, b) => a.localeCompare(b));
+  return {
+    id: `cycle-${index + 1}`,
+    size: nodes.length,
+    nodes,
+    path: nodes.join(" -> ")
+  };
+});
+var riskyDependencies = (snapshot) => {
+  if (!snapshot.analysis.external.available) {
+    return [];
+  }
+  const dependencyByName = new Map(
+    snapshot.analysis.external.dependencies.map((dependency) => [dependency.name, dependency])
+  );
+  return snapshot.analysis.risk.dependencyScores.map((score) => {
+    const dependency = dependencyByName.get(score.dependency);
+    const riskSignals = [.../* @__PURE__ */ new Set([...score.ownRiskSignals, ...score.inheritedRiskSignals])];
+    return {
+      name: score.dependency,
+      score: score.score,
+      normalizedScore: score.normalizedScore,
+      dependencyScope: normalizeDependencyScope(dependency?.dependencyScope),
+      direct: dependency?.direct ?? false,
+      resolvedVersion: dependency?.resolvedVersion ?? null,
+      riskSignals,
+      reason: riskSignals.length === 0 ? "Derived from aggregate dependency risk signals." : riskSignals.join(", ")
+    };
+  }).filter((dependency) => dependency.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, 20);
+};
 var repositoryDimensionScores = (snapshot) => {
   const target = findTraceTarget(snapshot, "repository", snapshot.analysis.structural.targetPath);
   if (target === void 0) {
@@ -2019,6 +2083,7 @@ var createReport = (snapshot, diff) => {
     schemaVersion: REPORT_SCHEMA_VERSION,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     repository: {
+      name: basename(snapshot.analysis.structural.targetPath) || snapshot.analysis.structural.targetPath,
       targetPath: snapshot.analysis.structural.targetPath,
       riskScore: snapshot.analysis.risk.riskScore,
       normalizedScore: snapshot.analysis.risk.normalizedScore,
@@ -2034,6 +2099,12 @@ var createReport = (snapshot, diff) => {
       cycles: snapshot.analysis.structural.cycles.map(
         (cycle) => [...cycle.nodes].sort((a, b) => a.localeCompare(b)).join(" -> ")
       ),
+      cycleDetails: cycleDetails(snapshot),
+      fanInOutExtremes: {
+        highestFanIn: topStructuralFiles(snapshot, (file) => file.fanIn),
+        highestFanOut: topStructuralFiles(snapshot, (file) => file.fanOut),
+        deepestFiles: topStructuralFiles(snapshot, (file) => file.depth)
+      },
       fragileClusters: snapshot.analysis.risk.fragileClusters.map((cluster) => ({
         id: cluster.id,
         kind: cluster.kind,
@@ -2057,7 +2128,8 @@ var createReport = (snapshot, diff) => {
       ),
       abandonedDependencies: [...external.abandonedDependencies].sort(
         (a, b) => a.localeCompare(b)
-      )
+      ),
+      riskyDependencies: riskyDependencies(snapshot)
     },
     appendix: {
       snapshotSchemaVersion: snapshot.schemaVersion,
@@ -2298,7 +2370,7 @@ var formatReport = (report, format) => {
 
 // ../governance/dist/index.js
 import { mkdirSync, rmSync } from "fs";
-import { basename, join as join5, resolve } from "path";
+import { basename as basename2, join as join5, resolve } from "path";
 import { execFile } from "child_process";
 import { promisify } from "util";
 var EXIT_CODES = {
@@ -2911,9 +2983,9 @@ var resolveAutoBaselineRef = async (input) => {
 
 // src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname2, resolve as resolve5 } from "path";
-import { fileURLToPath } from "url";
+import { readFile as readFile7, writeFile as writeFile7 } from "fs/promises";
+import { dirname as dirname3, resolve as resolve6 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/application/format-analyze-output.ts
 var toHealthTier2 = (score) => {
@@ -3558,7 +3630,7 @@ var promptInstall = async (packageName, latestVersion, currentVersion) => {
     );
     return "skip";
   }
-  return await new Promise((resolve6) => {
+  return await new Promise((resolve7) => {
     emitKeypressEvents(stdin);
     let selectedIndex = 0;
     const previousRawMode = stdin.isRaw;
@@ -3583,7 +3655,7 @@ var promptInstall = async (packageName, latestVersion, currentVersion) => {
       } else {
         stderr.write("\n");
       }
-      resolve6(choice);
+      resolve7(choice);
     };
     const onKeypress = (_str, key) => {
       if (key.ctrl === true && key.name === "c") {
@@ -3777,7 +3849,7 @@ var promptSelection = async (currentVersion, actions) => {
   if (!stdin2.isTTY || !stderr2.isTTY || typeof stdin2.setRawMode !== "function") {
     return "exit";
   }
-  return await new Promise((resolve6) => {
+  return await new Promise((resolve7) => {
     emitKeypressEvents2(stdin2);
     let selectedIndex = 0;
     const previousRawMode = stdin2.isRaw;
@@ -3792,7 +3864,7 @@ var promptSelection = async (currentVersion, actions) => {
       stdin2.setRawMode(previousRawMode);
       clearTerminal();
       showCursor2();
-      resolve6(selection);
+      resolve7(selection);
     };
     const onKeypress = (_str, key) => {
       if (key.ctrl === true && key.name === "c") {
@@ -3885,7 +3957,7 @@ var waitForReturnToMenu = async () => {
   }
   stderr2.write(`
 ${PROMPT_PADDING}Press enter to return to the menu...`);
-  await new Promise((resolve6) => {
+  await new Promise((resolve7) => {
     emitKeypressEvents2(stdin2);
     const previousRawMode = stdin2.isRaw;
     const cleanup = () => {
@@ -3894,7 +3966,7 @@ ${PROMPT_PADDING}Press enter to return to the menu...`);
       stdin2.setRawMode(previousRawMode);
       showCursor2();
       stderr2.write("\n");
-      resolve6();
+      resolve7();
     };
     const onKeypress = (_str, key) => {
       if (key.ctrl === true && key.name === "c") {
@@ -3912,7 +3984,7 @@ ${PROMPT_PADDING}Press enter to return to the menu...`);
   });
 };
 var runCliCommand = async (scriptPath2, args) => {
-  return await new Promise((resolve6, reject) => {
+  return await new Promise((resolve7, reject) => {
     const child = spawn2(process.execPath, [...process.execArgv, scriptPath2, ...args], {
       stdio: ["inherit", "pipe", "pipe"],
       env: {
@@ -3926,7 +3998,7 @@ var runCliCommand = async (scriptPath2, args) => {
       reject(error);
     });
     child.on("close", (code) => {
-      resolve6(code ?? 1);
+      resolve7(code ?? 1);
     });
   });
 };
@@ -4683,6 +4755,26 @@ var finalizeAuthorDistribution = (authorCommits) => {
     share: round44(commits / totalCommits)
   })).sort((a, b) => b.commits - a.commits || a.authorId.localeCompare(b.authorId));
 };
+var finalizeAuthorChurnDistribution = (authorChurn) => {
+  const entries = [...authorChurn.entries()].map(([authorId, churn]) => {
+    const churnAdded = churn.churnAdded;
+    const churnDeleted = churn.churnDeleted;
+    return {
+      authorId,
+      churnAdded,
+      churnDeleted,
+      churnTotal: churnAdded + churnDeleted
+    };
+  });
+  const totalChurn = entries.reduce((sum, entry) => sum + entry.churnTotal, 0);
+  if (totalChurn === 0) {
+    return [];
+  }
+  return entries.map((entry) => ({
+    ...entry,
+    share: round44(entry.churnTotal / totalChurn)
+  })).sort((a, b) => b.churnTotal - a.churnTotal || a.authorId.localeCompare(b.authorId));
+};
 var buildCouplingMatrix = (coChangeByPair, fileCommitCount, consideredCommits, skippedLargeCommits, maxCouplingPairs) => {
   const allPairs = [];
   for (const [key, coChangeCommits] of coChangeByPair.entries()) {
@@ -4751,10 +4843,19 @@ var computeRepositoryEvolutionSummary = (targetPath, commits, config) => {
         recentCommitCount: 0,
         churnAdded: 0,
         churnDeleted: 0,
-        authors: /* @__PURE__ */ new Map()
+        authorsByCommits: /* @__PURE__ */ new Map(),
+        authorsByChurn: /* @__PURE__ */ new Map()
       };
       current.churnAdded += fileChange.additions;
       current.churnDeleted += fileChange.deletions;
+      const effectiveAuthorId = authorAliasById.get(commit.authorId) ?? commit.authorId;
+      const authorChurn = current.authorsByChurn.get(effectiveAuthorId) ?? {
+        churnAdded: 0,
+        churnDeleted: 0
+      };
+      authorChurn.churnAdded += fileChange.additions;
+      authorChurn.churnDeleted += fileChange.deletions;
+      current.authorsByChurn.set(effectiveAuthorId, authorChurn);
       fileStats.set(fileChange.filePath, current);
     }
     for (const filePath of uniqueFiles) {
@@ -4767,7 +4868,10 @@ var computeRepositoryEvolutionSummary = (targetPath, commits, config) => {
         current.recentCommitCount += 1;
       }
       const effectiveAuthorId = authorAliasById.get(commit.authorId) ?? commit.authorId;
-      current.authors.set(effectiveAuthorId, (current.authors.get(effectiveAuthorId) ?? 0) + 1);
+      current.authorsByCommits.set(
+        effectiveAuthorId,
+        (current.authorsByCommits.get(effectiveAuthorId) ?? 0) + 1
+      );
     }
     const orderedFiles = [...uniqueFiles].sort((a, b) => a.localeCompare(b));
     if (orderedFiles.length > 1) {
@@ -4790,8 +4894,10 @@ var computeRepositoryEvolutionSummary = (targetPath, commits, config) => {
     }
   }
   const files = [...fileStats.entries()].map(([filePath, stats]) => {
-    const authorDistribution = finalizeAuthorDistribution(stats.authors);
-    const topAuthorShare = authorDistribution[0]?.share ?? 0;
+    const authorDistributionByCommits = finalizeAuthorDistribution(stats.authorsByCommits);
+    const authorDistributionByChurn = finalizeAuthorChurnDistribution(stats.authorsByChurn);
+    const topAuthorShareByCommits = authorDistributionByCommits[0]?.share ?? 0;
+    const topAuthorShareByChurn = authorDistributionByChurn[0]?.share ?? 0;
     return {
       filePath,
       commitCount: stats.commitCount,
@@ -4801,9 +4907,18 @@ var computeRepositoryEvolutionSummary = (targetPath, commits, config) => {
       churnTotal: stats.churnAdded + stats.churnDeleted,
       recentCommitCount: stats.recentCommitCount,
       recentVolatility: stats.commitCount === 0 ? 0 : round44(stats.recentCommitCount / stats.commitCount),
-      topAuthorShare,
-      busFactor: computeBusFactor(authorDistribution, config.busFactorCoverageThreshold),
-      authorDistribution
+      topAuthorShareByCommits,
+      busFactorByCommits: computeBusFactor(
+        authorDistributionByCommits,
+        config.busFactorCoverageThreshold
+      ),
+      authorDistributionByCommits,
+      topAuthorShareByChurn,
+      busFactorByChurn: computeBusFactor(
+        authorDistributionByChurn,
+        config.busFactorCoverageThreshold
+      ),
+      authorDistributionByChurn
     };
   }).sort((a, b) => a.filePath.localeCompare(b.filePath));
   const fileCommitCount = new Map(files.map((file) => [file.filePath, file.commitCount]));
@@ -5558,15 +5673,15 @@ var computeRepositoryHealthSummary = (input) => {
     let singleContributorFiles = 0;
     let trackedFiles = 0;
     for (const file of evolutionSourceFiles) {
-      if (file.commitCount <= 0 || file.authorDistribution.length === 0) {
+      if (file.commitCount <= 0 || file.authorDistributionByCommits.length === 0) {
         continue;
       }
       trackedFiles += 1;
-      const dominantShare = clamp01(file.authorDistribution[0]?.share ?? 0);
-      if (file.authorDistribution.length === 1 || dominantShare >= 0.9) {
+      const dominantShare = clamp01(file.authorDistributionByCommits[0]?.share ?? 0);
+      if (file.authorDistributionByCommits.length === 1 || dominantShare >= 0.9) {
         singleContributorFiles += 1;
       }
-      for (const author of file.authorDistribution) {
+      for (const author of file.authorDistributionByCommits) {
         const commits = Math.max(0, author.commits);
         if (commits <= 0) {
           continue;
@@ -6329,7 +6444,7 @@ var computeEvolutionScales = (evolutionByFile, config) => {
       config.quantileClamp.upper
     ),
     busFactor: buildQuantileScale(
-      evolutionFiles.map((metrics) => metrics.busFactor),
+      evolutionFiles.map((metrics) => metrics.busFactorByCommits),
       config.quantileClamp.lower,
       config.quantileClamp.upper
     )
@@ -6518,9 +6633,9 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         evolutionScales.churnTotal
       );
       volatilityRisk = toUnitInterval(evolutionMetrics.recentVolatility);
-      ownershipConcentrationRisk = toUnitInterval(evolutionMetrics.topAuthorShare);
+      ownershipConcentrationRisk = toUnitInterval(evolutionMetrics.topAuthorShareByCommits);
       busFactorRisk = toUnitInterval(
-        1 - normalizeWithScale(evolutionMetrics.busFactor, evolutionScales.busFactor)
+        1 - normalizeWithScale(evolutionMetrics.busFactorByCommits, evolutionScales.busFactor)
       );
       const evolutionWeights = config.evolutionFactorWeights;
       evolutionFactor = toUnitInterval(
@@ -6577,8 +6692,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         commitCount: evolutionMetrics?.commitCount ?? null,
         churnTotal: evolutionMetrics?.churnTotal ?? null,
         recentVolatility: evolutionMetrics?.recentVolatility ?? null,
-        topAuthorShare: evolutionMetrics?.topAuthorShare ?? null,
-        busFactor: evolutionMetrics?.busFactor ?? null,
+        topAuthorShareByCommits: evolutionMetrics?.topAuthorShareByCommits ?? null,
+        busFactorByCommits: evolutionMetrics?.busFactorByCommits ?? null,
         dependencyAffinity: round46(dependencyAffinity),
         repositoryExternalPressure: round46(dependencyComputation.repositoryExternalPressure),
         structuralAttenuation: round46(structuralAttenuation)
@@ -6646,8 +6761,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
             commitCount: context.rawMetrics.commitCount,
             churnTotal: context.rawMetrics.churnTotal,
             recentVolatility: context.rawMetrics.recentVolatility,
-            topAuthorShare: context.rawMetrics.topAuthorShare,
-            busFactor: context.rawMetrics.busFactor
+            topAuthorShareByCommits: context.rawMetrics.topAuthorShareByCommits,
+            busFactorByCommits: context.rawMetrics.busFactorByCommits
           },
           normalizedMetrics: {
             frequencyRisk: context.normalizedMetrics.frequencyRisk,
@@ -7597,7 +7712,114 @@ ${ciMarkdown}`;
 };
 
 // src/application/run-report-command.ts
-import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
+import { join as join8 } from "path";
+import { readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
+
+// src/application/html-report.ts
+import { mkdir as mkdir3, readFile as readFile5, rm, stat as stat2, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname2, join as join7, resolve as resolve5 } from "path";
+import { fileURLToPath } from "url";
+var HTML_REPORT_DIR = ".codesentinel/report";
+var getBundledHtmlAppPath = () => resolve5(dirname2(fileURLToPath(import.meta.url)), "html-report-app");
+var serializeReportBootstrap = (report) => `window.__CODESENTINEL_REPORT__ = ${JSON.stringify(report).replaceAll("</", "<\\/")};
+`;
+var escapeInlineScript = (script) => script.replaceAll("</script", "<\\/script").replaceAll("<script", "\\x3Cscript").replaceAll("<!--", "\\x3C!--").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+var ensureDirectory = async (directoryPath) => {
+  await mkdir3(directoryPath, { recursive: true });
+};
+var readReferencedAssets = async (appPath, indexHtml) => {
+  const stylesheetPaths = [
+    ...indexHtml.matchAll(/<link[^>]+rel=["']stylesheet["'][^>]+href=["']([^"']+)["'][^>]*>/g)
+  ].map((match) => match[1]).filter((value) => value !== void 0);
+  const styles = await Promise.all(
+    stylesheetPaths.map(async (href) => readFile5(resolve5(appPath, href), "utf8"))
+  );
+  const scriptPaths = [...indexHtml.matchAll(/<script[^>]+src=["']([^"']+)["'][^>]*><\/script>/g)].map((match) => match[1]).filter((value) => value !== void 0);
+  const scripts = await Promise.all(
+    scriptPaths.map(async (src) => readFile5(resolve5(appPath, src), "utf8"))
+  );
+  return { styles, scripts };
+};
+var inlineBuiltHtml = async (appPath, report) => {
+  const indexHtml = await readFile5(resolve5(appPath, "index.html"), "utf8");
+  const { styles, scripts } = await readReferencedAssets(appPath, indexHtml);
+  const htmlWithoutExternalAssets = indexHtml.replace(/\s*<link[^>]+rel=["']stylesheet["'][^>]*>\s*/g, "").replace(/\s*<script[^>]+src=["'][^"']+["'][^>]*><\/script>\s*/g, "");
+  const inlineStyles = styles.map((style) => `<style>
+${style}
+</style>`).join("\n");
+  const bootstrapScript = `<script>
+${serializeReportBootstrap(report)}</script>`;
+  const inlineScripts = scripts.map((script) => `<script>
+${escapeInlineScript(script)}
+</script>`).join("\n");
+  return htmlWithoutExternalAssets.replace("</head>", () => `${inlineStyles === "" ? "" : `${inlineStyles}
+`}</head>`).replace(
+    "</body>",
+    () => `${bootstrapScript}
+${inlineScripts === "" ? "" : `${inlineScripts}
+`}</body>`
+  );
+};
+var assertHtmlAppAssets = async (assetPath) => {
+  const assetStats = await stat2(assetPath).catch(() => void 0);
+  if (assetStats === void 0 || !assetStats.isDirectory()) {
+    throw new Error(
+      `html_report_assets_missing: expected built app at ${assetPath}. Run the workspace build first.`
+    );
+  }
+};
+var resolveHtmlReportOutputPath = (repositoryPath, outputPath) => {
+  const invocationCwd = process.env["INIT_CWD"] ?? process.cwd();
+  return resolve5(invocationCwd, outputPath ?? join7(repositoryPath, HTML_REPORT_DIR));
+};
+var writeHtmlReportBundle = async (report, options) => {
+  const bundledAppPath = options.bundledAppPath ?? getBundledHtmlAppPath();
+  await assertHtmlAppAssets(bundledAppPath);
+  const outputPath = resolveHtmlReportOutputPath(options.repositoryPath, options.outputPath);
+  await rm(outputPath, { recursive: true, force: true });
+  await ensureDirectory(outputPath);
+  await writeFile5(
+    resolve5(outputPath, "index.html"),
+    await inlineBuiltHtml(bundledAppPath, report),
+    "utf8"
+  );
+  return outputPath;
+};
+
+// src/application/open-path.ts
+import { spawn as spawn3 } from "child_process";
+import { platform } from "os";
+var openCommandForPlatform = (targetPath) => {
+  switch (platform()) {
+    case "darwin":
+      return { command: "open", args: [targetPath] };
+    case "win32":
+      return { command: "cmd", args: ["/c", "start", "", targetPath] };
+    case "linux":
+      return { command: "xdg-open", args: [targetPath] };
+    default:
+      return void 0;
+  }
+};
+var openPath = async (targetPath) => {
+  const command = openCommandForPlatform(targetPath);
+  if (command === void 0) {
+    return false;
+  }
+  return new Promise((resolve7) => {
+    const child = spawn3(command.command, command.args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.once("error", () => resolve7(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve7(true);
+    });
+  });
+};
+
+// src/application/run-report-command.ts
 var runReportCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
   logger.info("building analysis snapshot");
   const current = await buildAnalysisSnapshot(
@@ -7611,7 +7833,7 @@ var runReportCommand = async (inputPath, authorIdentityMode, options, logger = c
     logger
   );
   if (options.snapshotPath !== void 0) {
-    await writeFile5(options.snapshotPath, JSON.stringify(current, null, 2), "utf8");
+    await writeFile6(options.snapshotPath, JSON.stringify(current, null, 2), "utf8");
     logger.info(`snapshot written: ${options.snapshotPath}`);
   }
   let report;
@@ -7619,17 +7841,39 @@ var runReportCommand = async (inputPath, authorIdentityMode, options, logger = c
     report = createReport(current);
   } else {
     logger.info(`loading baseline snapshot: ${options.comparePath}`);
-    const baselineRaw = await readFile5(options.comparePath, "utf8");
+    const baselineRaw = await readFile6(options.comparePath, "utf8");
     const baseline = parseSnapshot(baselineRaw);
     const diff = compareSnapshots(current, baseline);
     report = createReport(current, diff);
   }
+  if (options.format === "html") {
+    const bundlePath = await writeHtmlReportBundle(report, {
+      repositoryPath: current.analysis.structural.targetPath,
+      ...options.outputPath === void 0 ? {} : { outputPath: options.outputPath }
+    });
+    if (options.open === true) {
+      const opened = await openPath(join8(bundlePath, "index.html"));
+      if (!opened) {
+        logger.warn("unable to open html report automatically on this platform");
+      }
+    }
+    logger.info(`html report written: ${bundlePath}`);
+    return {
+      report,
+      rendered: bundlePath,
+      outputPath: bundlePath
+    };
+  }
   const rendered = formatReport(report, options.format);
   if (options.outputPath !== void 0) {
-    await writeFile5(options.outputPath, rendered, "utf8");
+    await writeFile6(options.outputPath, rendered, "utf8");
     logger.info(`report written: ${options.outputPath}`);
   }
-  return { report, rendered };
+  return {
+    report,
+    rendered,
+    ...options.outputPath === void 0 ? {} : { outputPath: options.outputPath }
+  };
 };
 
 // src/application/run-explain-command.ts
@@ -7699,7 +7943,7 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
 
 // src/index.ts
 var program = new Command();
-var packageJsonPath = resolve5(dirname2(fileURLToPath(import.meta.url)), "../package.json");
+var packageJsonPath = resolve6(dirname3(fileURLToPath2(import.meta.url)), "../package.json");
 var { version } = JSON.parse(readFileSync2(packageJsonPath, "utf8"));
 var parseRecentWindowDays = (value) => {
   const parsed = Number.parseInt(value, 10);
@@ -7945,8 +8189,8 @@ program.command("report").argument("[path]", "path to the project to analyze").a
     "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("md")
-).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").addOption(
+  new Option("--format <mode>", "output format: text, json, md, html").choices(["text", "json", "md", "html"]).default("md")
+).option("--output <path>", "write rendered report to a file path").option("--open", "open the generated HTML report in the default browser").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"
@@ -7962,14 +8206,20 @@ program.command("report").argument("[path]", "path to the project to analyze").a
         ...options.output === void 0 ? {} : { outputPath: options.output },
         ...options.compare === void 0 ? {} : { comparePath: options.compare },
         ...options.snapshot === void 0 ? {} : { snapshotPath: options.snapshot },
+        ...options.open === void 0 ? {} : { open: options.open },
         includeTrace: options.trace,
         scoringProfile: options.scoringProfile,
         recentWindowDays: options.recentWindowDays
       },
       logger
     );
-    if (options.output === void 0) {
+    if (options.output === void 0 && options.format !== "html") {
       process.stdout.write(`${result.rendered}
+`);
+      return;
+    }
+    if (options.format === "html") {
+      process.stdout.write(`${result.outputPath ?? result.rendered}
 `);
     }
   }
@@ -7988,7 +8238,9 @@ program.command("run").argument("[path]", "path to the project to analyze").addO
   new Option("--format <mode>", "combined output format: text, md, json").choices(["text", "md", "json"]).default("md")
 ).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(
+).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").addOption(
+  new Option("--report <format>", "write an additional report bundle during the run").choices(["html"]).default(void 0)
+).option("--report-output <path>", "output path for the generated report bundle").option("--open", "open the generated HTML report in the default browser").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"
@@ -8015,13 +8267,28 @@ program.command("run").argument("[path]", "path to the project to analyze").addO
       ...options.trace === true ? { trace: explain.trace } : {}
     });
     if (options.snapshot !== void 0) {
-      await writeFile6(options.snapshot, JSON.stringify(snapshot, null, 2), "utf8");
+      await writeFile7(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 readFile6(options.compare, "utf8")))
+      compareSnapshots(snapshot, parseSnapshot(await readFile7(options.compare, "utf8")))
     );
+    if (options.report === "html") {
+      const htmlOutputPath = await writeHtmlReportBundle(report, {
+        repositoryPath: explain.summary.structural.targetPath,
+        ...options.reportOutput === void 0 ? {} : { outputPath: options.reportOutput }
+      });
+      if (options.open === true) {
+        const opened = await openPath(`${htmlOutputPath}/index.html`);
+        if (!opened) {
+          logger.warn("unable to open html report automatically on this platform");
+        }
+      }
+      logger.info(`html report written: ${htmlOutputPath}`);
+    } else if (options.open === true) {
+      logger.warn("--open has no effect unless --report html is set");
+    }
     if (options.format === "json") {
       const analyzeSummaryOutput = formatAnalyzeOutput(explain.summary, "summary");
       if (options.detail === "compact") {