@getcodesentinel/codesentinel 1.13.0 → 1.14.0

package/README.md

@@ -140,6 +140,7 @@ Then run:
 
 ```bash
 codesentinel analyze [path]
+codesentinel run [path]
 codesentinel explain [path]
 codesentinel report [path]
 codesentinel check [path]
@@ -150,6 +151,8 @@ codesentinel dependency-risk <dependency[@version]>
 Examples:
 
 ```bash
+codesentinel run
+codesentinel run . --detail full --format text
 codesentinel analyze
 codesentinel analyze .
 codesentinel analyze ../project
@@ -243,6 +246,7 @@ pnpm dev -- analyze
 pnpm dev -- analyze .
 pnpm dev -- analyze ../project
 pnpm dev -- analyze . --author-identity strict_email
+pnpm dev -- run . --format text
 pnpm dev -- explain
 pnpm dev -- explain . --top 5 --format text
 pnpm dev -- explain . --file src/app/page.tsx
@@ -271,6 +275,15 @@ Diff mode compares snapshots and reports:
 - new/resolved cycles
 - dependency exposure list changes
 
+## Run Output
+
+`codesentinel run` is a convenience command that emits `analyze + explain + report` in one execution.
+
+- formats: `text`, `md`, `json` (`text` default)
+- detail levels: `--detail compact|standard|full` (`compact` default, `full` = full verbose sections)
+- explain target selectors: `--file <path>`, `--module <name>`, `--top <n>`
+- report diff/snapshot flags: `--compare <baseline.json>`, `--snapshot <path>`, `--no-trace`
+
 ## CI Mode
 
 `codesentinel check` evaluates enforcement gates against current analysis (and optional baseline diff).

package/dist/index.js

@@ -1736,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");
@@ -1813,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");
@@ -2461,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";
 
@@ -2544,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"])}`;
@@ -2676,20 +2676,15 @@ var renderText = (payload) => {
   lines.push("");
   lines.push("explanation:");
   lines.push(
-    `  why risky: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
+    `  key drivers: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
   );
   lines.push(
-    `  what specifically contributed: ${repositoryTopFactors.map((factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`).join(", ") || "insufficient data"}`
+    `  contributions: ${repositoryTopFactors.map(formatFactorContribution).join(", ") || "insufficient data"}`
   );
   lines.push(
-    `  dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
-  );
-  lines.push(
-    `  intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
-  );
-  lines.push(
-    `  what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+    `  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));
@@ -2717,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(
@@ -6029,6 +6018,118 @@ 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)"
@@ -6169,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;