@getcodesentinel/codesentinel 1.9.5 → 1.10.0

package/README.md

@@ -178,6 +178,9 @@ codesentinel analyze . --author-identity likely_merge
 # Deterministic: strict email identity, no heuristic merging
 codesentinel analyze . --author-identity strict_email
 
+# Tune recency window (days) used for evolution volatility
+codesentinel analyze . --recent-window-days 60
+
 # Quiet mode (only JSON output)
 codesentinel analyze . --log-level silent
 
@@ -203,6 +206,7 @@ codesentinel explain . --module src/components
 # Explain in markdown or json
 codesentinel explain . --format md
 codesentinel explain . --format json
+codesentinel explain . --recent-window-days 60
 
 # Report generation (human + machine readable)
 codesentinel report .
@@ -223,6 +227,7 @@ Notes:
 - At `info`/`debug`, structural, evolution, and dependency stages report progress so long analyses are observable.
 - `--output summary` (default) prints a compact result for terminal use.
 - `--output json` (or `--json`) prints the full analysis object.
+- `--recent-window-days <days>` customizes the git recency window used to compute `recentVolatility` (default: `30`).
 
 When running through pnpm, pass CLI arguments after `--`:
 
@@ -318,7 +323,7 @@ Exit codes:
 
 Text/markdown output includes:
 
-- repository score and risk band (`low|moderate|high|very_high`)
+- repository score and risk band (`low|moderate|elevated|high|very_high`)
 - plain-language primary drivers
 - concrete evidence values behind those drivers
 - intersected signals (composite interaction terms)

package/dist/index.js

@@ -4992,7 +4992,7 @@ var createEvolutionProgressReporter = (logger) => {
     }
   };
 };
-var collectAnalysisInputs = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
+var collectAnalysisInputs = async (inputPath, authorIdentityMode, options = {}, logger = createSilentLogger()) => {
   const invocationCwd = process.env["INIT_CWD"] ?? process.cwd();
   const targetPath = resolveTargetPath(inputPath, invocationCwd);
   logger.info(`analyzing repository: ${targetPath}`);
@@ -5008,7 +5008,10 @@ var collectAnalysisInputs = async (inputPath, authorIdentityMode, logger = creat
   const evolution = analyzeRepositoryEvolutionFromGit(
     {
       repositoryPath: targetPath,
-      config: { authorIdentityMode }
+      config: {
+        authorIdentityMode,
+        ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+      }
     },
     createEvolutionProgressReporter(logger)
   );
@@ -5037,8 +5040,8 @@ var collectAnalysisInputs = async (inputPath, authorIdentityMode, logger = creat
     external
   };
 };
-var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
-  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+var runAnalyzeCommand = async (inputPath, authorIdentityMode, options = {}, logger = createSilentLogger()) => {
+  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, options, logger);
   logger.info("computing risk summary");
   const risk = computeRepositoryRiskSummary(analysisInputs);
   logger.info(`analysis completed (repositoryScore=${risk.repositoryScore})`);
@@ -5053,7 +5056,14 @@ import { readFile, writeFile } from "fs/promises";
 
 // src/application/build-analysis-snapshot.ts
 var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logger) => {
-  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  const analysisInputs = await collectAnalysisInputs(
+    inputPath,
+    authorIdentityMode,
+    {
+      ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+    },
+    logger
+  );
   const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: options.includeTrace });
   const summary = {
     ...analysisInputs,
@@ -5064,7 +5074,8 @@ var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logge
     ...evaluation.trace === void 0 ? {} : { trace: evaluation.trace },
     analysisConfig: {
       authorIdentityMode,
-      includeTrace: options.includeTrace
+      includeTrace: options.includeTrace,
+      recentWindowDays: analysisInputs.evolution.available ? analysisInputs.evolution.metrics.recentWindowDays : options.recentWindowDays ?? null
     }
   });
 };
@@ -5096,7 +5107,10 @@ var runCheckCommand = async (inputPath, authorIdentityMode, options, logger = cr
   const current = await buildAnalysisSnapshot(
     inputPath,
     authorIdentityMode,
-    { includeTrace: options.includeTrace },
+    {
+      includeTrace: options.includeTrace,
+      ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+    },
     logger
   );
   let baseline;
@@ -5163,7 +5177,10 @@ var runCiCommand = async (inputPath, authorIdentityMode, options, logger = creat
   const current = await buildAnalysisSnapshot(
     inputPath,
     authorIdentityMode,
-    { includeTrace: options.includeTrace },
+    {
+      includeTrace: options.includeTrace,
+      ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+    },
     logger
   );
   if (options.snapshotPath !== void 0) {
@@ -5218,7 +5235,10 @@ var runCiCommand = async (inputPath, authorIdentityMode, options, logger = creat
           return buildAnalysisSnapshot(
             baselineTargetPath,
             authorIdentityMode,
-            { includeTrace: options.includeTrace },
+            {
+              includeTrace: options.includeTrace,
+              ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+            },
             logger
           );
         }
@@ -5290,7 +5310,10 @@ var runReportCommand = async (inputPath, authorIdentityMode, options, logger = c
   const current = await buildAnalysisSnapshot(
     inputPath,
     authorIdentityMode,
-    { includeTrace: options.includeTrace },
+    {
+      includeTrace: options.includeTrace,
+      ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+    },
     logger
   );
   if (options.snapshotPath !== void 0) {
@@ -5336,7 +5359,14 @@ var selectTargets = (trace, summary, options) => {
   );
 };
 var runExplainCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
-  const analysisInputs = await collectAnalysisInputs(inputPath, authorIdentityMode, logger);
+  const analysisInputs = await collectAnalysisInputs(
+    inputPath,
+    authorIdentityMode,
+    {
+      ...options.recentWindowDays === void 0 ? {} : { recentWindowDays: options.recentWindowDays }
+    },
+    logger
+  );
   logger.info("computing explainable risk summary");
   const evaluation = evaluateRepositoryRisk(analysisInputs, { explain: true });
   if (evaluation.trace === void 0) {
@@ -5358,6 +5388,13 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
 var program = new Command();
 var packageJsonPath = resolve5(dirname(fileURLToPath(import.meta.url)), "../package.json");
 var { version } = JSON.parse(readFileSync2(packageJsonPath, "utf8"));
+var parseRecentWindowDays = (value) => {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error("--recent-window-days must be a positive integer");
+  }
+  return parsed;
+};
 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(
   new Option(
@@ -5371,10 +5408,20 @@ program.command("analyze").argument("[path]", "path to the project to analyze").
   ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
 ).addOption(
   new Option("--output <mode>", "output mode: summary (default) or json (full analysis object)").choices(["summary", "json"]).default("summary")
-).option("--json", "shortcut for --output json").action(
+).option("--json", "shortcut for --output json").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 summary = await runAnalyzeCommand(path, options.authorIdentity, logger);
+    const summary = await runAnalyzeCommand(
+      path,
+      options.authorIdentity,
+      { recentWindowDays: options.recentWindowDays },
+      logger
+    );
     const outputMode = options.json === true ? "json" : options.output;
     process.stdout.write(`${formatAnalyzeOutput(summary, outputMode)}
 `);
@@ -5391,6 +5438,11 @@ program.command("explain").argument("[path]", "path to the project to analyze").
     "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
   ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
 ).option("--file <path>", "explain a specific file target").option("--module <name>", "explain a specific module target").option("--top <count>", "number of top hotspots to explain when no target is selected", "5").addOption(
+  new Option(
+    "--recent-window-days <days>",
+    "git recency window in days used for evolution volatility metrics"
+  ).argParser(parseRecentWindowDays).default(30)
+).addOption(
   new Option("--format <mode>", "output format: text, json, md").choices(["text", "json", "md"]).default("md")
 ).action(
   async (path, options) => {
@@ -5400,6 +5452,7 @@ program.command("explain").argument("[path]", "path to the project to analyze").
       ...options.file === void 0 ? {} : { file: options.file },
       ...options.module === void 0 ? {} : { module: options.module },
       top: Number.isFinite(top) ? top : 5,
+      recentWindowDays: options.recentWindowDays,
       format: options.format
     };
     const result = await runExplainCommand(path, options.authorIdentity, explainOptions, logger);
@@ -5449,7 +5502,12 @@ program.command("report").argument("[path]", "path to the project to analyze").a
   ).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").action(
+).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(
+    "--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 result = await runReportCommand(
@@ -5460,7 +5518,8 @@ 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 },
-        includeTrace: options.trace
+        includeTrace: options.trace,
+        recentWindowDays: options.recentWindowDays
       },
       logger
     );
@@ -5525,7 +5584,12 @@ program.command("check").argument("[path]", "path to the project to analyze").ad
   new Option("--fail-on <level>", "failing severity threshold").choices(["error", "warn"]).default("error")
 ).addOption(
   new Option("--format <mode>", "output format: text, json, md").choices(["text", "json", "md"]).default("text")
-).option("--output <path>", "write check output to a file path").option("--no-trace", "disable trace embedding in generated snapshot").action(
+).option("--output <path>", "write check output to a file path").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);
     try {
@@ -5536,6 +5600,7 @@ program.command("check").argument("[path]", "path to the project to analyze").ad
         {
           ...options.compare === void 0 ? {} : { baselinePath: options.compare },
           includeTrace: options.trace,
+          recentWindowDays: options.recentWindowDays,
           gateConfig,
           outputFormat: options.format,
           ...options.output === void 0 ? {} : { outputPath: options.output }
@@ -5584,7 +5649,12 @@ program.command("ci").argument("[path]", "path to the project to analyze").addOp
   "comma-separated default branch candidates for auto baseline resolution (for example: main,master)"
 ).option("--snapshot <path>", "write current snapshot JSON to path").option("--report <path>", "write markdown CI summary report").option("--json-output <path>", "write machine-readable CI JSON output").option("--max-repo-delta <value>", "maximum allowed normalized repository score increase").option("--no-new-cycles", "fail if new structural cycles are introduced").option("--no-new-high-risk-deps", "fail if new high-risk direct dependencies are introduced").option("--max-new-hotspots <count>", "maximum allowed number of new hotspots").option("--new-hotspot-score-threshold <score>", "minimum hotspot score to count as new hotspot").option("--max-repo-score <score>", "absolute repository score limit (0..100)").addOption(
   new Option("--fail-on <level>", "failing severity threshold").choices(["error", "warn"]).default("error")
-).option("--no-trace", "disable trace embedding in generated snapshot").action(
+).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);
     try {
@@ -5602,6 +5672,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,
+          recentWindowDays: options.recentWindowDays,
           gateConfig
         },
         logger