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
  • 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 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

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)

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:

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:

{
  "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 (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.