repopilot 0.12.0 → 0.14.0

package/README.md

@@ -7,76 +7,46 @@
 [![License](https://img.shields.io/crates/l/repopilot.svg)](LICENSE)
 [![GitHub Stars](https://img.shields.io/github/stars/MykytaStel/repopilot?style=social)](https://github.com/MykytaStel/repopilot)
 
-**Local-first repository risk checks for safer human and AI-assisted code changes.**
+**Local-first repository audits for safer human and AI-assisted code changes.**
 
-RepoPilot gives teams a fast safety pass before a pull request, release, or AI
-coding session. It scans a repository locally, explains architecture, security,
-code-quality, testing, and framework risks, then turns findings into AI-ready
-context without uploading your source code to a hosted scanner.
-
-It is not meant to replace language linters. RepoPilot focuses on repository
-signals that are hard to see from one file at a time: risky files, architecture
-drift, security candidates, testing gaps, review risk, baselines, and remediation
-context for Claude Code, ChatGPT, Cursor, or another coding assistant.
-
----
-
-## Why RepoPilot?
-
-Most tools either lint one language or send results into a dashboard. RepoPilot is
-designed for the local development loop:
+RepoPilot is a fast Rust CLI that scans a repository locally, ranks evidence-backed risks, supports baseline adoption, reviews branches, and creates AI-ready remediation context without uploading source code.
 
 ```text
-scan -> understand risk -> generate AI context -> fix -> review
+scan -> review risk -> baseline adoption -> CI evidence -> local AI context
 ```
 
-| Capability | Language linters | Hosted scanners | RepoPilot |
-|---|---:|---:|---:|
-| Runs locally | ✅ | ❌ | ✅ |
-| No source upload required | ✅ | ❌ | ✅ |
-| Cross-language repository view | ❌ | ✅ | ✅ |
-| Architecture and repo risk signals | partial | ✅ | ✅ |
-| AI-ready remediation context | ❌ | ❌ | ✅ |
-| Baseline and PR review workflow | partial | ✅ | ✅ |
-| Default noise reduction / Trust Mode | ❌ | partial | ✅ |
-
-Use RepoPilot when you need to:
-
-- understand the highest-risk files before asking an AI assistant to edit;
-- add a CI gate without blocking on every existing finding;
-- review PR risk from changed lines instead of only whole-repo noise;
-- produce local evidence for releases through Markdown, JSON, SARIF, and receipts.
-
----
+RepoPilot is not a replacement for language linters, formatters, type checkers, or dedicated security scanners. It complements them with repository-level evidence: secrets, runtime footguns, architecture risk, review blast radius, baseline status, and report formats that work in CI.
 
 ## Install
 
-With Cargo:
+Choose one install method.
+
+Cargo:
 
 ```bash
 cargo install repopilot
 ```
 
-With npm:
+npm:
 
 ```bash
 npm install -g repopilot
 ```
 
-With Homebrew:
+Homebrew:
 
 ```bash
 brew tap mykytastel/repopilot
 brew install repopilot
 ```
 
-With curl on Linux/macOS:
+Installer:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/MykytaStel/repopilot/main/install.sh | bash
 ```
 
-Build from source:
+From source:
 
 ```bash
 git clone https://github.com/MykytaStel/repopilot.git
@@ -84,347 +54,205 @@ cd repopilot
 cargo build --release
 ```
 
-Upgrade:
-
-```bash
-cargo install repopilot --force
-npm update -g repopilot
-brew update && brew upgrade repopilot
-```
-
----
+More: [docs/install.md](docs/install.md).
 
 ## Quick Start
 
-Start with a local scan:
+Run a local scan:
 
 ```bash
 repopilot scan .
+repopilot doctor .
 ```
 
-Check adoption readiness and create an intentional baseline for existing debt:
+Adopt RepoPilot in an existing repository without failing CI on old debt:
 
 ```bash
-repopilot doctor .
 repopilot baseline create . --output .repopilot/baseline.json
 repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
 ```
 
-Generate AI-ready context for the highest-risk work:
+Review a branch:
 
 ```bash
-repopilot ai context . --budget 4k
+repopilot review . --base origin/main
 ```
 
-Copy AI context on macOS:
+Generate local AI context:
 
 ```bash
-repopilot ai context . | pbcopy
+repopilot ai context . --budget 4k
 ```
 
-Save a Markdown report:
+Save CI evidence:
 
 ```bash
 repopilot scan . --format markdown --output repopilot-report.md
+repopilot scan . --format json --output repopilot-report.json --receipt .repopilot/receipt.json
+repopilot scan . --format sarif --output repopilot.sarif
 ```
 
-Run a focused security scan:
-
-```bash
-repopilot scan . --min-severity high --rule security.secret-candidate
-```
-
-Review only changed code against a base branch:
-
-```bash
-repopilot review . --base origin/main
-```
-
----
-
-## Trust Mode
-
-RepoPilot's default scan profile is intentionally quiet.
+## Use with AI agents (MCP)
 
-The default profile focuses on actionable production, security, and runtime risks.
-Strict mode shows the full raw audit output, including maintainability and testing
-suggestions.
+RepoPilot ships a local [Model Context Protocol](https://modelcontextprotocol.io) server so AI coding agents (Claude Code, Cursor, …) can call it as a tool — auditing what the agent just changed, without anything leaving your machine.
 
 ```bash
-repopilot scan .                  # default profile
-repopilot scan . --profile strict # full audit output
-repopilot scan . --include-maintainability
+claude mcp add repopilot -- repopilot mcp
 ```
 
-The visibility engine classifies findings by product intent:
+The server runs locally over stdio (JSON-RPC, no network, no AI calls) and exposes four tools:
 
-```text
-SecurityRisk | RuntimeRisk | ActionableRisk | Maintainability | TestingGap | Informational
-```
+- `repopilot_review_change` — audit the current Git changes: in-diff vs out-of-diff findings plus blast radius.
+- `repopilot_scan` — full repository audit as a JSON report.
+- `repopilot_context` — a budgeted, AI-ready Markdown brief of the repo.
+- `repopilot_explain_file` — how a single file is classified and which rules apply.
 
-Hidden suggestions are summarized by intent, rule, category, and reason, so the
-default report stays quiet without silently losing information.
+More: [docs/mcp.md](docs/mcp.md).
 
-Read more:
+## What It Checks
 
-- [Trust Mode](docs/trust-mode.md)
-- [Core Visibility Engine](docs/core-visibility-engine.md)
-
----
+| Area | Examples |
+|---|---|
+| Security | secret candidates, private keys, committed `.env` files |
+| Runtime risk | Rust panic/unwrap paths, JavaScript/Python/Go/JVM/.NET process exits |
+| Architecture | circular dependencies, excessive fan-out, instability hubs |
+| Review risk | changed files, branch context, blast radius |
+| Adoption | baselines, new-vs-existing findings, CI gates |
+| Evidence | JSON, Markdown, SARIF, receipts, report envelopes |
+| AI context | local, budgeted, evidence-backed Markdown for coding assistants |
 
-## AI Workflow
+## Trust Mode
 
-RepoPilot does not call LLM APIs. It produces local Markdown that you choose where
-to paste.
+Default scans are intentionally quiet. They keep high-trust security, runtime, and import-graph findings visible while summarizing broad maintainability and testing suggestions as strict-only noise.
 
 ```bash
-repopilot ai context . --focus security
-repopilot ai plan . --focus security
-repopilot ai prompt . --budget 8k
-```
-
-Typical loop:
-
-```text
-1. Run RepoPilot locally.
-2. Read the risk summary.
-3. Generate focused AI context.
-4. Paste the context into Claude Code, ChatGPT, Cursor, or another assistant.
-5. Apply the patch.
-6. Run RepoPilot review/scan again.
+repopilot scan .                  # compact default output
+repopilot scan . --output-style full
+repopilot scan . --profile strict # full audit output
 ```
 
-See [AI workflows](docs/ai-workflows.md).
+Use strict mode for cleanup passes, rule development, and release hardening. Use the default profile for day-to-day local checks and CI gates.
 
----
+More: [docs/trust-mode.md](docs/trust-mode.md).
 
 ## Core Commands
 
-| Command | Alias | Description |
-|---|---:|---|
-| `repopilot scan <path>` | `s` | Scan a project, folder, or file |
-| `repopilot scan <path> --changed` | — | Scan changed files with local cache |
-| `repopilot cache clear [path]` | — | Remove `.repopilot/cache` |
-| `repopilot review [path]` | `r` | Review findings that touch changed Git diff lines |
-| `repopilot ai context <path>` | — | Generate LLM-ready repository context |
-| `repopilot ai plan <path>` | — | Generate a prioritized remediation plan |
-| `repopilot ai prompt <path>` | — | Generate a paste-ready remediation prompt |
-| `repopilot compare <before> <after>` | `cmp` | Compare two JSON scan reports |
-| `repopilot baseline create <path>` | `bl` | Store current findings as accepted debt |
-| `repopilot doctor [path]` | `d` | Diagnose audit readiness |
-| `repopilot init` | — | Generate `repopilot.toml` |
-
-Get command help:
-
-```bash
-repopilot --help
-repopilot scan --help
-repopilot review --help
-repopilot ai --help
+```text
+scan | review | baseline | compare | doctor | inspect | ai | init | cache | mcp
 ```
 
----
-
-## Output Formats
+Common workflows:
 
 ```bash
-repopilot scan . --format console
-repopilot scan . --format json --output report.json
-repopilot scan . --format markdown --output report.md
-repopilot scan . --format html --output report.html
-repopilot scan . --format sarif --output repopilot.sarif
+repopilot scan .
+repopilot review . --base origin/main
+repopilot baseline create .
+repopilot compare before.json after.json
+repopilot inspect rules
+repopilot inspect eval-rules --format json
+repopilot ai context .
 ```
 
-Use:
-
-- `console` for local development
-- `markdown` for human-readable reports
-- `json` for scripts and integrations
-- `html` for shareable reports
-- `sarif` for GitHub Code Scanning
+More: [docs/commands.md](docs/commands.md) and [docs/cli.md](docs/cli.md).
 
----
+## Baseline Adoption
 
-## Configuration
-
-Generate a config file:
+A baseline records current findings as accepted existing debt. Future scans can fail only on newly introduced risk:
 
 ```bash
-repopilot init
+repopilot baseline create . --output .repopilot/baseline.json
+git add .repopilot/baseline.json
+repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
 ```
 
-Run with an explicit config:
+Review baseline updates like code changes. A baseline is not a suppression file; it is a CI adoption contract.
 
-```bash
-repopilot scan . --config repopilot.toml
-```
+## Rule Quality
 
-Configuration precedence:
+Rules move through a lifecycle:
 
 ```text
-CLI args > repopilot.toml > built-in defaults
+experimental -> preview -> stable
 ```
 
-Common scan options:
+Before a rule becomes stable or default-visible, it should have metadata, true-positive and false-positive fixtures, stable finding IDs, concrete evidence, false-positive notes, recommendations, and clean local evaluation:
 
 ```bash
-repopilot scan . --preset strict
-repopilot scan . --preset balanced
-repopilot scan . --preset lenient
-repopilot scan . --max-file-loc 500
-repopilot scan . --max-directory-depth 6
-repopilot scan . --exclude generated
-repopilot scan . --include-low-signal
+repopilot inspect eval-rules --format json
 ```
 
-See [configuration docs](docs/configuration.md).
+More: [docs/rule-quality-gate.md](docs/rule-quality-gate.md).
 
----
+## Local-First
 
-## Baseline and Review
+RepoPilot does not upload source code, run a hosted scanner, call LLM APIs implicitly, send telemetry, or require a SaaS account.
 
-Create a baseline for existing findings:
+AI commands only format local scan evidence as Markdown for tools such as Claude Code, ChatGPT, Cursor, Zed, or another assistant.
 
-```bash
-repopilot baseline create . --output .repopilot/baseline.json
-```
+## Reports
+
+| Format | Use case |
+|---|---|
+| Console | fast local feedback |
+| Markdown | PR comments and human-readable reports |
+| JSON | automation and internal tooling |
+| SARIF | GitHub Code Scanning |
+| HTML | shareable local reports |
+| Receipt | compact release/CI evidence |
 
-Scan against accepted debt:
+More: [docs/reports.md](docs/reports.md).
 
-```bash
-repopilot scan . --baseline .repopilot/baseline.json
-```
+## CI
 
-Fail CI only on new high-risk findings:
+Minimal baseline-aware gate:
 
 ```bash
 repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
 ```
 
-Commit `.repopilot/baseline.json` only after reviewing the accepted findings.
-Do not update it just to make CI green; note accepted baseline changes in the PR.
-
-Validate or bypass local feedback suppressions:
+GitHub Code Scanning:
 
 ```bash
-repopilot inspect feedback .
-repopilot scan . --ignore-feedback
+repopilot scan . --format sarif --output repopilot.sarif
 ```
 
-Review a pull request or branch diff:
+Release smoke:
 
 ```bash
-repopilot review . --base origin/main --fail-on-priority p1
+./scripts/smoke-product.sh
 ```
 
-See:
-
-- [CLI reference](docs/cli.md)
-- [Commands guide](docs/commands.md)
-- [GitHub Code Scanning integration](docs/integrations/github-code-scanning.md)
-
----
-
-## What RepoPilot Checks
-
-RepoPilot includes rules for:
-
-- architecture risk
-- large and complex files
-- deep nesting
-- risky barrel files
-- excessive fan-out and coupling
-- circular dependencies
-- TODO/FIXME/HACK markers
-- long functions
-- hardcoded secret candidates
-- committed private keys
-- committed `.env` files
-- missing test structure
-- source files without test counterparts
-- JavaScript/TypeScript framework signals
-- React and React Native project health
-- Django project health
-- Rust panic/unwrap risk
-- JavaScript runtime exit risk
+More: [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md).
 
-See the full rule list in [rulesets](docs/rulesets.md).
+## Documentation
 
----
+| Document | Purpose |
+|---|---|
+| [Install](docs/install.md) | Cargo, npm, Homebrew, curl, and source builds |
+| [Commands](docs/commands.md) | Task-oriented workflows |
+| [CLI](docs/cli.md) | Complete command and flag reference |
+| [Configuration](docs/configuration.md) | `repopilot.toml`, presets, ignores, and baselines |
+| [Rulesets](docs/rulesets.md) | Built-in rules, lifecycle, severity, and confidence |
+| [Trust Mode](docs/trust-mode.md) | Default vs strict visibility policy |
+| [Reports](docs/reports.md) | JSON, SARIF, Markdown, HTML, receipts, and schema fields |
+| [Release Process](docs/release.md) | Local and CI release gates |
 
-## Example
+## Development
 
 ```bash
-$ repopilot scan .
-
-RepoPilot Scan
-Version: 0.12.0
-Path: .
-Risk: Elevated
-Health score: 93/100
-Profile: default
-Findings visible: 7
-Hidden suggestions: 657 strict-only suggestions
-
-Top risks:
-	P0 security.secret-candidate src/config/app.ts:12
-	P1 language.rust.panic-risk src/api/routes/search.rs:88
-
-Hidden suggestions breakdown:
-	 379 testing-gap / testing.source-without-test
-	 104 maintainability / code-quality.long-function
-		43 maintainability / architecture.large-file
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all
+npm run test:npm
+./scripts/smoke-product.sh
 ```
 
-Default mode shows what is likely to matter now. Strict mode keeps the full audit:
+Run rule evaluation from source:
 
 ```bash
-repopilot scan . --profile strict
+cargo run -- inspect eval-rules --format json
 ```
 
----
-
-## Documentation
-
-| Document | Description |
-|---|---|
-| [Install](docs/install.md) | Cargo, npm, Homebrew, curl, and source builds |
-| [AI workflows](docs/ai-workflows.md) | Claude Code, ChatGPT, Cursor, and remediation workflows |
-| [Security](docs/security.md) | Local-first trust model and vulnerability reporting |
-| [Configuration](docs/configuration.md) | `repopilot.toml`, presets, ignore files, and baseline adoption |
-| [Language support](docs/language-support.md) | Supported language/framework tiers and limitations |
-| [Knowledge Engine](docs/knowledge-engine.md) | Rule applicability and local-first learning policy |
-| [Risk Engine](docs/risk-engine.md) | Risk scoring, priorities, and calibration policy |
-| [Local Feedback](docs/local-feedback.md) | Repository-local suppressions and validation |
-| [Trust Mode](docs/trust-mode.md) | Default vs strict visibility and hidden suggestions |
-| [Core Visibility Engine](docs/core-visibility-engine.md) | Finding intent model and visibility decisions |
-| [CLI reference](docs/cli.md) | Commands, flags, and exit codes |
-| [Commands guide](docs/commands.md) | Task-oriented command examples |
-| [Rulesets](docs/rulesets.md) | Implemented rules, categories, and severity levels |
-| [React Native](docs/react-native.md) | React Native and Expo detection |
-| [GitHub Code Scanning](docs/integrations/github-code-scanning.md) | SARIF workflow and CI setup |
-| [Roadmap](docs/roadmap.md) | Pre-1.0 roadmap and v1 gates |
-| [0.12 GTM plan](docs/gtm-0.12.md) | Launch audiences, messaging, and proof points |
-| [Release process](docs/release.md) | Manual release process |
-| [Changelog](CHANGELOG.md) | Version history |
-
----
-
-## Roadmap
-
-Planned direction:
-
-- stronger Trust Mode calibration
-- `repopilot eval` with golden fixtures
-- local feedback validation and report transparency
-- hidden suggestion trend tracking
-- deeper dependency graph and impact analysis
-- AI task packs with context, constraints, and acceptance criteria
-
-See [roadmap](docs/roadmap.md).
-
----
-
 ## License
 
-RepoPilot is licensed under **MIT OR Apache-2.0**.
+RepoPilot is licensed under **MIT OR Apache-2.0**.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "repopilot",
-	"version": "0.12.0",
+	"version": "0.14.0",
 	"description": "Local-first CLI for repository audit, architecture risk detection, baseline tracking, and CI-friendly code review.",
 	"license": "MIT OR Apache-2.0",
 	"repository": {
@@ -26,11 +26,11 @@
 		"LICENSE"
 	],
 	"optionalDependencies": {
-		"@repopilot/darwin-arm64": "0.12.0",
-		"@repopilot/darwin-x64": "0.12.0",
-		"@repopilot/linux-arm64-gnu": "0.12.0",
-		"@repopilot/linux-x64-gnu": "0.12.0",
-		"@repopilot/win32-x64-msvc": "0.12.0"
+		"@repopilot/darwin-arm64": "0.14.0",
+		"@repopilot/darwin-x64": "0.14.0",
+		"@repopilot/linux-arm64-gnu": "0.14.0",
+		"@repopilot/linux-x64-gnu": "0.14.0",
+		"@repopilot/win32-x64-msvc": "0.14.0"
 	},
 	"keywords": [
 		"cli",