prism-pr 1.0.0-alpha.67 → 1.0.0-alpha.68

package/README.md

@@ -1,339 +1,339 @@
-# PRISM-PR
-
-> **Alpha** — this package is in active development (`1.0.0-alpha`). APIs and commands may change between releases.
-
-Intelligent Pull Request review orchestrator for Bitbucket. AI-powered code review plus pattern-based pre-checks using ast-grep structural matching, a shared team rules repository, and a self-evolving rule system that learns from your feedback.
-
-## Install
-
-```bash
-npm i -g prism-pr
-```
-
-## Requirements
-
-- Node.js **>= 22.5.0** (SQLite is loaded via the native `node:sqlite` module)
-- Bitbucket Cloud account with an Atlassian API token
-- AI provider (one of):
-  - `ANTHROPIC_API_KEY` environment variable (preferred), or
-  - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
-
-## Setup
-
-```bash
-prism login
-```
-
-Your Bitbucket app password / API token needs these permissions:
-
-- Repositories: **Read** + **Write**
-- Pull requests: **Read** + **Write**
-
-## Discoverability — always available
-
-Every command documents itself via `--help`. If something in this README is stale, trust `--help`:
-
-```bash
-prism --help                      # full command tree
-prism rules --help                # subcommands under `rules`
-prism guard --help                # subcommands under `guard`
-prism rules bootstrap --help      # flags + examples for a specific command
-prism guard check --help
-prism review start --help
-```
-
----
-
-## Quick start — zero config
-
-PRISM auto-detects your stack and bootstraps rules on the first run. No setup needed.
-
-```bash
-cd your-bitbucket-repo
-prism guard check
-```
-
-That's it. On first run, PRISM will:
-
-1. Detect workspace/repo from your git remote
-2. Fetch `package.json` via Bitbucket API to detect your stack (TypeScript, Angular, React, NestJS, AG Grid, …)
-3. Generate a manifest with the matching rulesets
-4. Push everything to the shared rules repository
-5. Resolve patterns and check your PR
-
-### Manual bootstrap (optional)
-
-If you prefer explicit control:
-
-```bash
-# Detect stack and push manifest + rulesets to the shared rules repo
-prism rules bootstrap
-
-# Preview without pushing
-prism rules bootstrap --dry-run
-
-# JSON output (CI-friendly)
-prism rules bootstrap --dry-run --json
-
-# Explicit workspace/repo/branch
-prism rules bootstrap --workspace acme --repo my-repo --branch develop
-```
-
-### Check a PR
-
-```bash
-# Interactive PR picker (auto-detects workspace/repo from git origin)
-prism guard check
-
-# Pick a PR by ID
-prism guard check --pr 42
-
-# Full output with code snippets and suggestions
-prism guard check --pr 42 --verbose
-
-# Filter by severity
-prism guard check --pr 42 --min-severity high --verbose
-
-# JSON output for CI
-prism guard check --pr 42 --json
-```
-
-**`--verbose` gates the snippet and suggestion.** Without it, matches show severity badge + title + file:line only. With `--verbose`, you get diff context with a pointer on the exact line, plus the fix suggestion.
-
----
-
-## Living Rules — self-evolving rule system
-
-PRISM's rules aren't static. They learn, adapt, and grow with your codebase.
-
-### Auto-Refresh
-
-Manifests detect when your stack changes. If you add a new framework (e.g. NestJS) to your project, the next guard check automatically updates the manifest with the new rulesets. Default staleness threshold: 7 days.
-
-### Versioned Catalog
-
-Rulesets are published as immutable versioned artifacts:
-
-```
-catalog/
-  shared/security/1.0.0.json    # immutable, infinite cache
-  shared/general/1.0.0.json
-  angular/v17/1.0.0.json
-  ...
-catalog/index.json               # lists all rulesets + latest versions
-```
-
-Manifests can pin versions: `"shared/security@1.2.0"`. Unversioned includes resolve to latest. A 3-level fallback chain ensures resilience: versioned remote → unversioned remote → static builtin catalog.
-
-### Feedback Loop & Auto-Tune
-
-Mark findings as false positives. After enough feedback, PRISM auto-excludes noisy patterns.
-
-```bash
-# CLI: mark specific pattern IDs as false positive
-prism guard check --pr 42 --mark-fp "security--xss--innerHTML-usage,general--debug--console-log"
-
-# CLI: auto-exclude patterns with 3+ false positives
-prism guard check --pr 42 --auto-tune
-```
-
-In the TUI, press `[f]` on any finding to mark it as a false positive. Press `[t]` in the results screen to apply auto-tune.
-
-### AI Rule Suggestion
-
-PRISM can analyze findings from any review and generate new ast-grep rules automatically. Rule suggestions are a **post-review** action — you see the findings first, then decide which patterns should become permanent rules.
-
-```bash
-# CLI: generate rules from guard findings
-prism guard check --pr 42 --suggest-rules
-
-# CLI: generate rules from AI review findings
-prism review start --workspace acme --repo app --pr 42 --suggest-rules
-```
-
-PRISM uses the same AI provider configured for reviews (auto-detects from `ANTHROPIC_API_KEY` or falls back to Claude Code CLI).
-
-In the TUI, press `[g]` on any results screen (guard results or AI review findings) to generate rule suggestions on demand. Review, accept/reject, and apply to the manifest.
-
----
-
-## Interactive TUI
-
-```bash
-prism           # main TUI (review + navigation)
-prism guard     # guard-focused TUI
-```
-
-Launches a full Ink-based terminal UI with keyboard navigation.
-
-### Guardian Angel section
-
-- **Guard Check** — select workspace → repo → PR → run check
-- **Guard Check (auto-detect)** — detects workspace/repo from git origin, skips manual selection
-- **Rules Bootstrap** — detect stack and push manifest (dry-run toggle, branch override)
-
-### Guard options (toggleable in guard-home)
-
-| Key | Option | Description |
-|-----|--------|-------------|
-| `v` | Verbose | Show context lines and suggestions |
-| `s` | Severity | Cycle minimum severity filter |
-| `a` | AST | Toggle ast-grep matching on/off |
-
-### Guard results actions
-
-| Key | Action | Description |
-|-----|--------|-------------|
-| `↑↓` | Navigate | Browse findings |
-| `Enter` | Detail | View finding detail with context |
-| `f` | False positive | Mark finding as FP (in detail view) |
-| `j` | Export JSON | Export results to `prism-guard-results.json` |
-| `t` | Auto-tune | Batch-exclude patterns with enough FP feedback |
-| `g` | AI suggestions | Generate and review AI-suggested rules (on demand) |
-| `Esc` | Back | Return to previous screen |
-
-### AI Review findings actions
-
-| Key | Action | Description |
-|-----|--------|-------------|
-| `↑↓` | Navigate | Browse findings |
-| `Enter` | Detail | View finding detail |
-| `g` | AI suggestions | Generate rules from review findings (on demand) |
-| `p` | Publish | Publish findings to Bitbucket PR |
-| `Esc` | Back | Return to previous screen |
-
----
-
-## AI Review — full PR analysis (LLM-powered)
-
-```bash
-prism review start --workspace acme --repo app --pr 42
-
-# Verbose logging
-prism review start --workspace acme --repo app --pr 42 --verbose
-
-# Pick a provider explicitly
-prism review start --workspace acme --repo app --pr 42 --provider anthropic
-prism review start --workspace acme --repo app --pr 42 --provider claude-code
-
-# Generate rule suggestions from findings
-prism review start --workspace acme --repo app --pr 42 --suggest-rules
-```
-
-> **Note:** `review start` requires `--workspace` and `--repo` explicitly (no auto-detect from git origin). `guard check` auto-detects both.
-
-The AI review runs specialized agents (TypeScript, PHP, CSS, Security, Architecture, Performance, …) and produces findings with inline suggestions. Findings are stored in a local SQLite database for review memory and pattern generation.
-
----
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `prism` | Launch main interactive TUI |
-| `prism login` | Authenticate with Bitbucket |
-| `prism logout` | Remove stored credentials |
-| `prism guard` | Guard Check TUI |
-| `prism guard check` | Non-interactive pattern check (manifest v3) |
-| `prism rules bootstrap` | Detect stack, generate manifest, push to rules repo |
-| `prism rules sync` | ~~Legacy v2.~~ Generate `.prism-patterns.json` from local review history (deprecated) |
-| `prism rules push` | ~~Legacy v2.~~ Push a local `.prism-patterns.json` to the rules repo (deprecated) |
-| `prism rules stats` | Show aggregated finding patterns from local review history |
-| `prism review start` | Run an AI code review on a PR |
-
-### guard check flags
-
-| Flag | Description |
-|------|-------------|
-| `--workspace, -w` | Bitbucket workspace (auto-detected from git origin) |
-| `--repo, -r` | Repository slug (auto-detected from git origin) |
-| `--pr, -p` | Pull request ID (interactive picker if omitted) |
-| `--verbose` | Show diff context and suggestions |
-| `--min-severity` | Filter: `critical`, `high`, `medium`, `low`, `info` |
-| `--json` | Structured JSON output (CI-friendly) |
-| `--skip-ast` | Skip ast-grep, keyword-only matching |
-| `--auto-tune` | Auto-exclude patterns with repeated false positives |
-| `--suggest-rules` | Generate AI rules from recurring findings |
-| `--mark-fp` | Mark pattern IDs as false positive (comma-separated) |
-| `--patterns` | Path to local patterns file (bypasses manifest) |
-| `--remote` | **Deprecated.** Use v2 remote fetch path |
-
-### Exit codes (guard check)
-
-- `0` — no matches found
-- `1` — matches found (or error)
-
-Useful in CI:
-
-```bash
-prism guard check --pr "$PR_ID" --min-severity high --json > findings.json
-```
-
----
-
-## Concepts
-
-### Manifest v3
-
-A `ProjectManifest` lives at `projects/<workspace>/<repo>.json` in the shared rules repo. It references rulesets by id instead of inlining patterns:
-
-```json
-{
-  "version": 3,
-  "generatedAt": "2026-04-13T21:00:00.000Z",
-  "stack": {
-    "languages": ["typescript"],
-    "frameworks": [{ "name": "angular", "version": "17.3.0" }],
-    "detectedAt": "2026-04-13T21:00:00.000Z"
-  },
-  "includes": ["angular/base", "angular/v17", "shared/typescript", "shared/security@1.0.0"],
-  "excludes": ["general--debug--console-log"],
-  "patterns": []
-}
-```
-
-- `includes` — ruleset IDs to pull in (supports `@version` pinning)
-- `excludes` — pattern IDs to skip (auto-tune populates this)
-- `patterns` — project-specific custom patterns (AI suggestions land here)
-
-### Rulesets
-
-Built-in rulesets today (9 rulesets, 30+ ast-grep patterns):
-
-- `shared/general`, `shared/security`, `shared/typescript`
-- `angular/base`, `angular/v17`
-- `react/base`
-- `nestjs/base`
-- `ag-grid/base`, `ag-grid/v32`
-
-### Remote catalog structure
-
-All teams share a single Bitbucket rules repository that hosts manifests and versioned rulesets. The default shared repo is `walzate1/prism-rules`:
-
-```
-{rules-repo} (Bitbucket)
-├── projects/{workspace}/{repo}.json    # per-project manifest
-├── rulesets/{id}.json                  # unversioned rulesets (backward compat)
-└── catalog/
-    ├── index.json                      # catalog index (all rulesets + versions)
-    └── {id}/{version}.json             # immutable versioned rulesets
-```
-
-### Severity levels
-
-`critical` · `high` · `medium` · `low` · `info`
-
-### Pattern resolution flow
-
-1. `--patterns <file>` explicitly set → use local file (bypasses manifest)
-2. Fetch manifest from `projects/<ws>/<repo>.json`
-3. If no manifest → **auto-bootstrap** (detect stack → generate → push → continue)
-4. If manifest is stale (>7 days) → **auto-refresh** (re-detect stack → smart merge → push)
-5. Resolve includes via 3-level fallback (versioned → unversioned → static builtin)
-6. Apply excludes → merge custom patterns → run guard
-
----
-
-## License
-
-UNLICENSED — All rights reserved.
+# PRISM-PR
+
+> **Alpha** — this package is in active development (`1.0.0-alpha`). APIs and commands may change between releases.
+
+Intelligent Pull Request review orchestrator for Bitbucket. AI-powered code review plus pattern-based pre-checks using ast-grep structural matching, a shared team rules repository, and a self-evolving rule system that learns from your feedback.
+
+## Install
+
+```bash
+npm i -g prism-pr
+```
+
+## Requirements
+
+- Node.js **>= 22.5.0** (SQLite is loaded via the native `node:sqlite` module)
+- Bitbucket Cloud account with an Atlassian API token
+- AI provider (one of):
+  - `ANTHROPIC_API_KEY` environment variable (preferred), or
+  - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+
+## Setup
+
+```bash
+prism login
+```
+
+Your Bitbucket app password / API token needs these permissions:
+
+- Repositories: **Read** + **Write**
+- Pull requests: **Read** + **Write**
+
+## Discoverability — always available
+
+Every command documents itself via `--help`. If something in this README is stale, trust `--help`:
+
+```bash
+prism --help                      # full command tree
+prism rules --help                # subcommands under `rules`
+prism guard --help                # subcommands under `guard`
+prism rules bootstrap --help      # flags + examples for a specific command
+prism guard check --help
+prism review start --help
+```
+
+---
+
+## Quick start — zero config
+
+PRISM auto-detects your stack and bootstraps rules on the first run. No setup needed.
+
+```bash
+cd your-bitbucket-repo
+prism guard check
+```
+
+That's it. On first run, PRISM will:
+
+1. Detect workspace/repo from your git remote
+2. Fetch `package.json` via Bitbucket API to detect your stack (TypeScript, Angular, React, NestJS, AG Grid, …)
+3. Generate a manifest with the matching rulesets
+4. Push everything to the shared rules repository
+5. Resolve patterns and check your PR
+
+### Manual bootstrap (optional)
+
+If you prefer explicit control:
+
+```bash
+# Detect stack and push manifest + rulesets to the shared rules repo
+prism rules bootstrap
+
+# Preview without pushing
+prism rules bootstrap --dry-run
+
+# JSON output (CI-friendly)
+prism rules bootstrap --dry-run --json
+
+# Explicit workspace/repo/branch
+prism rules bootstrap --workspace acme --repo my-repo --branch develop
+```
+
+### Check a PR
+
+```bash
+# Interactive PR picker (auto-detects workspace/repo from git origin)
+prism guard check
+
+# Pick a PR by ID
+prism guard check --pr 42
+
+# Full output with code snippets and suggestions
+prism guard check --pr 42 --verbose
+
+# Filter by severity
+prism guard check --pr 42 --min-severity high --verbose
+
+# JSON output for CI
+prism guard check --pr 42 --json
+```
+
+**`--verbose` gates the snippet and suggestion.** Without it, matches show severity badge + title + file:line only. With `--verbose`, you get diff context with a pointer on the exact line, plus the fix suggestion.
+
+---
+
+## Living Rules — self-evolving rule system
+
+PRISM's rules aren't static. They learn, adapt, and grow with your codebase.
+
+### Auto-Refresh
+
+Manifests detect when your stack changes. If you add a new framework (e.g. NestJS) to your project, the next guard check automatically updates the manifest with the new rulesets. Default staleness threshold: 7 days.
+
+### Versioned Catalog
+
+Rulesets are published as immutable versioned artifacts:
+
+```
+catalog/
+  shared/security/1.0.0.json    # immutable, infinite cache
+  shared/general/1.0.0.json
+  angular/v17/1.0.0.json
+  ...
+catalog/index.json               # lists all rulesets + latest versions
+```
+
+Manifests can pin versions: `"shared/security@1.2.0"`. Unversioned includes resolve to latest. A 3-level fallback chain ensures resilience: versioned remote → unversioned remote → static builtin catalog.
+
+### Feedback Loop & Auto-Tune
+
+Mark findings as false positives. After enough feedback, PRISM auto-excludes noisy patterns.
+
+```bash
+# CLI: mark specific pattern IDs as false positive
+prism guard check --pr 42 --mark-fp "security--xss--innerHTML-usage,general--debug--console-log"
+
+# CLI: auto-exclude patterns with 3+ false positives
+prism guard check --pr 42 --auto-tune
+```
+
+In the TUI, press `[f]` on any finding to mark it as a false positive. Press `[t]` in the results screen to apply auto-tune.
+
+### AI Rule Suggestion
+
+PRISM can analyze findings from any review and generate new ast-grep rules automatically. Rule suggestions are a **post-review** action — you see the findings first, then decide which patterns should become permanent rules.
+
+```bash
+# CLI: generate rules from guard findings
+prism guard check --pr 42 --suggest-rules
+
+# CLI: generate rules from AI review findings
+prism review start --workspace acme --repo app --pr 42 --suggest-rules
+```
+
+PRISM uses the same AI provider configured for reviews (auto-detects from `ANTHROPIC_API_KEY` or falls back to Claude Code CLI).
+
+In the TUI, press `[g]` on any results screen (guard results or AI review findings) to generate rule suggestions on demand. Review, accept/reject, and apply to the manifest.
+
+---
+
+## Interactive TUI
+
+```bash
+prism           # main TUI (review + navigation)
+prism guard     # guard-focused TUI
+```
+
+Launches a full Ink-based terminal UI with keyboard navigation.
+
+### Guardian Angel section
+
+- **Guard Check** — select workspace → repo → PR → run check
+- **Guard Check (auto-detect)** — detects workspace/repo from git origin, skips manual selection
+- **Rules Bootstrap** — detect stack and push manifest (dry-run toggle, branch override)
+
+### Guard options (toggleable in guard-home)
+
+| Key | Option | Description |
+|-----|--------|-------------|
+| `v` | Verbose | Show context lines and suggestions |
+| `s` | Severity | Cycle minimum severity filter |
+| `a` | AST | Toggle ast-grep matching on/off |
+
+### Guard results actions
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `↑↓` | Navigate | Browse findings |
+| `Enter` | Detail | View finding detail with context |
+| `f` | False positive | Mark finding as FP (in detail view) |
+| `j` | Export JSON | Export results to `prism-guard-results.json` |
+| `t` | Auto-tune | Batch-exclude patterns with enough FP feedback |
+| `g` | AI suggestions | Generate and review AI-suggested rules (on demand) |
+| `Esc` | Back | Return to previous screen |
+
+### AI Review findings actions
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `↑↓` | Navigate | Browse findings |
+| `Enter` | Detail | View finding detail |
+| `g` | AI suggestions | Generate rules from review findings (on demand) |
+| `p` | Publish | Publish findings to Bitbucket PR |
+| `Esc` | Back | Return to previous screen |
+
+---
+
+## AI Review — full PR analysis (LLM-powered)
+
+```bash
+prism review start --workspace acme --repo app --pr 42
+
+# Verbose logging
+prism review start --workspace acme --repo app --pr 42 --verbose
+
+# Pick a provider explicitly
+prism review start --workspace acme --repo app --pr 42 --provider anthropic
+prism review start --workspace acme --repo app --pr 42 --provider claude-code
+
+# Generate rule suggestions from findings
+prism review start --workspace acme --repo app --pr 42 --suggest-rules
+```
+
+> **Note:** `review start` requires `--workspace` and `--repo` explicitly (no auto-detect from git origin). `guard check` auto-detects both.
+
+The AI review runs specialized agents (TypeScript, PHP, CSS, Security, Architecture, Performance, …) and produces findings with inline suggestions. Findings are stored in a local SQLite database for review memory and pattern generation.
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `prism` | Launch main interactive TUI |
+| `prism login` | Authenticate with Bitbucket |
+| `prism logout` | Remove stored credentials |
+| `prism guard` | Guard Check TUI |
+| `prism guard check` | Non-interactive pattern check (manifest v3) |
+| `prism rules bootstrap` | Detect stack, generate manifest, push to rules repo |
+| `prism rules sync` | ~~Legacy v2.~~ Generate `.prism-patterns.json` from local review history (deprecated) |
+| `prism rules push` | ~~Legacy v2.~~ Push a local `.prism-patterns.json` to the rules repo (deprecated) |
+| `prism rules stats` | Show aggregated finding patterns from local review history |
+| `prism review start` | Run an AI code review on a PR |
+
+### guard check flags
+
+| Flag | Description |
+|------|-------------|
+| `--workspace, -w` | Bitbucket workspace (auto-detected from git origin) |
+| `--repo, -r` | Repository slug (auto-detected from git origin) |
+| `--pr, -p` | Pull request ID (interactive picker if omitted) |
+| `--verbose` | Show diff context and suggestions |
+| `--min-severity` | Filter: `critical`, `high`, `medium`, `low`, `info` |
+| `--json` | Structured JSON output (CI-friendly) |
+| `--skip-ast` | Skip ast-grep, keyword-only matching |
+| `--auto-tune` | Auto-exclude patterns with repeated false positives |
+| `--suggest-rules` | Generate AI rules from recurring findings |
+| `--mark-fp` | Mark pattern IDs as false positive (comma-separated) |
+| `--patterns` | Path to local patterns file (bypasses manifest) |
+| `--remote` | **Deprecated.** Use v2 remote fetch path |
+
+### Exit codes (guard check)
+
+- `0` — no matches found
+- `1` — matches found (or error)
+
+Useful in CI:
+
+```bash
+prism guard check --pr "$PR_ID" --min-severity high --json > findings.json
+```
+
+---
+
+## Concepts
+
+### Manifest v3
+
+A `ProjectManifest` lives at `projects/<workspace>/<repo>.json` in the shared rules repo. It references rulesets by id instead of inlining patterns:
+
+```json
+{
+  "version": 3,
+  "generatedAt": "2026-04-13T21:00:00.000Z",
+  "stack": {
+    "languages": ["typescript"],
+    "frameworks": [{ "name": "angular", "version": "17.3.0" }],
+    "detectedAt": "2026-04-13T21:00:00.000Z"
+  },
+  "includes": ["angular/base", "angular/v17", "shared/typescript", "shared/security@1.0.0"],
+  "excludes": ["general--debug--console-log"],
+  "patterns": []
+}
+```
+
+- `includes` — ruleset IDs to pull in (supports `@version` pinning)
+- `excludes` — pattern IDs to skip (auto-tune populates this)
+- `patterns` — project-specific custom patterns (AI suggestions land here)
+
+### Rulesets
+
+Built-in rulesets today (9 rulesets, 30+ ast-grep patterns):
+
+- `shared/general`, `shared/security`, `shared/typescript`
+- `angular/base`, `angular/v17`
+- `react/base`
+- `nestjs/base`
+- `ag-grid/base`, `ag-grid/v32`
+
+### Remote catalog structure
+
+All teams share a single Bitbucket rules repository that hosts manifests and versioned rulesets. The default shared repo is `walzate1/prism-rules`:
+
+```
+{rules-repo} (Bitbucket)
+├── projects/{workspace}/{repo}.json    # per-project manifest
+├── rulesets/{id}.json                  # unversioned rulesets (backward compat)
+└── catalog/
+    ├── index.json                      # catalog index (all rulesets + versions)
+    └── {id}/{version}.json             # immutable versioned rulesets
+```
+
+### Severity levels
+
+`critical` · `high` · `medium` · `low` · `info`
+
+### Pattern resolution flow
+
+1. `--patterns <file>` explicitly set → use local file (bypasses manifest)
+2. Fetch manifest from `projects/<ws>/<repo>.json`
+3. If no manifest → **auto-bootstrap** (detect stack → generate → push → continue)
+4. If manifest is stale (>7 days) → **auto-refresh** (re-detect stack → smart merge → push)
+5. Resolve includes via 3-level fallback (versioned → unversioned → static builtin)
+6. Apply excludes → merge custom patterns → run guard
+
+---
+
+## License
+
+UNLICENSED — All rights reserved.