\n\nCodeSentinel is a structural and evolutionary risk analysis engine for modern TypeScript/JavaScript codebases. It turns architecture, change history, and dependency health into a unified risk model that helps engineering teams spot fragility before it becomes failure.\n\nThis repository contains the CodeSentinel monorepo, with structural, evolution, external dependency, and deterministic risk analysis engines exposed through a CLI.\n\n## Quick Start\n\n### 1) Install\n\nGlobal install (good for local/manual usage):\n\n```bash\nnpm install -g @getcodesentinel/codesentinel\n```\n\nProject/CI install (recommended for CI and reproducibility):\n\n```bash\nnpm install --save-dev @getcodesentinel/codesentinel\n```\n\n### 2) Analyze a project\n\nRun 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`).\n\n```bash\ncodesentinel analyze\n```\n\n### 3) Generate a report\n\n```bash\ncodesentinel report --format md --output codesentinel-report.md\n```\n\n### 4) Run in CI\n\nUsing local project install (no global install required):\n\n```bash\nnpx codesentinel ci --baseline-ref auto --fail-on error\n```\n\nOr in package scripts:\n\n```json\n{\n \"scripts\": {\n \"risk:ci\": \"codesentinel ci --baseline-ref auto --fail-on error\"\n }\n}\n```\n\nCI example:\n\n```yaml\n- uses: actions/checkout@v4\n with:\n fetch-depth: 0\n filter: blob:none\n ref: ${{ github.event.pull_request.head.sha || github.sha }}\n- name: Ensure git history for CodeSentinel\n run: |\n set -euo pipefail\n git fetch --prune --unshallow || true\n BASE_REF=\"${GITHUB_BASE_REF:-main}\"\n git fetch origin \"+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}\"\n- name: Run CodeSentinel\n run: npx codesentinel ci --baseline-ref auto --max-risk-score 55 --max-risk-delta 0.03 --min-health-score 65 --max-health-delta 0.03 --no-new-cycles --no-new-high-risk-deps --max-new-hotspots 2 --fail-on error\n```\n\n`--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.\n\nA full workflow template is available at `examples/github-actions/codesentinel-ci.yml`.\n\n## Vision\n\nCodeSentinel combines three signals into a single, explainable risk profile:\n\n- **Structural risk**: dependency graph topology, cycles, coupling, fan-in/fan-out, boundary violations.\n- **Evolutionary risk**: change frequency, hotspots, bus factor, volatility.\n- **External risk**: transitive dependency exposure, maintainer risk, staleness and abandonment indicators.\n - Includes bounded popularity dampening (weekly npm downloads) as a secondary stability signal.\n\nThe CLI output now includes a deterministic `risk` block composed from those dimensions:\n\n- `riskScore` and `normalizedScore`\n- ranked `hotspots`\n- `fragileClusters` (structural cycles + change coupling components)\n- `dependencyAmplificationZones`\n- file/module/dependency score tables\n\nIt also includes a deterministic `health` block (`healthScore`, dimension scores, and actionable top issues) computed independently from risk.\n\nThe goal is a practical, engineering-grade model that supports both strategic architecture decisions and daily code review workflows.\n\n## Monorepo Layout\n\n- `packages/core`: shared domain types and cross-cutting services.\n- `packages/code-graph`: source graph analysis primitives.\n- `packages/git-analyzer`: Git history and evolutionary signals.\n- `packages/dependency-firewall`: external dependency and supply chain signals.\n- `packages/risk-engine`: risk aggregation and scoring model.\n- `packages/health-engine`: health posture aggregation and scoring model.\n- `packages/reporter`: structured report output (console, JSON, CI).\n- `packages/governance`: CI gate evaluation and enforcement policy checks.\n- `packages/cli`: user-facing CLI entrypoint.\n\nEach 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.\n\n## Requirements\n\n- Node.js 22+\n- pnpm\n\n## Commands\n\n- `pnpm install`\n- `pnpm build`\n- `pnpm dev`\n- `pnpm test`\n- `pnpm release`\n\n## CLI\n\nInstall globally with npm:\n\n```bash\nnpm install -g @getcodesentinel/codesentinel\n```\n\nThen run:\n\n```bash\ncodesentinel analyze [path]\ncodesentinel run [path]\ncodesentinel explain [path]\ncodesentinel report [path]\ncodesentinel check [path]\ncodesentinel ci [path]\ncodesentinel dependency-risk \ncodesentinel update\n```\n\nExamples:\n\n```bash\ncodesentinel run\ncodesentinel run . --detail full --format text\ncodesentinel analyze\ncodesentinel analyze .\ncodesentinel analyze ../project\ncodesentinel explain\ncodesentinel explain . --top 5 --format text\ncodesentinel explain . --file src/app/page.tsx\ncodesentinel explain . --module src/components\ncodesentinel report\ncodesentinel report --format md --output report.md\ncodesentinel report --snapshot snapshot.json\ncodesentinel report --compare baseline.json --format text\ncodesentinel check --compare baseline.json --max-risk-delta 0.03 --no-new-cycles\ncodesentinel ci --baseline baseline.json --snapshot current.json --report report.md --fail-on error\ncodesentinel ci --baseline-ref origin/main --max-risk-delta 0.03 --no-new-cycles\ncodesentinel ci --baseline-ref auto --fail-on error\ncodesentinel dependency-risk react\ncodesentinel dependency-risk react@19.0.0\ncodesentinel update\n```\n\nUse `codesentinel update` to manually check for a newer CLI release and install it without waiting for the startup notifier.\n\nAuthor identity mode:\n\n```bash\n# Default: heuristic merge of likely same person across emails\ncodesentinel analyze . --author-identity likely_merge\n\n# Deterministic: strict email identity, no heuristic merging\ncodesentinel analyze . --author-identity strict_email\n\n# Personal-project profile (down-weights single-maintainer ownership penalties)\ncodesentinel analyze . --scoring-profile personal\n\n# Tune recency window (days) used for evolution volatility\ncodesentinel analyze . --recent-window-days 60\n\n# Quiet mode (only JSON output)\ncodesentinel analyze . --log-level silent\n\n# Verbose diagnostics to stderr\ncodesentinel analyze . --log-level debug\n\n# Default compact output (summary)\ncodesentinel analyze .\n\n# Full output (all sections and detailed arrays)\ncodesentinel analyze . --output json\ncodesentinel analyze . --json\n\n# Explain top hotspots with narrative output\ncodesentinel explain .\n\n# Explain a specific file\ncodesentinel explain . --file src/app/page.tsx\n\n# Explain a specific module\ncodesentinel explain . --module src/components\n\n# Explain in markdown or json\ncodesentinel explain . --format md\ncodesentinel explain . --format json\ncodesentinel explain . --recent-window-days 60\n\n# Report generation (human + machine readable)\ncodesentinel report .\ncodesentinel report . --format md --output report.md\ncodesentinel report . --format json\ncodesentinel report . --snapshot snapshot.json\ncodesentinel report . --compare baseline.json --format text\n```\n\nNotes:\n\n- `likely_merge` (default) may merge multiple emails that likely belong to the same person based on repository history.\n- `strict_email` treats each canonical email as a distinct author, which avoids false merges but can split the same person across multiple emails.\n- 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 ownership distributions.\n- Evolution output includes both `authorDistributionByCommits` and `authorDistributionByChurn`, plus their derived `topAuthorShare...` and `busFactor...` fields.\n- Current scoring continues to use the commit-weighted ownership view (`...ByCommits`).\n- Logs are emitted to `stderr` and JSON output is written to `stdout`, so CI redirection still works.\n- You can set a default log level with `CODESENTINEL_LOG_LEVEL` (`silent|error|warn|info|debug`).\n- At `info`/`debug`, structural, evolution, and dependency stages report progress so long analyses are observable.\n- `--output summary` (default) prints a compact result for terminal use.\n- `--output json` (or `--json`) prints the full analysis object.\n- `--recent-window-days ` customizes the git recency window used to compute `recentVolatility` (default: `30`).\n- `--scoring-profile default|personal` selects scoring profile.\n - `default`: balanced team-oriented defaults.\n - `personal`: lowers single-maintainer ownership penalties for both risk and health ownership scoring.\n - `personal` does not remove structural, churn, volatility, external, or interaction risk; scores can still be elevated when those signals are high.\n\nWhen running through pnpm, pass CLI arguments after `--`:\n\n```bash\npnpm dev -- analyze\npnpm dev -- analyze .\npnpm dev -- analyze ../project\npnpm dev -- analyze . --author-identity strict_email\npnpm dev -- run . --format text\npnpm dev -- explain\npnpm dev -- explain . --top 5 --format text\npnpm dev -- explain . --file src/app/page.tsx\npnpm dev -- report\npnpm dev -- report . --format md --output report.md\npnpm dev -- report . --compare baseline.json --format text\npnpm dev -- check . --compare baseline.json --max-risk-delta 0.03 --no-new-cycles\npnpm dev -- ci . --baseline baseline.json --snapshot current.json --report report.md --fail-on warn\n```\n\n## Report Output\n\n`codesentinel report` produces deterministic engineering artifacts from existing analysis outputs.\n\n- default format: `md`\n- formats: `text`, `md`, `json`\n- optional file output: `--output `\n- optional snapshot export: `--snapshot `\n- optional diff mode: `--compare `\n\nDiff mode compares snapshots and reports:\n\n- repository score deltas\n- file/module risk deltas\n- new/resolved hotspots\n- new/resolved cycles\n- dependency exposure list changes\n\n## Run Output\n\n`codesentinel run` is a convenience command that emits `analyze + explain + report` in one execution.\n\n- formats: `text`, `md`, `json` (`md` default)\n- detail levels: `--detail compact|standard|full` (`compact` default, `full` = full verbose sections)\n- explain target selectors: `--file `, `--module `, `--top `\n- report diff/snapshot flags: `--compare `, `--snapshot `, `--no-trace`\n\n## CI Mode\n\n`codesentinel check` evaluates enforcement gates against current analysis (and optional baseline diff).\n\nSupported gates:\n\n- `--max-risk-delta `\n- `--max-health-delta `\n- `--no-new-cycles`\n- `--no-new-high-risk-deps`\n- `--max-new-hotspots `\n- `--max-risk-score `\n- `--min-health-score `\n- `--new-hotspot-score-threshold `\n- `--fail-on error|warn`\n\n`codesentinel ci` orchestrates snapshot + diff + gate evaluation + markdown summary generation.\n\nBaseline input modes:\n\n- `--baseline `: use an existing snapshot JSON artifact.\n- `--baseline-ref `: resolve baseline from git (`origin/main`, `main`, `HEAD~1`) using an isolated temporary worktree. No checkout/stash of your current working tree.\n- `--baseline-ref auto`: deterministic resolver with ordered fallbacks:\n - `--baseline-sha ` if provided.\n - CI base branch env vars (`GITHUB_BASE_REF`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, `BITBUCKET_PR_DESTINATION_BRANCH`) with `origin/` first, then ``.\n - branch-aware defaults:\n - on `main/master`: `HEAD~1`\n - otherwise: `merge-base(HEAD, origin/main)` then `origin/master`, `main`, `master`\n- `--main-branch ` (repeatable) or `--main-branches \"main,master,trunk\"` customize default branch candidates used by `--baseline-ref auto`.\n\nGitHub Actions recommendation for deterministic CI with `--baseline-ref auto`:\n\n```yaml\n- uses: actions/checkout@v4\n with:\n fetch-depth: 0\n filter: blob:none\n ref: ${{ github.event.pull_request.head.sha || github.sha }}\n\n- name: Ensure git history for CodeSentinel\n run: |\n set -euo pipefail\n git fetch --prune --unshallow || true\n BASE_REF=\"${GITHUB_BASE_REF:-main}\"\n git fetch origin \"+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}\"\n```\n\nExit codes:\n\n- `0`: no failing violations\n- `1`: error-level violations\n- `2`: warn-level violations when `--fail-on=warn`\n- `3`: invalid configuration\n- `4`: internal execution error\n\n## Explain Output\n\n`codesentinel explain` uses the same risk-engine scoring model as `analyze` and adds structured explanation traces.\n\nText/markdown output includes:\n\n- repository score and risk band (`low|moderate|elevated|high|very_high`)\n- repository dimension scores (`structural`, `evolution`, `external`, `interactions`) as `0-100`\n- plain-language primary drivers\n- concrete evidence values behind those drivers\n- intersected signals (composite interaction terms)\n- prioritized reduction actions\n- per-target breakdowns (repository/file/module/dependency, depending on selection)\n\nFilters:\n\n- `--file `: explain one file target.\n- `--module `: explain one module target.\n- `--top `: explain top `n` hotspot files (default behavior when no file/module is provided).\n- `--format text|json|md`: render narrative text, full JSON payload, or markdown.\n\n## Understanding Analyze Output\n\n`codesentinel analyze` returns one JSON document with five top-level blocks:\n\n- `structural`: file dependency graph shape and graph metrics.\n- `evolution`: git-derived change behavior per file and coupling pairs.\n- `external`: dependency exposure for direct packages plus propagated transitive signals.\n- `risk`: deterministic composition of `structural + evolution + external`.\n- `health`: deterministic code health posture from local structural/evolution/test signals.\n\nMinimal shape:\n\n```json\n{\n \"structural\": { \"...\": \"...\" },\n \"evolution\": { \"...\": \"...\" },\n \"external\": { \"...\": \"...\" },\n \"risk\": {\n \"riskScore\": 0,\n \"normalizedScore\": 0,\n \"hotspots\": [],\n \"fragileClusters\": [],\n \"dependencyAmplificationZones\": []\n },\n \"health\": {\n \"healthScore\": 0,\n \"normalizedScore\": 0,\n \"dimensions\": {\n \"modularity\": 0,\n \"changeHygiene\": 0,\n \"testHealth\": 0,\n \"ownershipDistribution\": 0\n },\n \"topIssues\": [],\n \"trace\": {\n \"schemaVersion\": \"1\",\n \"dimensions\": []\n }\n }\n}\n```\n\nHow to read `risk` first:\n\n- `riskScore`: overall repository fragility index (`0..100`).\n- `hotspots`: ranked files to inspect first.\n- `fragileClusters`: groups of files with structural-cycle or co-change fragility.\n- `dependencyAmplificationZones`: files where external dependency pressure intersects with local fragility.\n\nScore direction:\n\n- `risk.riskScore`: higher means higher risk (worse).\n- `health.healthScore`: higher means better health posture.\n- Report views also include derived tiers: `riskTier` and `healthTier`.\n- `health.trace`: per-dimension factor traces with normalized metrics and evidence.\n\nHealth dimensions:\n\n- `modularity`: cycle density + fan/centrality concentration + structural-hotspot overlap.\n- `changeHygiene`: churn/volatility concentration + dense co-change clusters.\n- `testHealth`: test presence + test-to-source ratio + testing directory presence.\n- `ownershipDistribution`: top-author share + author entropy + single-author dominance signals.\n\nSignal ingestion (deterministic, local):\n\n- Structural and evolution metrics come from local graph + git analysis.\n- Test posture uses file/path heuristics only (no mandatory coverage integration).\n- Ownership posture is derived from local git author distribution metrics.\n\nInterpretation notes:\n\n- Scores are deterministic for the same inputs and config.\n- Scores are meant for within-repo prioritization and trend tracking.\n- Full model details and limits are in `packages/risk-engine/README.md`.\n\n### Risk Score Guide\n\nUse these ranges as operational guidance:\n\n- `0-20`: low fragility (architectural and change pressure signals are generally contained).\n- `20-40`: moderate fragility (localized hotspots exist; monitor trend direction and concentration).\n- `40-60`: elevated fragility (prioritize top hotspots before introducing major concurrent change).\n- `60-80`: high fragility (expect higher coordination cost, regressions, and change coupling across areas).\n- `80-100`: very high fragility (treat as immediate triage; focus on stabilization before further expansion).\n\nThese ranges are heuristics for triage, not incident probability.\n\n### Health Score Guide\n\nUse these ranges as operational guidance:\n\n- `0-20`: critical health posture (maintainability pressure is highly concentrated and debt is likely compounding).\n- `20-40`: weak health posture (key maintainability bottlenecks are visible; prioritize stabilization work).\n- `40-60`: fair health posture (baseline is workable, but concentrated architecture/change pressure can still slow delivery).\n- `60-80`: good health posture (most maintainability signals are stable, with targeted improvements still valuable).\n- `80-100`: excellent health posture (maintainability pressure is broadly distributed and sustainably controlled over time).\n\nThese ranges are heuristics for prioritization, not absolute quality guarantees.\n\n### What Moves Scores\n\n`risk.riskScore` and `risk.fileScores[*].score` increase when:\n\n- structurally central files/modules change frequently,\n- ownership is highly concentrated in volatile files,\n- files in central areas are exposed to high external dependency pressure,\n- tightly coupled change patterns emerge.\n\nThey decrease when:\n\n- change concentrates less around central files,\n- ownership spreads or volatility decreases,\n- dependency pressure decreases (shallower trees, fewer high-risk signals),\n- hotspot concentration drops.\n\n### External Risk Signal Semantics\n\nFor `external.dependencies`, each direct dependency now exposes three signal fields:\n\n- `ownRiskSignals`: signals computed from that package itself.\n- `inheritedRiskSignals`: signals propagated from transitive dependencies in its subtree.\n- `riskSignals`: union of `ownRiskSignals` and `inheritedRiskSignals`.\n\nData source notes:\n\n- Lockfile-first extraction supports `pnpm-lock.yaml`, `package-lock.json` / `npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`.\n- If no lockfile is present, CodeSentinel attempts a bounded npm registry graph resolution from direct dependencies.\n- npm weekly download metadata is fetched only for direct dependencies (not all transitive nodes).\n\nClassification lists:\n\n- `highRiskDependencies`: **production** direct packages classified from strong **own** signals (not inherited-only signals).\n- `highRiskDevelopmentDependencies`: same classification model for direct development dependencies.\n- `transitiveExposureDependencies`: direct packages carrying inherited transitive exposure signals.\n\nCurrent high-risk rule for direct dependencies:\n\n- mark high-risk if own signals include `abandoned`, or\n- mark high-risk if at least two of own signals are in `{high_centrality, deep_chain, high_fanout}`, or\n- mark high-risk if own signals include `single_maintainer` and the package is stale (>= half abandoned threshold) or has no recent repository activity signal.\n\nPropagation policy is explicit and deterministic:\n\n- `single_maintainer`: **not propagated**\n - Rationale: maintainer concentration is package-specific governance, not a transferable property.\n- `abandoned`: **propagated**\n - Rationale: depending on abandoned transitive packages is still real operational exposure.\n - Note: `abandonedDependencies` list only includes packages with **own** `abandoned`.\n- `high_centrality`: **propagated**\n - Rationale: highly central transitive packages can become systemic weak points for a parent dependency.\n- `deep_chain`: **propagated**\n - Rationale: deep transitive trees increase update/debug complexity for top-level dependencies.\n- `high_fanout`: **propagated**\n - Rationale: broad transitive fan-out increases blast radius and maintenance surface.\n- `metadata_unavailable`: **not propagated**\n - Rationale: unknown metadata for one child should not automatically degrade parent classification.\n\nThis keeps package-level facts local while still surfacing meaningful transitive exposure.\n\n## ESM Import Policy\n\n- The workspace uses `TypeScript` with `moduleResolution: \"NodeNext\"` and ESM output.\n- For local relative imports, use `.js` specifiers in source files (example: `import { x } from \"./x.js\"`).\n- Do not use `.ts` specifiers for runtime imports in package source files.\n- This keeps emitted code and runtime resolution aligned with Node.js ESM behavior.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"CodeSentinel](\"assets/codesentinel-logo.png\"){kind=logo}
\n![\"Release\"](\"https://github.com/getcodesentinel/codesentinel/actions/workflows/release.yml/badge.svg?branch=main\"){kind=icon}
\n ![\"npm](\"https://img.shields.io/npm/v/@getcodesentinel/codesentinel\")
![\"Node.js](\"https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg\"){kind=icon}
\n