@getcodesentinel/codesentinel 1.13.0 → 1.15.0

package/README.md

@@ -100,6 +100,8 @@ The CLI output now includes a deterministic `risk` block composed from those dim
 - `dependencyAmplificationZones`
 - file/module/dependency score tables
 
+It also includes a deterministic `quality` block (`qualityScore`, dimension scores, and actionable top issues) computed independently from risk.
+
 The goal is a practical, engineering-grade model that supports both strategic architecture decisions and daily code review workflows.
 
 ## Monorepo Layout
@@ -109,6 +111,7 @@ The goal is a practical, engineering-grade model that supports both strategic ar
 - `packages/git-analyzer`: Git history and evolutionary signals.
 - `packages/dependency-firewall`: external dependency and supply chain signals.
 - `packages/risk-engine`: risk aggregation and scoring model.
+- `packages/quality-engine`: quality posture aggregation and scoring model.
 - `packages/reporter`: structured report output (console, JSON, CI).
 - `packages/governance`: CI gate evaluation and enforcement policy checks.
 - `packages/cli`: user-facing CLI entrypoint.
@@ -140,6 +143,7 @@ Then run:
 
 ```bash
 codesentinel analyze [path]
+codesentinel run [path]
 codesentinel explain [path]
 codesentinel report [path]
 codesentinel check [path]
@@ -150,6 +154,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 +249,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 +278,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).
@@ -347,12 +363,13 @@ Filters:
 
 ## Understanding Analyze Output
 
-`codesentinel analyze` returns one JSON document with four top-level blocks:
+`codesentinel analyze` returns one JSON document with five 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`.
+- `quality`: deterministic code health posture from local structural/evolution/test signals.
 
 Minimal shape:
 
@@ -367,6 +384,16 @@ Minimal shape:
     "hotspots": [],
     "fragileClusters": [],
     "dependencyAmplificationZones": []
+  },
+  "quality": {
+    "qualityScore": 0,
+    "normalizedScore": 0,
+    "dimensions": {
+      "modularity": 0,
+      "changeHygiene": 0,
+      "testHealth": 0
+    },
+    "topIssues": []
   }
 }
 ```
@@ -378,6 +405,11 @@ How to read `risk` first:
 - `fragileClusters`: groups of files with structural-cycle or co-change fragility.
 - `dependencyAmplificationZones`: files where external dependency pressure intersects with local fragility.
 
+Score direction:
+
+- `risk.riskScore`: higher means higher risk (worse).
+- `quality.qualityScore`: higher means better quality posture.
+
 Interpretation notes:
 
 - Scores are deterministic for the same inputs and config.