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

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
  • OPENAI_API_KEY environment variable, or
  • GEMINI_API_KEY environment variable, or
  • Claude Code CLI installed and authenticated

Setup

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:

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.

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:

# 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

# 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/[email protected]". 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.

# 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.

# 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, OPENAI_API_KEY, or GEMINI_API_KEY, then 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

prism           # main TUI (review + navigation)
prism guard     # guard-focused TUI

Launches a full Ink-based terminal UI with keyboard navigation.

In Settings, a unified tabbed screen:

• Provider & Keys: provider selection (auto, anthropic, openai, gemini, claude-code) and Anthropic/OpenAI/Gemini key registration
• Models & Agents: default model, per-agent model picker, presets (Max/Balance/Low), and custom model IDs
• Defaults: review defaults (minimum severity, content mode, …)

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)

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 openai
prism review start --workspace acme --repo app --pr 42 --provider gemini
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.

File-by-File Execution

Each agent processes files one at a time (not batched), eliminating output truncation on large PRs. A flat work queue keeps all semaphore slots busy — when one agent finishes its files, those slots are immediately used for pending files from other agents.

Live Progress View

While a review runs, the TUI shows honest, real-time progress instead of a vague spinner:

• Files hero bar — a single Files [████░░] X/Y · N active · M done line tracks overall work. The X/Y counter reaches Y/Y because cache-skipped, per-file-failed, and batch-failed files all count as done (no more bars that stall short of 100%).
• Concurrency slots — a vertical panel lists each busy slot with the agent, the file it's on, and live elapsed time per slot.
• Per-agent rows — each agent reports filesDone/totalFiles and its accumulated findings. Each agent emits its aggregate complete event the moment its own last file reaches terminal disposition (success/fail/cache-skip), so agents never linger in a "finalizing…" state — completion is immediate and per-agent, not a burst at the end of the run.
• Narrow terminals degrade gracefully (the hero bar and slots collapse to compact summaries). The hero bar is sized to stay inside the app frame on narrow terminals (border and padding chrome subtracted), preventing unwanted line-wrapping.

Incremental Re-Reviews (Hash Cache)

PRISM tracks a SHA-256 hash per file per agent. On re-review:

| File state | Action | |------------|--------| | Unchanged + previously clean | Skip (zero tokens) | | Unchanged + had findings | Re-review (dev hasn't fixed) | | Changed | Re-review (always) |

This saves 80%+ tokens on re-reviews where only a few files changed.

Per-Agent Model Presets

Configure all 14 agent models at once via the Settings screen:

| Preset | Critical agents (Security, Architecture) | All others | |--------|------------------------------------------|------------| | Max | Opus | Opus | | Balance (default) | Opus | Sonnet | | Low | Sonnet | Haiku |

Publish Failure Diagnostics

When Bitbucket rejects comments during publish, PRISM tells you exactly why instead of a generic error:

• Specific abort reasons surfaced in the TUI and CLI (e.g. Bitbucket's 200-comment-per-PR limit, missing PR/permissions)
• The raw Bitbucket error body and session ID are persisted locally for later inspection
• Errors thrown before a retry even starts are logged and persisted too — nothing is silently lost
• Response bodies are now captured for 401 and all 5xx errors too (not only 403), so transient gateway or auth failures keep their full detail

Publish Quota Pre-Check

PRISM now checks Bitbucket's 200-comment-per-PR cap before publishing, so you no longer discover the limit mid-flight with half the findings posted:

• The publish flow calls Bitbucket once to read the current comment count and compares it against BITBUCKET_COMMENT_LIMIT (200) plus the findings about to be posted
• In the TUI, when the projected total would exceed the cap, an interactive modal appears with three choices:
  • (a)bort — cancel the publish; nothing is posted
  • (p)ublish first N — post exactly the remaining quota (cap − current); the rest are reported as skipped
  • (c)ancel — close the modal and keep the session as-is, no error raised
• In non-TTY / CLI mode, the publish fails fast with the quota error code (a dedicated member of SessionPublishRetryErrorCode) instead of attempting partial publishes
• The pre-check uses ?pagelen=0 against the comments endpoint — single cheap call, no extra round trips per finding

Provider Retry Resilience

Transient AI-provider failures (5xx gateway errors, 429 rate limits, network timeouts) are automatically retried with exponential backoff — up to 2 retries, base delay 1 s, cap 8 s, with jitter. Retry-After headers are honored (clamped to the backoff cap). Auth errors and parse errors are never retried. OpenAI and Gemini providers use the shared withRetry utility; Anthropic's SDK already retries internally.

Comment Lifecycle — manage prior PRISM comments

Over a PR's life, PRISM accumulates review comments. prism review lifecycle captures them, classifies each by state (resolved, active, dev-reply), posts a single summary comment, and cleans up the resolved ones. Dev replies are never deleted.

# Preview only (default) — classify and report, ZERO Bitbucket writes
prism review lifecycle https://bitbucket.org/acme/app/pull-requests/42

# Full pipeline — post summary comment + delete resolved PRISM comments
prism review lifecycle https://bitbucket.org/acme/app/pull-requests/42 --cleanup

# Structured JSON (CI-friendly)
prism review lifecycle https://bitbucket.org/acme/app/pull-requests/42 --json

Breaking change (alpha.77): the default is now preview-only. Add --cleanup to post the summary and delete comments. The --no-cleanup flag was removed; --dry-run is deprecated (redundant with the new default).

In the TUI, Comment Lifecycle (home menu) runs the same flow with a rich preview screen: confirm to post + clean up, or Esc to abort with no writes. After publishing, it offers to start a new review on the same PR (URL pre-filled).

| Exit code | Meaning | |-----------|---------| | 0 | Preview OK, or full pipeline success | | 1 | Capture or summary failed (Bitbucket untouched or partial) | | 2 | Cleanup partial failure (some deletes failed) |

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 | | prism review lifecycle | Preview or clean up prior PRISM comments on a PR (preview-only by default; --cleanup deletes) |

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:

prism guard check --pr "$PR_ID" --min-severity high --json > findings.json

Repo Configuration (.prism.yml)

Optional file at the repo root. Key fields:

# Agent selection (overrides auto-detection)
agents: [ts-reviewer, security-reviewer, php-reviewer]

# Accessibility checks (OFF by default — opt-in)
accessibility: true

# Per-agent model overrides
agentModels:
  security-reviewer: claude-opus-4-5
  ts-reviewer: claude-sonnet-4-5

# Severity overrides
severityOverrides:
  - match: { category: security }
    severity: critical

# Skills (custom review instructions per agent)
skills:
  - id: laravel-conventions
    name: Laravel Conventions
    instructions: "Use repository pattern. No Eloquent in controllers."
    agentIds: [php-reviewer, architecture-reviewer]

Stack detection is mandatory. If PRISM cannot find a manifest file (package.json, composer.json, go.mod, etc.) in the repo root or common subfolders, the review is blocked to avoid incorrect suggestions. Add the appropriate manifest to your repo.

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:

{
  "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/[email protected]"],
  "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 (10 rulesets, 30+ ast-grep patterns):

• shared/general, shared/security, shared/typescript
• angular/base, angular/v2, 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.