@getcodesentinel/codesentinel 1.6.5 → 1.8.0

package/README.md

@@ -69,6 +69,8 @@ Then run:
 
 ```bash
 codesentinel analyze [path]
+codesentinel explain [path]
+codesentinel report [path]
 codesentinel dependency-risk <dependency[@version]>
 ```
 
@@ -78,6 +80,14 @@ Examples:
 codesentinel analyze
 codesentinel analyze .
 codesentinel analyze ../project
+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 dependency-risk react
 codesentinel dependency-risk react@19.0.0
 ```
@@ -103,6 +113,26 @@ codesentinel analyze .
 # Full output (all sections and detailed arrays)
 codesentinel analyze . --output json
 codesentinel analyze . --json
+
+# Explain top hotspots with narrative output
+codesentinel explain .
+
+# Explain a specific file
+codesentinel explain . --file src/app/page.tsx
+
+# Explain a specific module
+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:
@@ -124,8 +154,51 @@ pnpm dev -- analyze
 pnpm dev -- analyze .
 pnpm dev -- analyze ../project
 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
 ```
 
+## 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
+
+## Explain Output
+
+`codesentinel explain` uses the same risk-engine scoring model as `analyze` and adds structured explanation traces.
+
+Text/markdown output includes:
+
+- repository score and risk band (`low|moderate|high|very_high`)
+- plain-language primary drivers
+- concrete evidence values behind those drivers
+- intersected signals (composite interaction terms)
+- prioritized reduction actions
+- per-target breakdowns (repository/file/module/dependency, depending on selection)
+
+Filters:
+
+- `--file <path>`: explain one file target.
+- `--module <name>`: explain one module target.
+- `--top <n>`: explain top `n` hotspot files (default behavior when no file/module is provided).
+- `--format text|json|md`: render narrative text, full JSON payload, or markdown.
+
 ## Understanding Analyze Output
 
 `codesentinel analyze` returns one JSON document with four top-level blocks:
@@ -201,12 +274,24 @@ For `external.dependencies`, each direct dependency now exposes three signal fie
 - `inheritedRiskSignals`: signals propagated from transitive dependencies in its subtree.
 - `riskSignals`: union of `ownRiskSignals` and `inheritedRiskSignals`.
 
+Data source notes:
+
+- Lockfile-first extraction supports `pnpm-lock.yaml`, `package-lock.json` / `npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`.
+- If no lockfile is present, CodeSentinel attempts a bounded npm registry graph resolution from direct dependencies.
+- npm weekly download metadata is fetched only for direct dependencies (not all transitive nodes).
+
 Classification lists:
 
 - `highRiskDependencies`: **production** direct packages classified from strong **own** signals (not inherited-only signals).
 - `highRiskDevelopmentDependencies`: same classification model for direct development dependencies.
 - `transitiveExposureDependencies`: direct packages carrying inherited transitive exposure signals.
 
+Current high-risk rule for direct dependencies:
+
+- mark high-risk if own signals include `abandoned`, or
+- mark high-risk if at least two of own signals are in `{high_centrality, deep_chain, high_fanout}`, or
+- mark high-risk if own signals include `single_maintainer` and the package is stale (>= half abandoned threshold) or has no recent repository activity signal.
+
 Propagation policy is explicit and deterministic:
 
 - `single_maintainer`: **not propagated**
@@ -225,28 +310,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.