@getcodesentinel/codesentinel 1.8.0 → 1.9.1

package/README.md

@@ -13,6 +13,66 @@ CodeSentinel is a structural and evolutionary risk analysis engine for modern Ty
 
 This repository contains the CodeSentinel monorepo, with structural, evolution, external dependency, and deterministic risk analysis engines exposed through a CLI.
 
+## Quick Start
+
+### 1) Install
+
+Global install (good for local/manual usage):
+
+```bash
+npm install -g @getcodesentinel/codesentinel
+```
+
+Project/CI install (recommended for CI and reproducibility):
+
+```bash
+npm install --save-dev @getcodesentinel/codesentinel
+```
+
+### 2) Analyze a project
+
+Run commands from the repository root you want to analyze. If you run from another directory, pass the target path explicitly (for example `codesentinel analyze /path/to/project`).
+
+```bash
+codesentinel analyze
+```
+
+### 3) Generate a report
+
+```bash
+codesentinel report --format md --output codesentinel-report.md
+```
+
+### 4) Run in CI
+
+Using local project install (no global install required):
+
+```bash
+npx codesentinel ci --baseline-ref auto --fail-on error
+```
+
+Or in package scripts:
+
+```json
+{
+  "scripts": {
+    "risk:ci": "codesentinel ci --baseline-ref auto --fail-on error"
+  }
+}
+```
+
+CI example:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- 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
+```
+
+`--baseline-ref auto` requires enough git history to resolve a baseline deterministically. In GitHub Actions, use `fetch-depth: 0`.
+
 ## Vision
 
 CodeSentinel combines three signals into a single, explainable risk profile:
@@ -40,6 +100,7 @@ The goal is a practical, engineering-grade model that supports both strategic ar
 - `packages/dependency-firewall`: external dependency and supply chain signals.
 - `packages/risk-engine`: risk 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.
 
 Each package is standalone, ESM-only, TypeScript-first, and built with `tsup`. The CLI depends on `core`; domain packages are kept decoupled to avoid circular dependencies.
@@ -71,6 +132,8 @@ Then run:
 codesentinel analyze [path]
 codesentinel explain [path]
 codesentinel report [path]
+codesentinel check [path]
+codesentinel ci [path]
 codesentinel dependency-risk <dependency[@version]>
 ```
 
@@ -88,6 +151,10 @@ 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 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 auto --fail-on error
 codesentinel dependency-risk react
 codesentinel dependency-risk react@19.0.0
 ```
@@ -160,6 +227,8 @@ 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 -- ci . --baseline baseline.json --snapshot current.json --report report.md --fail-on warn
 ```
 
 ## Report Output
@@ -179,6 +248,42 @@ Diff mode compares snapshots and reports:
 - new/resolved cycles
 - dependency exposure list changes
 
+## CI Mode
+
+`codesentinel check` evaluates enforcement gates against current analysis (and optional baseline diff).
+
+Supported gates:
+
+- `--max-repo-delta <value>`
+- `--no-new-cycles`
+- `--no-new-high-risk-deps`
+- `--max-new-hotspots <count>`
+- `--max-repo-score <score>`
+- `--new-hotspot-score-threshold <score>`
+- `--fail-on error|warn`
+
+`codesentinel ci` orchestrates snapshot + diff + gate evaluation + markdown summary generation.
+
+Baseline input modes:
+
+- `--baseline <path>`: use an existing snapshot JSON artifact.
+- `--baseline-ref <git-ref>`: resolve baseline from git (`origin/main`, `main`, `HEAD~1`) using an isolated temporary worktree. No checkout/stash of your current working tree.
+- `--baseline-ref auto`: deterministic resolver with ordered fallbacks:
+  - `--baseline-sha <sha>` if provided.
+  - CI base branch env vars (`GITHUB_BASE_REF`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, `BITBUCKET_PR_DESTINATION_BRANCH`) with `origin/<branch>` first, then `<branch>`.
+  - branch-aware defaults:
+    - on `main/master`: `HEAD~1`
+    - otherwise: `merge-base(HEAD, origin/main)` then `origin/master`, `main`, `master`
+- `--main-branch <name>` (repeatable) or `--main-branches "main,master,trunk"` customize default branch candidates used by `--baseline-ref auto`.
+
+Exit codes:
+
+- `0`: no failing violations
+- `1`: error-level violations
+- `2`: warn-level violations when `--fail-on=warn`
+- `3`: invalid configuration
+- `4`: internal execution error
+
 ## Explain Output
 
 `codesentinel explain` uses the same risk-engine scoring model as `analyze` and adds structured explanation traces.