@getcodesentinel/codesentinel 1.9.4 → 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

@@ -254,6 +254,46 @@ var DEFAULT_EXTERNAL_ANALYSIS_CONFIG = {
   maxHighRiskDependencies: 100,
   metadataRequestConcurrency: 8
 };
+var mapWithConcurrency = async (values, limit, handler) => {
+  const effectiveLimit = Math.max(1, limit);
+  const workerCount = Math.min(effectiveLimit, values.length);
+  const results = new Array(values.length);
+  let index = 0;
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= values.length) {
+        return;
+      }
+      const value = values[current];
+      if (value !== void 0) {
+        results[current] = await handler(value);
+      }
+    }
+  });
+  await Promise.all(workers);
+  return results;
+};
+var collectDependencyMetadata = async (extraction, metadataProvider, concurrency, onProgress) => {
+  const directNames = new Set(extraction.directDependencies.map((dependency) => dependency.name));
+  let completed = 0;
+  return mapWithConcurrency(extraction.nodes, concurrency, async (node) => {
+    const result = {
+      key: `${node.name}@${node.version}`,
+      metadata: await metadataProvider.getMetadata(node.name, node.version, {
+        directDependency: directNames.has(node.name)
+      })
+    };
+    completed += 1;
+    onProgress?.({
+      completed,
+      total: extraction.nodes.length,
+      packageName: node.name
+    });
+    return result;
+  });
+};
 var LOCKFILE_CANDIDATES = [
   { fileName: "pnpm-lock.yaml", kind: "pnpm" },
   { fileName: "package-lock.json", kind: "npm" },
@@ -545,6 +585,24 @@ var parseYarnLock = (raw, directSpecs) => {
 var parseBunLock = (_raw, _directSpecs) => {
   throw new Error("unsupported_lockfile_format");
 };
+var parseLockfileExtraction = (lockfileKind, lockfileRaw, directSpecs) => {
+  switch (lockfileKind) {
+    case "pnpm":
+      return parsePnpmLockfile(lockfileRaw, directSpecs);
+    case "npm":
+    case "npm-shrinkwrap":
+      return {
+        ...parsePackageLock(lockfileRaw, directSpecs),
+        kind: lockfileKind
+      };
+    case "yarn":
+      return parseYarnLock(lockfileRaw, directSpecs);
+    case "bun":
+      return parseBunLock(lockfileRaw, directSpecs);
+    default:
+      throw new Error("unsupported_lockfile_format");
+  }
+};
 var parseRetryAfterMs = (value) => {
   if (value === null) {
     return null;
@@ -977,77 +1035,31 @@ var resolveRegistryGraphFromDirectSpecs = async (directSpecs, options) => {
     truncated
   };
 };
-var withDefaults = (overrides) => ({
-  ...DEFAULT_EXTERNAL_ANALYSIS_CONFIG,
-  ...overrides
-});
-var parseExtraction = (lockfileKind, lockfileRaw, directSpecs) => {
-  switch (lockfileKind) {
-    case "pnpm":
-      return parsePnpmLockfile(lockfileRaw, directSpecs);
-    case "npm":
-    case "npm-shrinkwrap":
-      return {
-        ...parsePackageLock(lockfileRaw, directSpecs),
-        kind: lockfileKind
-      };
-    case "yarn":
-      return parseYarnLock(lockfileRaw, directSpecs);
-    case "bun":
-      return parseBunLock(lockfileRaw, directSpecs);
-    default:
-      throw new Error("unsupported_lockfile_format");
-  }
-};
-var mapWithConcurrency = async (values, limit, handler) => {
-  const effectiveLimit = Math.max(1, limit);
-  const workerCount = Math.min(effectiveLimit, values.length);
-  const results = new Array(values.length);
-  let index = 0;
-  const workers = Array.from({ length: workerCount }, async () => {
-    while (true) {
-      const current = index;
-      index += 1;
-      if (current >= values.length) {
-        return;
-      }
-      const value = values[current];
-      if (value !== void 0) {
-        results[current] = await handler(value);
-      }
-    }
-  });
-  await Promise.all(workers);
-  return results;
-};
-var analyzeDependencyExposure = async (input, metadataProvider, onProgress) => {
-  const config = withDefaults(input.config);
-  const packageJson = loadPackageJson(input.repositoryPath);
+var prepareDependencyExtraction = async (repositoryPath) => {
+  const packageJson = loadPackageJson(repositoryPath);
   if (packageJson === null) {
     return {
-      targetPath: input.repositoryPath,
       available: false,
       reason: "package_json_not_found"
     };
   }
-  onProgress?.({ stage: "package_json_loaded" });
-  try {
-    const directSpecs = parsePackageJson(packageJson.raw);
-    const lockfile = selectLockfile(input.repositoryPath);
-    let extraction;
-    if (lockfile === null) {
-      const resolvedGraph = await resolveRegistryGraphFromDirectSpecs(directSpecs, {
-        maxNodes: 500,
-        maxDepth: 8
-      });
-      if (resolvedGraph.nodes.length === 0) {
-        return {
-          targetPath: input.repositoryPath,
-          available: false,
-          reason: "lockfile_not_found"
-        };
-      }
-      extraction = {
+  const directSpecs = parsePackageJson(packageJson.raw);
+  const lockfile = selectLockfile(repositoryPath);
+  if (lockfile === null) {
+    const resolvedGraph = await resolveRegistryGraphFromDirectSpecs(directSpecs, {
+      maxNodes: 500,
+      maxDepth: 8
+    });
+    if (resolvedGraph.nodes.length === 0) {
+      return {
+        available: false,
+        reason: "lockfile_not_found"
+      };
+    }
+    return {
+      available: true,
+      lockfileKind: "npm",
+      extraction: {
         kind: "npm",
         directDependencies: resolvedGraph.directDependencies.map((dependency) => ({
           name: dependency.name,
@@ -1055,46 +1067,61 @@ var analyzeDependencyExposure = async (input, metadataProvider, onProgress) => {
           scope: dependency.scope
         })),
         nodes: resolvedGraph.nodes
+      }
+    };
+  }
+  return {
+    available: true,
+    lockfileKind: lockfile.kind,
+    extraction: parseLockfileExtraction(lockfile.kind, lockfile.raw, directSpecs)
+  };
+};
+var withDefaults = (overrides) => ({
+  ...DEFAULT_EXTERNAL_ANALYSIS_CONFIG,
+  ...overrides
+});
+var analyzeDependencyExposure = async (input, metadataProvider, onProgress) => {
+  const config = withDefaults(input.config);
+  try {
+    const prepared = await prepareDependencyExtraction(input.repositoryPath);
+    if (!prepared.available) {
+      return {
+        targetPath: input.repositoryPath,
+        available: false,
+        reason: prepared.reason
       };
-      onProgress?.({ stage: "lockfile_selected", kind: "npm" });
-    } else {
-      extraction = parseExtraction(lockfile.kind, lockfile.raw, directSpecs);
-      onProgress?.({ stage: "lockfile_selected", kind: lockfile.kind });
     }
-    const directNames = new Set(extraction.directDependencies.map((dependency) => dependency.name));
+    onProgress?.({ stage: "package_json_loaded" });
+    onProgress?.({ stage: "lockfile_selected", kind: prepared.lockfileKind });
+    const { extraction } = prepared;
     onProgress?.({
       stage: "lockfile_parsed",
       dependencyNodes: extraction.nodes.length,
       directDependencies: extraction.directDependencies.length
     });
     onProgress?.({ stage: "metadata_fetch_started", total: extraction.nodes.length });
-    let completed = 0;
-    const metadataEntries = await mapWithConcurrency(
-      extraction.nodes,
+    const metadataEntries = await collectDependencyMetadata(
+      extraction,
+      metadataProvider,
       config.metadataRequestConcurrency,
-      async (node) => {
-        const result = {
-          key: `${node.name}@${node.version}`,
-          metadata: await metadataProvider.getMetadata(node.name, node.version, {
-            directDependency: directNames.has(node.name)
-          })
-        };
-        completed += 1;
-        onProgress?.({
-          stage: "metadata_fetch_progress",
-          completed,
-          total: extraction.nodes.length,
-          packageName: node.name
-        });
-        return result;
-      }
+      (event) => onProgress?.({
+        stage: "metadata_fetch_progress",
+        completed: event.completed,
+        total: event.total,
+        packageName: event.packageName
+      })
     );
     onProgress?.({ stage: "metadata_fetch_completed", total: extraction.nodes.length });
     const metadataByKey = /* @__PURE__ */ new Map();
     for (const entry of metadataEntries) {
       metadataByKey.set(entry.key, entry.metadata);
     }
-    const summary = buildExternalAnalysisSummary(input.repositoryPath, extraction, metadataByKey, config);
+    const summary = buildExternalAnalysisSummary(
+      input.repositoryPath,
+      extraction,
+      metadataByKey,
+      config
+    );
     if (summary.available) {
       onProgress?.({
         stage: "summary_built",
@@ -4965,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}`);
@@ -4981,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)
   );
@@ -5010,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})`);
@@ -5026,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,
@@ -5037,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
     }
   });
 };
@@ -5069,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;
@@ -5136,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) {
@@ -5191,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
           );
         }
@@ -5263,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) {
@@ -5309,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) {
@@ -5331,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(
@@ -5344,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)}
 `);
@@ -5364,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) => {
@@ -5373,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);
@@ -5422,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(
@@ -5433,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
     );
@@ -5498,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 {
@@ -5509,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 }
@@ -5557,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 {
@@ -5575,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