@codesentinel/codesentinel 1.2.0 → 1.3.0

package/README.md

@@ -12,6 +12,14 @@ CodeSentinel combines three signals into a single, explainable risk profile:
 - **Evolutionary risk**: change frequency, hotspots, bus factor, volatility.
 - **External risk**: transitive dependency exposure, maintainer risk, staleness and abandonment indicators.
 
+The CLI output now includes a deterministic `risk` block composed from those dimensions:
+
+- `repositoryScore` and `normalizedScore`
+- ranked `hotspots`
+- `fragileClusters` (structural cycles + change coupling components)
+- `dependencyAmplificationZones`
+- file/module/dependency score tables
+
 The goal is a practical, engineering-grade model that supports both strategic architecture decisions and daily code review workflows.
 
 ## Monorepo Layout
@@ -69,6 +77,19 @@ codesentinel analyze . --author-identity likely_merge
 
 # Deterministic: strict email identity, no heuristic merging
 codesentinel analyze . --author-identity strict_email
+
+# Quiet mode (only JSON output)
+codesentinel analyze . --log-level silent
+
+# Verbose diagnostics to stderr
+codesentinel analyze . --log-level debug
+
+# Default compact output (summary)
+codesentinel analyze .
+
+# Full output (all sections and detailed arrays)
+codesentinel analyze . --output json
+codesentinel analyze . --json
 ```
 
 Notes:
@@ -77,6 +98,11 @@ Notes:
 - `strict_email` treats each canonical email as a distinct author, which avoids false merges but can split the same person across multiple emails.
 - Git mailmap is enabled (`git log --use-mailmap`). Put `.mailmap` in the repository being analyzed (the `codesentinel analyze [path]` target). Git will then deterministically unify known aliases before CodeSentinel computes `authorDistribution`.
 - `authorDistribution` returns whichever identity mode is selected.
+- Logs are emitted to `stderr` and JSON output is written to `stdout`, so CI redirection still works.
+- You can set a default log level with `CODESENTINEL_LOG_LEVEL` (`silent|error|warn|info|debug`).
+- 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.
 
 When running through pnpm, pass CLI arguments after `--`:
 
@@ -87,6 +113,73 @@ pnpm dev -- analyze ../project
 pnpm dev -- analyze . --author-identity strict_email
 ```
 
+## Understanding Analyze Output
+
+`codesentinel analyze` returns one JSON document with four top-level blocks:
+
+- `structural`: file dependency graph shape and graph metrics.
+- `evolution`: git-derived change behavior per file and coupling pairs.
+- `external`: dependency exposure for direct packages plus propagated transitive signals.
+- `risk`: deterministic composition of `structural + evolution + external`.
+
+Minimal shape:
+
+```json
+{
+  "structural": { "...": "..." },
+  "evolution": { "...": "..." },
+  "external": { "...": "..." },
+  "risk": {
+    "repositoryScore": 0,
+    "normalizedScore": 0,
+    "hotspots": [],
+    "fragileClusters": [],
+    "dependencyAmplificationZones": []
+  }
+}
+```
+
+How to read `risk` first:
+
+- `repositoryScore`: overall repository fragility index (`0..100`).
+- `hotspots`: ranked files to inspect first.
+- `fragileClusters`: groups of files with structural-cycle or co-change fragility.
+- `dependencyAmplificationZones`: files where external dependency pressure intersects with local fragility.
+
+Interpretation notes:
+
+- Scores are deterministic for the same inputs and config.
+- Scores are meant for within-repo prioritization and trend tracking.
+- Full model details and limits are in `packages/risk-engine/README.md`.
+
+### Score Guide
+
+Use these ranges as operational guidance:
+
+- `0-20`: low fragility.
+- `20-40`: moderate fragility.
+- `40-60`: elevated fragility (prioritize top hotspots).
+- `60-80`: high fragility (expect higher change coordination cost).
+- `80-100`: very high fragility (investigate immediately).
+
+These ranges are heuristics for triage, not incident probability.
+
+### What Moves Scores
+
+`risk.repositoryScore` and `risk.fileScores[*].score` increase when:
+
+- structurally central files/modules change frequently,
+- ownership is highly concentrated in volatile files,
+- files in central areas are exposed to high external dependency pressure,
+- tightly coupled change patterns emerge.
+
+They decrease when:
+
+- change concentrates less around central files,
+- ownership spreads or volatility decreases,
+- dependency pressure decreases (shallower trees, fewer high-risk signals),
+- hotspot concentration drops.
+
 ### External Risk Signal Semantics
 
 For `external.dependencies`, each direct dependency now exposes three signal fields: