pr-prism

https://github.com/yosefhayim/pr-prism
Admin
pr-prism is a stateful GitHub PR review scraper for AI agents that filters noise, caches seen...
Tokens:11,068
Snippets:83
Trust Score:4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Run pr-prism Without Installation

Source: https://github.com/yosefhayim/pr-prism/blob/main/README.md

Executes the `pr-review` command using `npx` without requiring a global or local installation of pr-prism. This is convenient for one-time use or testing the tool directly.

```bash
npx pr-prism pr-review -- 42
```

--------------------------------

### Install pr-prism Globally

Source: https://github.com/yosefhayim/pr-prism/blob/main/README.md

Installs the pr-prism package globally on your system, making the `pr-review` and `pr-resolve` commands available from any directory. This is useful for frequent use across multiple projects.

```bash
npm install -g pr-prism
```

--------------------------------

### Execute PR Auto-Resolve Commands

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Command-line examples for executing the auto-resolve functionality, including dry-run previews and agent tagging.

```bash
pnpm run pr-resolve -- 42 --auto              # auto-resolve addressed threads only
pnpm run pr-resolve -- 42 --auto --dry-run    # preview what would be resolved
pnpm run pr-resolve -- 42 --auto --tag-agents # auto-resolve + tag agents for re-review
```

--------------------------------

### Install pr-prism Locally for a Project

Source: https://github.com/yosefhayim/pr-prism/blob/main/README.md

Installs the pr-prism package as a development dependency for your current project. This allows you to use the `pr-review` and `pr-resolve` commands within the context of your project, typically via npm scripts.

```bash
npm install --save-dev pr-prism
```

--------------------------------

### CLI Command Interface for pr-resolve

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-design.md

Examples of how to invoke the pr-resolve tool, including the new --auto flag for smart resolution and various combinations with existing flags.

```bash
# Existing (unchanged) — resolve ALL threads from sidecar
pnpm run pr-resolve -- 42

# NEW — smart auto-resolve
pnpm run pr-resolve -- 42 --auto

# Combine with existing flags
pnpm run pr-resolve -- 42 --auto --tag-agents
pnpm run pr-resolve -- 42 --auto --dry-run
pnpm run pr-resolve -- 42 --auto --tag-agents --comment "Fixes pushed"
```

--------------------------------

### Implement Live Thread Fetching Utility

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

A TypeScript function that executes a GraphQL query against the GitHub API using the gh CLI. It handles temporary file creation for the request payload and error handling for authentication or API failures.

```typescript
function fetchThreadsLive(owner: string, repo: string, prNumber: number): AutoPayload {
  const reqFile = join(tmpdir(), ".pr-auto-resolve-req.json");
  writeFileSync(reqFile, JSON.stringify({ query: AUTO_GRAPHQL_QUERY, variables: { owner, repo, prNumber } }), "utf-8");
  try {
    return JSON.parse(run(`gh api https://api.github.com/graphql --input ${reqFile}`)) as AutoPayload;
  } catch (err) {
    console.error("gh API failed fetching threads. Is gh authenticated?");
    console.error((err as Error).message);
    process.exit(1);
  } finally {
    unlinkSync(reqFile);
  }
}
```

--------------------------------

### Extract and Fetch Utilities for PR Threads

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Functions to extract code suggestions from comment bodies using regex and fetch file contents from GitHub via the CLI. These utilities rely on the GitHub API and base64 decoding to retrieve file snapshots.

```typescript
function extractSuggestions(body: string): string[] {
  const suggestions: string[] = [];
  const regex = /```suggestion\n([\s\S]*?)```/g;
  let match: RegExpExecArray | null;
  while ((match = regex.exec(body)) !== null) {
    suggestions.push(match[1].trimEnd());
  }
  return suggestions;
}

function fetchFileAtHead(owner: string, repo: string, path: string, headSha: string): string | null {
  try {
    const raw = run(`gh api repos/${owner}/${repo}/contents/${path}?ref=${headSha}`);
    const parsed = JSON.parse(raw) as { content?: string; encoding?: string };
    if (parsed.encoding === "base64" && parsed.content) {
      return Buffer.from(parsed.content.replace(/\n/g, ""), "base64").toString("utf-8");
    }
    return null;
  } catch {
    return null;
  }
}
```

--------------------------------

### Git Version Control Commands

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Standard git commands used to stage and commit changes to the resolution script.

```bash
git add scripts/resolve-pr-threads.ts
git commit -m "feat: add thread classification with outdated + suggestion signals"
```

--------------------------------

### Execute PR review and resolution workflow

Source: https://github.com/yosefhayim/pr-prism/blob/main/llms.txt

The AI agent loop involves scraping new comments into markdown, implementing fixes, and then running the resolution script to update GitHub thread states and tag agents.

```bash
# 1. Scrape new comments
pnpm run pr-review -- <PR number>

# 2. Agent processes markdown and pushes fixes

# 3. Resolve threads and tag agents
pnpm run pr-resolve -- <PR number> --auto --tag-agents
```

--------------------------------

### Configure pr-prism behavior

Source: https://github.com/yosefhayim/pr-prism/blob/main/llms.txt

The .pr-prism.json file allows customization of the tool's behavior, specifically defining which AI agent handles to tag during the resolution process.

```json
{
  "agentMentions": ["cubic-dev-ai", "coderabbitai"]
}
```

--------------------------------

### Manage PR Review Workflow via CLI

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

Commands to scrape PR comments and resolve threads. These commands facilitate the iterative loop of reading feedback, applying changes, and notifying reviewers.

```bash
pr-review 42
pr-resolve 42 --auto --tag-agents
```

--------------------------------

### Suggestion Matching Logic

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Helper functions to normalize code lines and verify if a suggestion exists within a file's content. It uses whitespace-insensitive comparison to determine if a suggestion has been applied.

```typescript
function normalizeLine(line: string): string {
  return line.trim().replace(/\s+/g, " ");
}

function matchesSuggestion(fileContent: string, suggestion: string): boolean {
  const suggestionLines = suggestion.split("\n").map(normalizeLine).filter((l) => l.length > 0);
  if (suggestionLines.length === 0) return false;
  const fileLines = fileContent.split("\n").map(normalizeLine);

  for (let i = 0; i <= fileLines.length - suggestionLines.length; i++) {
    let allMatch = true;
    for (let j = 0; j < suggestionLines.length; j++) {
      if (fileLines[i + j] !== suggestionLines[j]) {
        allMatch = false;
        break;
      }
    }
    if (allMatch) return true;
  }
  return false;
}
```

--------------------------------

### Scrape PR reviews with pr-review

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

Scrapes new, actionable review comments from a GitHub PR. It supports interactive selection, direct PR numbers, and URL-based targeting, outputting results to a timestamped Markdown file.

```bash
# Interactive mode
pr-review

# Direct PR number
pr-review 42

# Process by full GitHub PR URL
pr-review https://github.com/owner/repo/pull/42

# Using npx
npx pr-prism pr-review -- 42
```

--------------------------------

### Perform smart auto-resolution

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

Automatically detects addressed feedback by checking if commented lines have changed or if suggested code blocks were applied. This reduces manual intervention in the review loop.

```bash
# Smart auto-resolve
pr-resolve 42 --auto

# Preview auto-resolve classifications
pr-resolve 42 --auto --dry-run

# Auto-resolve with agent tagging
pr-resolve 42 --auto --tag-agents
```

--------------------------------

### Define GraphQL Query for PR Threads

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

A GraphQL query constant used to fetch review threads, their outdated status, and associated comments from a GitHub pull request.

```graphql
const AUTO_GRAPHQL_QUERY = `
query($owner: String!, $repo: String!, $prNumber: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $prNumber) {
      headRefOid
      reviewThreads(first: 100) {
        nodes {
          id isResolved isOutdated
          path line originalLine
          comments(first: 20) {
            nodes {
              databaseId
              author { login }
              body
              path
              outdated
            }
          }
        }
      }
    }
  }
}`.trim();
```

--------------------------------

### Suggestion Matching Regex

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-design.md

A regular expression used to extract code blocks marked as suggestions from GitHub comment bodies for verification against the current file state.

```regex
/```suggestion\n([\s\S]*?)```/g
```

--------------------------------

### Implement runAutoResolve function (TypeScript)

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

This asynchronous function handles the core logic for automatically resolving PR threads. It fetches threads, classifies them based on resolution reasons (lines changed, suggestion applied), and conditionally resolves them or skips them. It also generates and posts a summary comment to the PR. Dependencies include `fetchThreadsLive`, `classifyThreads`, `loadConfig`, `postComment`, and utility functions like `mutateThread`.

```typescript
async function runAutoResolve(
  prNumber: number,
  owner: string,
  repo: string,
  isDryRun: boolean,
  shouldTag: boolean,
  customComment: string | null,
): Promise<void> {
  console.log(`\nAuto-resolving threads in ${owner}/${repo} #${prNumber}${isDryRun ? " [DRY RUN]" : ""}...\n`);

  const payload = fetchThreadsLive(owner, repo, prNumber);
  const pr = payload.data.repository.pullRequest;
  const headSha = pr.headRefOid;
  const allThreads = pr.reviewThreads.nodes;
  const unresolvedCount = allThreads.filter((t) => !t.isResolved).length;

  if (unresolvedCount === 0) {
    console.log("No unresolved threads found.");
    return;
  }

  const classified = classifyThreads(allThreads, owner, repo, headSha);
  const toResolve = classified.filter((c) => c.action === "resolve");
  const toSkip = classified.filter((c) => c.action === "skip");
  const linesChanged = toResolve.filter((c) => c.reason === "lines-changed").length;
  const suggestionApplied = toResolve.filter((c) => c.reason === "suggestion-applied").length;

  console.log(`  Unresolved threads: ${unresolvedCount}`);
  console.log(`  Will auto-resolve:  ${toResolve.length} (${linesChanged} lines changed, ${suggestionApplied} suggestion applied)`);
  console.log(`  Will skip:          ${toSkip.length}\n`);

  let ok = 0;
  let failed = 0;

  for (const { thread, reason } of toResolve) {
    const label = reason === "suggestion-applied" ? "suggestion applied" : "lines changed";
    if (isDryRun) {
      console.log(`  [dry-run] would resolve ${thread.id} (${label})`);
      ok++;
      continue;
    }
    if (mutateThread(thread.id, false)) {
      console.log(`  auto-resolved ${thread.id} (${label})`);
      ok++;
    } else {
      console.log(`  ${thread.id} — already resolved or mutation failed`);
      failed++;
    }
  }

  for (const { thread } of toSkip) {
    console.log(`  skipped ${thread.id} (no signal)`);
  }

  console.log(`\n${ok} auto-resolved${failed > 0 ? `, ${failed} failed` : ""}${toSkip.length > 0 ? `, ${toSkip.length} skipped` : ""}`);

  if (!isDryRun && (ok > 0 || toSkip.length > 0)) {
    const config = loadConfig();
    const mentions = shouldTag
      ? " " + (config.agentMentions ?? DEFAULT_AGENT_MENTIONS).map((a) => `@${a}`).join(" ")
      : "";

    const lines = [
      `**pr-prism auto-resolve** — ${ok} of ${unresolvedCount} threads resolved`,
      "",
    ];
    if (linesChanged > 0) lines.push(`**Auto-resolved (lines changed):** ${linesChanged}`);
    if (suggestionApplied > 0) lines.push(`**Auto-resolved (suggestion applied):** ${suggestionApplied}`);
    if (toSkip.length > 0) lines.push(`**Remaining (needs manual review):** ${toSkip.length}`);
    if (mentions.trim()) lines.push("", `${mentions.trim()} please re-review.`);
    if (customComment) lines.push("", customComment);

    const message = lines.join("\n");
    postComment(prNumber, owner, repo, message);
    console.log(`\nPosted summary comment.`);
  }
}
```

--------------------------------

### Manage PR thread resolution with pr-resolve

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

Resolves or unresolves PR review threads. Supports manual resolution, dry-run previews, and automatic tagging of AI agents upon completion.

```bash
# Resolve all threads from last scrape
pr-resolve 42

# Preview without mutating
pr-resolve 42 --dry-run

# Resolve and tag AI agents
pr-resolve 42 --tag-agents --comment "Fixed in commit abc123"

# Re-open resolved threads
pr-resolve 42 --unresolve
```

--------------------------------

### Commit changes for --auto flag feature (Bash)

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

This bash command stages the modified `scripts/resolve-pr-threads.ts` file and commits it with a descriptive message indicating the addition of the `--auto` flag and its associated smart thread classification and summary comment features.

```bash
git add scripts/resolve-pr-threads.ts
git commit -m "feat: add --auto flag with smart thread classification and summary comments"
```

--------------------------------

### Scrape New Comments for a PR

Source: https://github.com/yosefhayim/pr-prism/blob/main/README.md

Scrapes new comments for a specified GitHub Pull Request. It can be used interactively by listing open PRs, or directly by providing the PR number or its full URL. New comments are saved to a markdown file.

```bash
pr-review                  # list open PRs, pick interactively
pr-review 42               # process PR #42 directly
pr-review <url>            # process by full GitHub PR URL
```

--------------------------------

### Resolve PR Threads Automatically

Source: https://github.com/yosefhayim/pr-prism/blob/main/README.md

Resolves threads in a GitHub Pull Request based on specific criteria. The `--auto` flag enables smart resolution for threads where GitHub detects changes or suggestions have been applied. Dry-run and agent tagging options are also available.

```bash
pr-resolve 42                               # resolve all threads from last scrape
pr-resolve 42 --auto                        # smart resolve: addressed threads only
pr-resolve 42 --auto --dry-run              # preview what would be resolved
pr-resolve 42 --auto --tag-agents           # resolve + tag agents for re-review
pr-resolve 42 --tag-agents --comment "msg"  # custom message
pr-resolve 42 --unresolve                   # re-open resolved threads
```

--------------------------------

### Configure PR Resolve Script Header

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

The file header for resolve-pr-threads.ts defines the operational modes and CLI arguments for the PR resolution utility, including manual and auto-resolve capabilities.

```typescript
/*
 * Resolve (or unresolve) PR review threads and optionally tag AI agents.
 *
 * MODES
 *   Manual:  reads the sidecar .threads-<prNumber>.json written by pr-review
 *   Auto:    re-fetches live thread state from GitHub, resolves only threads
 *            where isOutdated=true or suggestion blocks match current file content
 *
 * USAGE
 *   pnpm run pr-resolve                        — latest .threads-*.json
 *   pnpm run pr-resolve -- 42                  — explicit PR number
 *   pnpm run pr-resolve -- 42 --auto           — smart auto-resolve (re-fetches from GitHub)
 *   pnpm run pr-resolve -- 42 --auto --dry-run — preview auto-resolve classifications
 *   pnpm run pr-resolve -- 42 --auto --tag-agents — auto-resolve + tag agents
 *   pnpm run pr-resolve -- 42 --dry-run        — preview without mutating
 *   pnpm run pr-resolve -- 42 --tag-agents     — resolve + post @mention comment
 *   pnpm run pr-resolve -- 42 --tag-agents --comment "Fixed in abc123"
 *   pnpm run pr-resolve -- 42 --unresolve      — re-open resolved threads
 *
 * CONFIG  (.pr-prism.json in repo root)
 *   { "agentMentions": ["cubic-dev-ai", "coderabbitai"] }
 */
```

--------------------------------

### Define Auto-Resolve TypeScript Interfaces

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Defines the data structures required to parse GitHub GraphQL responses for review threads and classify them for resolution. These interfaces support tracking thread state, outdated status, and resolution reasoning.

```typescript
interface AutoThreadComment {
  databaseId: number;
  author: { login: string };
  body: string;
  path: string;
  outdated: boolean;
}

interface AutoThread {
  id: string;
  isResolved: boolean;
  isOutdated: boolean;
  path: string;
  line: number | null;
  originalLine: number | null;
  comments: { nodes: AutoThreadComment[] };
}

interface AutoPayload {
  data: { repository: { pullRequest: { headRefOid: string; reviewThreads: { nodes: AutoThread[] }; }; }; };
}

type ResolutionReason = "lines-changed" | "suggestion-applied";

interface ClassifiedThread {
  thread: AutoThread;
  action: "resolve" | "skip";
  reason: ResolutionReason | "no-signal";
}
```

--------------------------------

### Integrate --auto flag logic into main function (TypeScript)

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

This code block replaces the latter part of the `main` function in `scripts/resolve-pr-threads.ts`. When the `--auto` flag is present, it ensures a PR number is provided, attempts to detect the owner and repository (first from a sidecar file, then falling back to git remote), and then calls the `runAutoResolve` function. The existing sidecar-based loop logic remains for cases where `--auto` is not used.

```typescript
  if (isAuto) {
    if (prNumber === null) {
      console.error("--auto requires a PR number. Usage: pnpm run pr-resolve -- <PR> --auto");
      process.exit(1);
    }
    // Try sidecar for owner/repo, fall back to git remote
    let owner: string;
    let repo: string;
    const sidecarPath = findSidecar(prNumber);
    if (sidecarPath) {
      const sidecar = JSON.parse(readFileSync(sidecarPath, "utf-8")) as ThreadsSidecar;
      owner = sidecar.owner;
      repo = sidecar.repo;
    } else {
      const remote = run("git remote get-url origin");
      const m = remote.match(/github\.com[:/]([^/]+)\/([^/\s.]+)/);
      if (!m) { console.error("Could not detect GitHub repo."); process.exit(1); }
      owner = m[1];
      repo = m[2].replace(/\.git$/, "");
    }
    await runAutoResolve(prNumber, owner, repo, isDryRun, shouldTag, customComment);
    return;
  }
```

--------------------------------

### Thread Classification Engine

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Classifies PR threads into 'resolve' or 'skip' actions. It evaluates whether threads are outdated or if suggestions have been successfully applied to the current file state.

```typescript
function classifyThreads(
  threads: AutoThread[],
  owner: string,
  repo: string,
  headSha: string,
): ClassifiedThread[] {
  const fileCache = new Map<string, string | null>();

  function getFile(path: string): string | null {
    if (!fileCache.has(path)) {
      fileCache.set(path, fetchFileAtHead(owner, repo, path, headSha));
    }
    return fileCache.get(path) ?? null;
  }

  return threads
    .filter((t) => !t.isResolved)
    .map((thread): ClassifiedThread => {
      if (thread.isOutdated || thread.line === null) {
        return { thread, action: "resolve", reason: "lines-changed" };
      }

      for (const comment of thread.comments.nodes) {
        const suggestions = extractSuggestions(comment.body);
        if (suggestions.length === 0) continue;

        const filePath = comment.path ?? thread.path;
        if (!filePath) continue;

        const fileContent = getFile(filePath);
        if (fileContent === null) {
          return { thread, action: "resolve", reason: "lines-changed" };
        }

        const allMatch = suggestions.every((s) => matchesSuggestion(fileContent, s));
        if (allMatch) {
          return { thread, action: "resolve", reason: "suggestion-applied" };
        }
      }

      return { thread, action: "skip", reason: "no-signal" };
    });
}
```

--------------------------------

### Define Thread Sidecar Format

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

The .threads-42.json file stores metadata and thread IDs for a specific pull request, enabling the resolver to track which threads are active.

```json
{
  "prNumber": 42,
  "owner": "owner",
  "repo": "repo",
  "threadIds": ["PRRT_kwDOABCDEF1234", "PRRT_kwDOABCDEF5678"]
}
```

--------------------------------

### Fetch Pull Request Thread Data via GraphQL

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-design.md

A GraphQL query designed to retrieve pull request thread information, including outdated status, file paths, and comment bodies, to determine if threads should be auto-resolved.

```graphql
query($owner: String!, $repo: String!, $prNumber: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $prNumber) {
      headRefOid
      reviewThreads(first: 100) {
        nodes {
          id isResolved isOutdated
          path line originalLine
          comments(first: 20) {
            nodes {
              databaseId
              author { login }
              body
              path
              outdated
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Define Scraped ID Cache Format

Source: https://context7.com/yosefhayim/pr-prism/llms.txt

The .scraped-ids.json file persists comment IDs to prevent the agent from re-processing the same feedback across multiple runs.

```json
{
  "seen": ["12345678", "12345679", "12345680"]
}
```

--------------------------------

### Parse --auto flag in main function (TypeScript)

Source: https://github.com/yosefhayim/pr-prism/blob/main/docs/plans/2026-03-14-auto-resolve-plan.md

Parses the `--auto` command-line argument within the `main` function of the `resolve-pr-threads.ts` script. This flag determines whether to trigger the automated thread resolution process. It's a simple boolean check against the provided arguments.

```typescript
const isAuto = args.includes("--auto");
```
Tokens:
Raw