@getcodesentinel/codesentinel 1.14.0 → 1.16.0

package/README.md

@@ -76,7 +76,7 @@ CI example:
     BASE_REF="${GITHUB_BASE_REF:-main}"
     git fetch origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}"
 - name: Run CodeSentinel
-  run: npx codesentinel ci --baseline-ref auto --max-repo-score 55 --max-repo-delta 0.03 --no-new-cycles --no-new-high-risk-deps --max-new-hotspots 2 --fail-on error
+  run: npx codesentinel ci --baseline-ref auto --max-risk-score 55 --max-risk-delta 0.03 --min-quality-score 65 --max-quality-delta 0.03 --no-new-cycles --no-new-high-risk-deps --max-new-hotspots 2 --fail-on error
 ```
 
 `--baseline-ref auto` requires enough git history to resolve a baseline deterministically. In GitHub Actions, use `fetch-depth: 0` and ensure the CI base branch ref is fetched.
@@ -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,8 @@ 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-signals`: local quality signal collection (lint, diagnostics, complexity, duplication, coverage).
+- `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.
@@ -164,9 +168,9 @@ codesentinel report
 codesentinel report --format md --output report.md
 codesentinel report --snapshot snapshot.json
 codesentinel report --compare baseline.json --format text
-codesentinel check --compare baseline.json --max-repo-delta 0.03 --no-new-cycles
+codesentinel check --compare baseline.json --max-risk-delta 0.03 --no-new-cycles
 codesentinel ci --baseline baseline.json --snapshot current.json --report report.md --fail-on error
-codesentinel ci --baseline-ref origin/main --max-repo-delta 0.03 --no-new-cycles
+codesentinel ci --baseline-ref origin/main --max-risk-delta 0.03 --no-new-cycles
 codesentinel ci --baseline-ref auto --fail-on error
 codesentinel dependency-risk react
 codesentinel dependency-risk react@19.0.0
@@ -253,7 +257,7 @@ pnpm dev -- explain . --file src/app/page.tsx
 pnpm dev -- report
 pnpm dev -- report . --format md --output report.md
 pnpm dev -- report . --compare baseline.json --format text
-pnpm dev -- check . --compare baseline.json --max-repo-delta 0.03 --no-new-cycles
+pnpm dev -- check . --compare baseline.json --max-risk-delta 0.03 --no-new-cycles
 pnpm dev -- ci . --baseline baseline.json --snapshot current.json --report report.md --fail-on warn
 ```
 
@@ -279,7 +283,7 @@ Diff mode compares snapshots and reports:
 
 `codesentinel run` is a convenience command that emits `analyze + explain + report` in one execution.
 
-- formats: `text`, `md`, `json` (`text` default)
+- formats: `text`, `md`, `json` (`md` 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`
@@ -290,11 +294,13 @@ Diff mode compares snapshots and reports:
 
 Supported gates:
 
-- `--max-repo-delta <value>`
+- `--max-risk-delta <value>`
+- `--max-quality-delta <value>`
 - `--no-new-cycles`
 - `--no-new-high-risk-deps`
 - `--max-new-hotspots <count>`
-- `--max-repo-score <score>`
+- `--max-risk-score <score>`
+- `--min-quality-score <score>`
 - `--new-hotspot-score-threshold <score>`
 - `--fail-on error|warn`
 
@@ -360,12 +366,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:
 
@@ -380,6 +387,23 @@ Minimal shape:
     "hotspots": [],
     "fragileClusters": [],
     "dependencyAmplificationZones": []
+  },
+  "quality": {
+    "qualityScore": 0,
+    "normalizedScore": 0,
+    "dimensions": {
+      "modularity": 0,
+      "changeHygiene": 0,
+      "staticAnalysis": 0,
+      "complexity": 0,
+      "duplication": 0,
+      "testHealth": 0
+    },
+    "topIssues": [],
+    "trace": {
+      "schemaVersion": "1",
+      "dimensions": []
+    }
   }
 }
 ```
@@ -391,6 +415,30 @@ 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.
+- `quality.trace`: per-dimension factor traces with normalized metrics and evidence.
+
+Quality v2 dimensions and weights:
+
+- `modularity` (`0.20`): cycles + fan-in/fan-out concentration.
+- `changeHygiene` (`0.20`): churn/volatility/coupling concentration + TODO/FIXME comment load.
+- `staticAnalysis` (`0.20`): ESLint issue rates + TypeScript diagnostics.
+- `complexity` (`0.15`): cyclomatic complexity pressure.
+- `duplication` (`0.10`): duplicated block/line ratio.
+- `testHealth` (`0.15`): test file presence + optional coverage summary input.
+
+Signal ingestion (deterministic, local):
+
+- ESLint issues are collected via ESLint API when configuration is available.
+- TypeScript diagnostics are collected from local `tsconfig.json` program diagnostics.
+- Complexity and duplication are derived from local source files.
+- Coverage input is optional:
+  - default path: `<target>/coverage/coverage-summary.json`
+  - override path: `CODESENTINEL_QUALITY_COVERAGE_SUMMARY`
+
 Interpretation notes:
 
 - Scores are deterministic for the same inputs and config.