@getcodesentinel/codesentinel 1.7.0 → 1.9.0

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"
+  }
+}
+```
+
+Example CI policy:
+
+```bash
+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
+```
+
 ## 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.
@@ -70,6 +131,9 @@ Then run:
 ```bash
 codesentinel analyze [path]
 codesentinel explain [path]
+codesentinel report [path]
+codesentinel check [path]
+codesentinel ci [path]
 codesentinel dependency-risk <dependency[@version]>
 ```
 
@@ -83,6 +147,14 @@ codesentinel explain
 codesentinel explain . --top 5 --format text
 codesentinel explain . --file src/app/page.tsx
 codesentinel explain . --module src/components
+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
 ```
@@ -121,6 +193,13 @@ codesentinel explain . --module src/components
 # Explain in markdown or json
 codesentinel explain . --format md
 codesentinel explain . --format json
+
+# Report generation (human + machine readable)
+codesentinel report .
+codesentinel report . --format md --output report.md
+codesentinel report . --format json
+codesentinel report . --snapshot snapshot.json
+codesentinel report . --compare baseline.json --format text
 ```
 
 Notes:
@@ -145,8 +224,66 @@ pnpm dev -- analyze . --author-identity strict_email
 pnpm dev -- explain
 pnpm dev -- explain . --top 5 --format text
 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
+
+`codesentinel report` produces deterministic engineering artifacts from existing analysis outputs.
+
+- formats: `text`, `md`, `json`
+- optional file output: `--output <path>`
+- optional snapshot export: `--snapshot <path>`
+- optional diff mode: `--compare <baseline.json>`
+
+Diff mode compares snapshots and reports:
+
+- repository score deltas
+- file/module risk deltas
+- new/resolved hotspots
+- 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.
@@ -278,28 +415,6 @@ Propagation policy is explicit and deterministic:
 
 This keeps package-level facts local while still surfacing meaningful transitive exposure.
 
-## Release Automation
-
-- Pull requests to `main` run build and tests via `.github/workflows/ci.yml`.
-- Pull requests and release runs also validate the packed CLI artifact (`npm pack`) with install/execute smoke checks before publish.
-- Merges to `main` run semantic-release via `.github/workflows/release.yml`.
-- semantic-release bumps `packages/cli/package.json`, creates a GitHub release, publishes to npm, and pushes the version-bump commit back to `main`.
-- Dependabot is configured monthly in `.github/dependabot.yml` for npm and GitHub Actions updates.
-
-Trusted Publisher setup (no `NPM_TOKEN` secret):
-
-- In npm package settings for `@getcodesentinel/codesentinel`, add a Trusted Publisher.
-- Provider: `GitHub Actions`.
-- Repository: `getcodesentinel/codesentinel`.
-- Workflow filename: `release.yml`.
-- Environment name: leave empty unless you explicitly use a GitHub Actions environment in this workflow.
-
-Commit messages on `main` should follow Conventional Commits (example: `feat:`, `fix:`, `chore:`) so semantic-release can calculate versions automatically.
-
-## Contributing
-
-This project aims to be production-grade and minimal. If you add new dependencies or abstractions, justify them clearly and keep the architecture clean.
-
 ## ESM Import Policy
 
 - The workspace uses `TypeScript` with `moduleResolution: "NodeNext"` and ESM output.