@getcodesentinel/codesentinel 1.7.0 → 1.8.0

package/README.md

@@ -70,6 +70,7 @@ Then run:
 ```bash
 codesentinel analyze [path]
 codesentinel explain [path]
+codesentinel report [path]
 codesentinel dependency-risk <dependency[@version]>
 ```
 
@@ -83,6 +84,10 @@ codesentinel explain
 codesentinel explain . --top 5 --format text
 codesentinel explain . --file src/app/page.tsx
 codesentinel explain . --module src/components
+codesentinel report
+codesentinel report --format md --output report.md
+codesentinel report --snapshot snapshot.json
+codesentinel report --compare baseline.json --format text
 codesentinel dependency-risk react
 codesentinel dependency-risk react@19.0.0
 ```
@@ -121,6 +126,13 @@ codesentinel explain . --module src/components
 # Explain in markdown or json
 codesentinel explain . --format md
 codesentinel explain . --format json
+
+# Report generation (human + machine readable)
+codesentinel report .
+codesentinel report . --format md --output report.md
+codesentinel report . --format json
+codesentinel report . --snapshot snapshot.json
+codesentinel report . --compare baseline.json --format text
 ```
 
 Notes:
@@ -145,8 +157,28 @@ pnpm dev -- analyze . --author-identity strict_email
 pnpm dev -- explain
 pnpm dev -- explain . --top 5 --format text
 pnpm dev -- explain . --file src/app/page.tsx
+pnpm dev -- report
+pnpm dev -- report . --format md --output report.md
+pnpm dev -- report . --compare baseline.json --format text
 ```
 
+## Report Output
+
+`codesentinel report` produces deterministic engineering artifacts from existing analysis outputs.
+
+- formats: `text`, `md`, `json`
+- optional file output: `--output <path>`
+- optional snapshot export: `--snapshot <path>`
+- optional diff mode: `--compare <baseline.json>`
+
+Diff mode compares snapshots and reports:
+
+- repository score deltas
+- file/module risk deltas
+- new/resolved hotspots
+- new/resolved cycles
+- dependency exposure list changes
+
 ## Explain Output
 
 `codesentinel explain` uses the same risk-engine scoring model as `analyze` and adds structured explanation traces.
@@ -278,28 +310,6 @@ Propagation policy is explicit and deterministic:
 
 This keeps package-level facts local while still surfacing meaningful transitive exposure.
 
-## Release Automation
-
-- Pull requests to `main` run build and tests via `.github/workflows/ci.yml`.
-- Pull requests and release runs also validate the packed CLI artifact (`npm pack`) with install/execute smoke checks before publish.
-- Merges to `main` run semantic-release via `.github/workflows/release.yml`.
-- semantic-release bumps `packages/cli/package.json`, creates a GitHub release, publishes to npm, and pushes the version-bump commit back to `main`.
-- Dependabot is configured monthly in `.github/dependabot.yml` for npm and GitHub Actions updates.
-
-Trusted Publisher setup (no `NPM_TOKEN` secret):
-
-- In npm package settings for `@getcodesentinel/codesentinel`, add a Trusted Publisher.
-- Provider: `GitHub Actions`.
-- Repository: `getcodesentinel/codesentinel`.
-- Workflow filename: `release.yml`.
-- Environment name: leave empty unless you explicitly use a GitHub Actions environment in this workflow.
-
-Commit messages on `main` should follow Conventional Commits (example: `feat:`, `fix:`, `chore:`) so semantic-release can calculate versions automatically.
-
-## Contributing
-
-This project aims to be production-grade and minimal. If you add new dependencies or abstractions, justify them clearly and keep the architecture clean.
-
 ## ESM Import Policy
 
 - The workspace uses `TypeScript` with `moduleResolution: "NodeNext"` and ESM output.

package/dist/index.js

@@ -4030,6 +4030,474 @@ var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSil
   };
 };
 
+// src/application/run-report-command.ts
+import { readFile, writeFile } from "fs/promises";
+
+// ../reporter/dist/index.js
+var SNAPSHOT_SCHEMA_VERSION = "codesentinel.snapshot.v1";
+var REPORT_SCHEMA_VERSION = "codesentinel.report.v1";
+var RISK_MODEL_VERSION = "deterministic-v1";
+var round45 = (value) => Number(value.toFixed(4));
+var toRiskTier = (score) => {
+  if (score < 20) {
+    return "low";
+  }
+  if (score < 40) {
+    return "moderate";
+  }
+  if (score < 60) {
+    return "elevated";
+  }
+  if (score < 80) {
+    return "high";
+  }
+  return "very_high";
+};
+var factorLabelById2 = {
+  "repository.structural": "Structural complexity",
+  "repository.evolution": "Change volatility",
+  "repository.external": "External dependency pressure",
+  "repository.composite.interactions": "Intersection amplification",
+  "file.structural": "File structural complexity",
+  "file.evolution": "File change volatility",
+  "file.external": "File external pressure",
+  "file.composite.interactions": "File interaction amplification",
+  "module.average_file_risk": "Average file risk",
+  "module.peak_file_risk": "Peak file risk",
+  "dependency.signals": "Dependency risk signals",
+  "dependency.staleness": "Dependency staleness",
+  "dependency.maintainer_concentration": "Maintainer concentration",
+  "dependency.topology": "Dependency topology pressure",
+  "dependency.bus_factor": "Dependency bus factor",
+  "dependency.popularity_dampening": "Popularity dampening"
+};
+var factorLabel = (factorId) => factorLabelById2[factorId] ?? factorId;
+var summarizeEvidence = (factor) => {
+  const entries = Object.entries(factor.rawMetrics).filter(([, value]) => value !== null).sort((a, b) => a[0].localeCompare(b[0])).slice(0, 3).map(([key, value]) => `${key}=${value}`);
+  if (entries.length > 0) {
+    return entries.join(", ");
+  }
+  const evidence = [...factor.evidence].map((entry) => {
+    if (entry.kind === "file_metric") {
+      return `${entry.target}:${entry.metric}`;
+    }
+    if (entry.kind === "dependency_metric") {
+      return `${entry.target}:${entry.metric}`;
+    }
+    if (entry.kind === "repository_metric") {
+      return entry.metric;
+    }
+    if (entry.kind === "graph_cycle") {
+      return `cycle:${entry.cycleId}`;
+    }
+    return `${entry.fileA}<->${entry.fileB}`;
+  }).sort((a, b) => a.localeCompare(b));
+  return evidence.join(", ");
+};
+var diffSets = (current, baseline) => {
+  const currentSet = new Set(current);
+  const baselineSet = new Set(baseline);
+  const added = [...currentSet].filter((item) => !baselineSet.has(item)).sort((a, b) => a.localeCompare(b));
+  const removed = [...baselineSet].filter((item) => !currentSet.has(item)).sort((a, b) => a.localeCompare(b));
+  return { added, removed };
+};
+var diffScoreMap = (current, baseline) => {
+  const keys = [.../* @__PURE__ */ new Set([...current.keys(), ...baseline.keys()])].sort((a, b) => a.localeCompare(b));
+  return keys.map((key) => {
+    const before = baseline.get(key) ?? 0;
+    const after = current.get(key) ?? 0;
+    const delta = round45(after - before);
+    return {
+      target: key,
+      before: round45(before),
+      after: round45(after),
+      delta
+    };
+  }).filter((entry) => entry.delta !== 0).sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta) || a.target.localeCompare(b.target));
+};
+var cycleKey = (nodes) => [...nodes].sort((a, b) => a.localeCompare(b)).join(" -> ");
+var compareSnapshots = (current, baseline) => {
+  const currentFileScores = new Map(
+    current.analysis.risk.fileScores.map((item) => [item.file, item.score])
+  );
+  const baselineFileScores = new Map(
+    baseline.analysis.risk.fileScores.map((item) => [item.file, item.score])
+  );
+  const currentModuleScores = new Map(
+    current.analysis.risk.moduleScores.map((item) => [item.module, item.score])
+  );
+  const baselineModuleScores = new Map(
+    baseline.analysis.risk.moduleScores.map((item) => [item.module, item.score])
+  );
+  const currentHotspots = current.analysis.risk.hotspots.slice(0, 10).map((item) => item.file);
+  const baselineHotspots = baseline.analysis.risk.hotspots.slice(0, 10).map((item) => item.file);
+  const currentCycles = current.analysis.structural.cycles.map((cycle) => cycleKey(cycle.nodes));
+  const baselineCycles = baseline.analysis.structural.cycles.map((cycle) => cycleKey(cycle.nodes));
+  const currentExternal = current.analysis.external.available ? current.analysis.external : {
+    highRiskDependencies: [],
+    singleMaintainerDependencies: [],
+    abandonedDependencies: []
+  };
+  const baselineExternal = baseline.analysis.external.available ? baseline.analysis.external : {
+    highRiskDependencies: [],
+    singleMaintainerDependencies: [],
+    abandonedDependencies: []
+  };
+  const highRisk = diffSets(currentExternal.highRiskDependencies, baselineExternal.highRiskDependencies);
+  const singleMaintainer = diffSets(
+    currentExternal.singleMaintainerDependencies,
+    baselineExternal.singleMaintainerDependencies
+  );
+  const abandoned = diffSets(currentExternal.abandonedDependencies, baselineExternal.abandonedDependencies);
+  const hotspots = diffSets(currentHotspots, baselineHotspots);
+  const cycles = diffSets(currentCycles, baselineCycles);
+  return {
+    repositoryScoreDelta: round45(current.analysis.risk.repositoryScore - baseline.analysis.risk.repositoryScore),
+    normalizedScoreDelta: round45(current.analysis.risk.normalizedScore - baseline.analysis.risk.normalizedScore),
+    fileRiskChanges: diffScoreMap(currentFileScores, baselineFileScores),
+    moduleRiskChanges: diffScoreMap(currentModuleScores, baselineModuleScores),
+    newHotspots: hotspots.added,
+    resolvedHotspots: hotspots.removed,
+    newCycles: cycles.added,
+    resolvedCycles: cycles.removed,
+    externalChanges: {
+      highRiskAdded: highRisk.added,
+      highRiskRemoved: highRisk.removed,
+      singleMaintainerAdded: singleMaintainer.added,
+      singleMaintainerRemoved: singleMaintainer.removed,
+      abandonedAdded: abandoned.added,
+      abandonedRemoved: abandoned.removed
+    }
+  };
+};
+var findTraceTarget = (snapshot, targetType, targetId) => snapshot.trace?.targets.find(
+  (target) => target.targetType === targetType && target.targetId === targetId
+);
+var toRenderedFactors = (target) => {
+  if (target === void 0) {
+    return [];
+  }
+  return [...target.factors].sort((a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)).slice(0, 4).map((factor) => ({
+    id: factor.factorId,
+    label: factorLabel(factor.factorId),
+    contribution: round45(factor.contribution),
+    confidence: round45(factor.confidence),
+    evidence: summarizeEvidence(factor)
+  }));
+};
+var suggestedActions = (target) => {
+  if (target === void 0) {
+    return [];
+  }
+  const actions = [];
+  for (const lever of target.reductionLevers) {
+    switch (lever.factorId) {
+      case "file.evolution":
+      case "repository.evolution":
+        actions.push("Reduce recent churn and volatile edit frequency in this area.");
+        break;
+      case "file.structural":
+      case "repository.structural":
+        actions.push("Reduce fan-in/fan-out concentration and simplify deep dependency paths.");
+        break;
+      case "file.composite.interactions":
+      case "repository.composite.interactions":
+        actions.push("Stabilize central files before concurrent structural changes.");
+        break;
+      case "file.external":
+      case "repository.external":
+        actions.push("Review external dependency pressure for this hotspot.");
+        break;
+      default:
+        actions.push(`Reduce ${factorLabel(lever.factorId).toLowerCase()} influence.`);
+        break;
+    }
+  }
+  return [...new Set(actions)].slice(0, 3);
+};
+var hotspotItems = (snapshot) => snapshot.analysis.risk.hotspots.slice(0, 10).map((hotspot) => {
+  const fileScore = snapshot.analysis.risk.fileScores.find((item) => item.file === hotspot.file);
+  const traceTarget = findTraceTarget(snapshot, "file", hotspot.file);
+  const factors = toRenderedFactors(traceTarget);
+  return {
+    target: hotspot.file,
+    score: hotspot.score,
+    normalizedScore: fileScore?.normalizedScore ?? round45(hotspot.score / 100),
+    topFactors: factors,
+    suggestedActions: suggestedActions(traceTarget),
+    biggestLevers: (traceTarget?.reductionLevers ?? []).slice(0, 3).map((lever) => `${factorLabel(lever.factorId)} (${lever.estimatedImpact})`)
+  };
+});
+var repositoryConfidence = (snapshot) => {
+  const target = findTraceTarget(snapshot, "repository", snapshot.analysis.structural.targetPath);
+  if (target === void 0 || target.factors.length === 0) {
+    return null;
+  }
+  const weight = target.factors.reduce((sum, factor) => sum + factor.contribution, 0);
+  if (weight <= 0) {
+    return null;
+  }
+  const weighted = target.factors.reduce(
+    (sum, factor) => sum + factor.confidence * factor.contribution,
+    0
+  );
+  return round45(weighted / weight);
+};
+var createReport = (snapshot, diff) => {
+  const external = snapshot.analysis.external;
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repository: {
+      targetPath: snapshot.analysis.structural.targetPath,
+      repositoryScore: snapshot.analysis.risk.repositoryScore,
+      normalizedScore: snapshot.analysis.risk.normalizedScore,
+      riskTier: toRiskTier(snapshot.analysis.risk.repositoryScore),
+      confidence: repositoryConfidence(snapshot)
+    },
+    hotspots: hotspotItems(snapshot),
+    structural: {
+      cycleCount: snapshot.analysis.structural.metrics.cycleCount,
+      cycles: snapshot.analysis.structural.cycles.map(
+        (cycle) => [...cycle.nodes].sort((a, b) => a.localeCompare(b)).join(" -> ")
+      ),
+      fragileClusters: snapshot.analysis.risk.fragileClusters.map((cluster) => ({
+        id: cluster.id,
+        kind: cluster.kind,
+        score: cluster.score,
+        files: [...cluster.files].sort((a, b) => a.localeCompare(b))
+      }))
+    },
+    external: !external.available ? {
+      available: false,
+      reason: external.reason
+    } : {
+      available: true,
+      highRiskDependencies: [...external.highRiskDependencies].sort((a, b) => a.localeCompare(b)),
+      highRiskDevelopmentDependencies: [...external.highRiskDevelopmentDependencies].sort((a, b) => a.localeCompare(b)),
+      singleMaintainerDependencies: [...external.singleMaintainerDependencies].sort((a, b) => a.localeCompare(b)),
+      abandonedDependencies: [...external.abandonedDependencies].sort((a, b) => a.localeCompare(b))
+    },
+    appendix: {
+      snapshotSchemaVersion: snapshot.schemaVersion,
+      riskModelVersion: snapshot.riskModelVersion,
+      timestamp: snapshot.generatedAt,
+      normalization: "Scores are deterministic 0-100 outputs from risk-engine normalized factors and interaction terms.",
+      ...snapshot.analysisConfig === void 0 ? {} : { analysisConfig: snapshot.analysisConfig }
+    },
+    ...diff === void 0 ? {} : { diff }
+  };
+};
+var renderTextDiff = (report) => {
+  if (report.diff === void 0) {
+    return [];
+  }
+  return [
+    "",
+    "Diff",
+    `  repositoryScoreDelta: ${report.diff.repositoryScoreDelta}`,
+    `  normalizedScoreDelta: ${report.diff.normalizedScoreDelta}`,
+    `  newHotspots: ${report.diff.newHotspots.join(", ") || "none"}`,
+    `  resolvedHotspots: ${report.diff.resolvedHotspots.join(", ") || "none"}`,
+    `  newCycles: ${report.diff.newCycles.join(", ") || "none"}`,
+    `  resolvedCycles: ${report.diff.resolvedCycles.join(", ") || "none"}`
+  ];
+};
+var renderTextReport = (report) => {
+  const lines = [];
+  lines.push("Repository Summary");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  repositoryScore: ${report.repository.repositoryScore}`);
+  lines.push(`  normalizedScore: ${report.repository.normalizedScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push(`  confidence: ${report.repository.confidence ?? "n/a"}`);
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+    for (const factor of hotspot.topFactors) {
+      lines.push(
+        `    factor: ${factor.label} contribution=${factor.contribution} confidence=${factor.confidence}`
+      );
+      lines.push(`    evidence: ${factor.evidence}`);
+    }
+    lines.push(`    actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+    lines.push(`    levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("Structural Observations");
+  lines.push(`  cycleCount: ${report.structural.cycleCount}`);
+  lines.push(`  cycles: ${report.structural.cycles.join(" ; ") || "none"}`);
+  lines.push(`  fragileClusters: ${report.structural.fragileClusters.length}`);
+  lines.push("");
+  lines.push("External Exposure");
+  if (!report.external.available) {
+    lines.push(`  unavailable: ${report.external.reason}`);
+  } else {
+    lines.push(`  highRiskDependencies: ${report.external.highRiskDependencies.join(", ") || "none"}`);
+    lines.push(
+      `  highRiskDevelopmentDependencies: ${report.external.highRiskDevelopmentDependencies.join(", ") || "none"}`
+    );
+    lines.push(
+      `  singleMaintainerDependencies: ${report.external.singleMaintainerDependencies.join(", ") || "none"}`
+    );
+    lines.push(`  abandonedDependencies: ${report.external.abandonedDependencies.join(", ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("Appendix");
+  lines.push(`  snapshotSchemaVersion: ${report.appendix.snapshotSchemaVersion}`);
+  lines.push(`  riskModelVersion: ${report.appendix.riskModelVersion}`);
+  lines.push(`  timestamp: ${report.appendix.timestamp}`);
+  lines.push(`  normalization: ${report.appendix.normalization}`);
+  lines.push(...renderTextDiff(report));
+  return lines.join("\n");
+};
+var renderMarkdownDiff = (report) => {
+  if (report.diff === void 0) {
+    return [];
+  }
+  return [
+    "",
+    "## Diff",
+    `- repositoryScoreDelta: \`${report.diff.repositoryScoreDelta}\``,
+    `- normalizedScoreDelta: \`${report.diff.normalizedScoreDelta}\``,
+    `- newHotspots: ${report.diff.newHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- resolvedHotspots: ${report.diff.resolvedHotspots.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- newCycles: ${report.diff.newCycles.map((item) => `\`${item}\``).join(", ") || "none"}`,
+    `- resolvedCycles: ${report.diff.resolvedCycles.map((item) => `\`${item}\``).join(", ") || "none"}`
+  ];
+};
+var renderMarkdownReport = (report) => {
+  const lines = [];
+  lines.push("# CodeSentinel Report");
+  lines.push("");
+  lines.push("## Repository Summary");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- repositoryScore: \`${report.repository.repositoryScore}\``);
+  lines.push(`- normalizedScore: \`${report.repository.normalizedScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push(`- confidence: \`${report.repository.confidence ?? "n/a"}\``);
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots) {
+    lines.push(`- **${hotspot.target}** (score: \`${hotspot.score}\`)`);
+    lines.push(`  - Top factors:`);
+    for (const factor of hotspot.topFactors) {
+      lines.push(
+        `  - ${factor.label}: contribution=\`${factor.contribution}\`, confidence=\`${factor.confidence}\``
+      );
+      lines.push(`  - evidence: \`${factor.evidence}\``);
+    }
+    lines.push(`  - Suggested actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+    lines.push(`  - Biggest levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("## Structural Observations");
+  lines.push(`- cycles detected: \`${report.structural.cycleCount}\``);
+  lines.push(`- cycles: ${report.structural.cycles.map((cycle) => `\`${cycle}\``).join(", ") || "none"}`);
+  lines.push(`- fragile clusters: \`${report.structural.fragileClusters.length}\``);
+  lines.push("");
+  lines.push("## External Exposure Summary");
+  if (!report.external.available) {
+    lines.push(`- unavailable: \`${report.external.reason}\``);
+  } else {
+    lines.push(`- high-risk dependencies: ${report.external.highRiskDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`);
+    lines.push(
+      `- high-risk development dependencies: ${report.external.highRiskDevelopmentDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`
+    );
+    lines.push(
+      `- single maintainer dependencies: ${report.external.singleMaintainerDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`
+    );
+    lines.push(`- abandoned dependencies: ${report.external.abandonedDependencies.map((item) => `\`${item}\``).join(", ") || "none"}`);
+  }
+  lines.push("");
+  lines.push("## Appendix");
+  lines.push(`- snapshot schema: \`${report.appendix.snapshotSchemaVersion}\``);
+  lines.push(`- risk model version: \`${report.appendix.riskModelVersion}\``);
+  lines.push(`- timestamp: \`${report.appendix.timestamp}\``);
+  lines.push(`- normalization: ${report.appendix.normalization}`);
+  lines.push(...renderMarkdownDiff(report));
+  return lines.join("\n");
+};
+var createSnapshot = (input) => ({
+  schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+  generatedAt: input.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+  riskModelVersion: RISK_MODEL_VERSION,
+  source: {
+    targetPath: input.analysis.structural.targetPath
+  },
+  analysis: input.analysis,
+  ...input.trace === void 0 ? {} : { trace: input.trace },
+  ...input.analysisConfig === void 0 ? {} : { analysisConfig: input.analysisConfig }
+});
+var parseSnapshot = (raw) => {
+  const parsed = JSON.parse(raw);
+  if (parsed.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+    throw new Error("unsupported_snapshot_schema");
+  }
+  if (typeof parsed.generatedAt !== "string") {
+    throw new Error("invalid_snapshot_generated_at");
+  }
+  if (parsed.analysis === void 0 || parsed.analysis === null) {
+    throw new Error("invalid_snapshot_analysis");
+  }
+  if (parsed.source === void 0 || typeof parsed.source.targetPath !== "string") {
+    throw new Error("invalid_snapshot_source");
+  }
+  return parsed;
+};
+var formatReport = (report, format) => {
+  if (format === "json") {
+    return JSON.stringify(report, null, 2);
+  }
+  if (format === "md") {
+    return renderMarkdownReport(report);
+  }
+  return renderTextReport(report);
+};
+
+// src/application/run-report-command.ts
+var buildSnapshot = async (inputPath, authorIdentityMode, includeTrace, logger) => {
+  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: includeTrace });
+  const summary = {
+    ...analysisInputs,
+    risk: evaluation.summary
+  };
+  return createSnapshot({
+    analysis: summary,
+    ...evaluation.trace === void 0 ? {} : { trace: evaluation.trace },
+    analysisConfig: {
+      authorIdentityMode,
+      includeTrace
+    }
+  });
+};
+var runReportCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
+  logger.info("building analysis snapshot");
+  const current = await buildSnapshot(inputPath, authorIdentityMode, options.includeTrace, logger);
+  if (options.snapshotPath !== void 0) {
+    await writeFile(options.snapshotPath, JSON.stringify(current, null, 2), "utf8");
+    logger.info(`snapshot written: ${options.snapshotPath}`);
+  }
+  let report;
+  if (options.comparePath === void 0) {
+    report = createReport(current);
+  } else {
+    logger.info(`loading baseline snapshot: ${options.comparePath}`);
+    const baselineRaw = await readFile(options.comparePath, "utf8");
+    const baseline = parseSnapshot(baselineRaw);
+    const diff = compareSnapshots(current, baseline);
+    report = createReport(current, diff);
+  }
+  const rendered = formatReport(report, options.format);
+  if (options.outputPath !== void 0) {
+    await writeFile(options.outputPath, rendered, "utf8");
+    logger.info(`report written: ${options.outputPath}`);
+  }
+  return { report, rendered };
+};
+
 // src/application/run-explain-command.ts
 var selectTargets = (trace, summary, options) => {
   if (options.file !== void 0) {
@@ -4163,6 +4631,39 @@ program.command("dependency-risk").argument("<dependency>", "dependency spec to
 `);
   }
 );
+program.command("report").argument("[path]", "path to the project to analyze").addOption(
+  new Option(
+    "--author-identity <mode>",
+    "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
+  ).choices(["likely_merge", "strict_email"]).default("likely_merge")
+).addOption(
+  new Option(
+    "--log-level <level>",
+    "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
+  ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
+).addOption(
+  new Option("--format <mode>", "output format: text, json, md").choices(["text", "json", "md"]).default("text")
+).option("--output <path>", "write rendered report to a file path").option("--compare <baseline>", "compare against a baseline snapshot JSON file").option("--snapshot <path>", "write current snapshot JSON artifact").option("--no-trace", "disable trace embedding in generated snapshot").action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const result = await runReportCommand(
+      path,
+      options.authorIdentity,
+      {
+        format: options.format,
+        ...options.output === void 0 ? {} : { outputPath: options.output },
+        ...options.compare === void 0 ? {} : { comparePath: options.compare },
+        ...options.snapshot === void 0 ? {} : { snapshotPath: options.snapshot },
+        includeTrace: options.trace
+      },
+      logger
+    );
+    if (options.output === void 0) {
+      process.stdout.write(`${result.rendered}
+`);
+    }
+  }
+);
 if (process.argv.length <= 2) {
   program.outputHelp();
   process.exit(0);