claude-git-hooks 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.21.0] - 2026-03-10
+
+### ✨ Added
+- New `analyze-pr` command to analyze GitHub PRs with team guidelines and post review comments (#86)
+- Linear ticket enrichment for PR analysis - automatically fetches ticket context when `[AUT-1234]` pattern found in PR title
+- New `setup-linear` command for interactive Linear token configuration
+- Centralized token persistence via `token-store.js` utility for managing settings.local.json
+- PR statistics tracking with write-only JSONL analytics at `.claude/statistics/pr/stats.jsonl`
+- Interactive comment workflow for PR analysis - confirm, select, or skip findings before posting
+- Auto-detection of preset from PR labels, Linear ticket labels, or file extensions
+- New `ANALYZE_PR.md` prompt template for GitHub PR review with category injection
+- Category normalization with fuzzy alias mapping for analysis results
+
+### 🔧 Changed
+- Extended `github-api.js` with PR fetch, review creation, and URL parsing capabilities
+- Updated documentation (README, README-NPM, CLAUDE.md) with analyze-pr usage and architecture
+
+
 ## [2.20.0] - 2026-03-09
 
 ### ✨ Added

package/CLAUDE.md

@@ -10,7 +10,8 @@
 2. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
 3. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
 4. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
-5. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset)
+5. **PR review**: `claude-hooks analyze-pr <url>` analyzes a GitHub PR with preset guidelines, Linear ticket enrichment, and posts review comments
+6. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset)
 
 ## Architecture
 
@@ -54,8 +55,10 @@ claude-git-hooks/
 │   │   ├── install.js                # Install command - dependencies, hooks, templates
 │   │   ├── hooks.js                  # Hook management - enable, disable, status, uninstall
 │   │   ├── analyze-diff.js           # Diff analysis - generate PR metadata from git diff
+│   │   ├── analyze-pr.js             # PR analysis - analyze GitHub PR with team guidelines
 │   │   ├── create-pr.js              # PR creation - full Octokit workflow
 │   │   ├── setup-github.js           # Token setup - interactive GitHub configuration
+│   │   ├── setup-linear.js           # Token setup - interactive Linear configuration
 │   │   ├── presets.js                # Preset management - list, set, show current
 │   │   ├── update.js                 # Self-update - check and install latest version
 │   │   ├── migrate-config.js         # Config migration - legacy to v2.8.0 format
@@ -78,8 +81,11 @@ claude-git-hooks/
 │       ├── logger.js                 # Logging system - centralized output, debug mode
 │       ├── preset-loader.js          # Preset system - load tech-stack configurations
 │       ├── pr-metadata-engine.js     # PR metadata generation - branch context, diff reduction, metadata (v2.14.0)
-│       ├── github-api.js             # Octokit integration - PR creation, token validation
+│       ├── github-api.js             # Octokit integration - PR creation, PR analysis, token validation
 │       ├── github-client.js          # GitHub helpers - CODEOWNERS parsing, reviewers
+│       ├── token-store.js            # Token persistence - centralized settings.local.json read/write
+│       ├── linear-connector.js       # Linear API - ticket context fetching with retry
+│       ├── pr-statistics.js          # PR statistics - write-only JSONL analytics
 │       ├── task-id.js                # Task ID extraction - Jira, GitHub, Linear patterns
 │       ├── interactive-ui.js         # CLI UI components - previews, prompts, spinners
 │       ├── judge.js                  # Auto-fix judge - LLM verdict + search/replace fixes (v2.20.0)
@@ -100,6 +106,7 @@ claude-git-hooks/
 │   ├── CLAUDE_ANALYSIS_PROMPT.md     # Analysis prompt - code review template
 │   ├── CLAUDE_RESOLUTION_PROMPT.md   # Resolution prompt - structured JSON output for judge + manual use
 │   ├── ANALYZE_DIFF.md               # PR analysis - diff review template
+│   ├── ANALYZE_PR.md                 # PR analysis - GitHub PR review template with category injection
 │   ├── GENERATE_CHANGELOG.md         # CHANGELOG generation - commit analysis template (v2.12.0)
 │   ├── DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md  # Orchestration prompt - Opus batch grouping (v2.20.0)
 │   ├── HELP_QUERY.md                 # AI help - question answering with NEED_MORE_CONTEXT protocol (v2.18.0)
@@ -186,8 +193,10 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 | Analysis timeout        | 300s    | Per-batch timeout                                  |
 | Commit msg timeout      | 300s    | Message generation timeout                         |
 | PR metadata timeout     | 180s    | Engine default (reads config)                      |
-| Judge model             | opus    | Default, configurable via `config.judge.model`     |
+| Judge model             | sonnet  | Default, configurable via `config.judge.model`     |
 | Judge timeout           | 120s    | Per-judge call timeout                             |
+| PR analysis model       | sonnet  | Default, configurable via `config.prAnalysis.model` |
+| PR analysis timeout     | 300s    | Per-analysis Claude call                           |
 
 **Judge behavior (v2.20.0):**
 
@@ -252,10 +261,12 @@ consolidateResults()
 | `hooks.js`              | Hook management           | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()`                |
 | `analyze.js`            | Interactive code analysis | `runAnalyze()`                                                                |
 | `analyze-diff.js`       | Diff analysis             | `runAnalyzeDiff()`                                                            |
+| `analyze-pr.js`         | PR analysis from URL      | `runAnalyzePr()`, `normalizeCategory()`                                       |
 | `create-pr.js`          | PR creation               | `runCreatePr()`                                                               |
 | `bump-version.js`       | Version management        | `runBumpVersion()`                                                            |
 | `generate-changelog.js` | CHANGELOG generation      | `runGenerateChangelog()`                                                      |
-| `setup-github.js`       | Token setup               | `runSetupGitHub()`                                                            |
+| `setup-github.js`       | Token setup (GitHub)      | `runSetupGitHub()`                                                            |
+| `setup-linear.js`       | Token setup (Linear)      | `runSetupLinear()`                                                            |
 | `presets.js`            | Preset management         | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()`                    |
 | `update.js`             | Self-update               | `runUpdate()`                                                                 |
 | `migrate-config.js`     | Config migration          | `runMigrateConfig()`                                                          |
@@ -280,8 +291,11 @@ consolidateResults()
 | `git-tag-manager.js`     | Git tag operations    | `createTag()`, `pushTags()`, `getLocalTags()`, `getRemoteTags()`, `compareLocalAndRemoteTags()`, `tagExists()` (v2.12.0)                                                       |
 | `version-manager.js`     | Version management    | `discoverVersionFiles()`, `getDiscoveryResult()`, `readVersionFromFile()`, `writeVersionToFile()`, `updateVersionFiles()`, `modifySuffix()`, `incrementVersion()`, `parseVersion()`, `validateVersionFormat()`, `compareVersions()`, `validateVersionAlignment()` (v2.15.5)                             |
 | `changelog-generator.js` | CHANGELOG generation  | `generateChangelogEntry()`, `updateChangelogFile()`, `getLastFinalVersionTag()`, `getCommitsSinceTag()`, `discoverChangelogFiles()`, `selectChangelogFile()` (v2.12.0)         |
-| `github-api.js`          | Octokit integration   | `createPullRequest()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()`                                                |
+| `github-api.js`          | Octokit integration   | `createPullRequest()`, `fetchPullRequest()`, `fetchPullRequestFiles()`, `createPullRequestReview()`, `parseGitHubPRUrl()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
 | `github-client.js`       | GitHub helpers        | `getReviewersForFiles()`, `parseGitHubRepo()`                                                                                                                                  |
+| `token-store.js`         | Token persistence     | `loadToken()`, `saveToken()`, `hasToken()`, `loadLocalSettings()`                                                                                                              |
+| `linear-connector.js`    | Linear integration    | `loadLinearToken()`, `testConnection()`, `fetchTicket()`, `extractLinearTicketFromTitle()`, `parseLinearIdentifier()`, `LinearConnectorError`                                   |
+| `pr-statistics.js`       | PR statistics         | `recordPRAnalysis()` — write-only JSONL at `.claude/statistics/pr/stats.jsonl`                                                                                                  |
 | `preset-loader.js`       | Preset system         | `loadPreset()`, `listPresets()`                                                                                                                                                |
 | `task-id.js`             | Task ID extraction    | `getOrPromptTaskId()`, `formatWithTaskId()`                                                                                                                                    |
 | `logger.js`              | Logging system        | `info()`, `warning()`, `error()`, `debug()`                                                                                                                                    |
@@ -361,6 +375,21 @@ claude-hooks analyze-diff develop
   → saves to .claude/out/pr-analysis.json
 ```
 
+**Flow 3.5: Analyze PR from GitHub URL**
+
+```
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123
+  → parseGitHubPRUrl() → { owner, repo, number }
+  → fetchPullRequest() + fetchPullRequestFiles() via Octokit
+  → extractLinearTicketFromTitle() → fetchTicket() (optional enrichment)
+  → resolvePreset(): CLI flag → PR labels → ticket labels → auto-detect from extensions → 'default'
+  → loadPrompt('ANALYZE_PR.md') with preset guidelines + category injection
+  → executeClaudeWithRetry() → extractJSON() → normalizeCategory() with fuzzy aliases
+  → interactive comment workflow: post all / select / skip
+  → createPullRequestReview() with inline comments + review body
+  → recordPRAnalysis() → .claude/statistics/pr/stats.jsonl
+```
+
 **Flow 4: PR creation (with auto-push v2.11.0, engine v2.14.0)**
 
 ```
@@ -673,8 +702,11 @@ claude-hooks preset current           # View current preset
 
 # Analysis and PRs
 claude-hooks analyze-diff [branch]    # Analyze diff for PR
+claude-hooks analyze-pr <pr-url>      # Analyze GitHub PR with team guidelines
+claude-hooks analyze-pr <url> --dry-run  # Analyze without posting comments
 claude-hooks create-pr [branch]       # Create PR on GitHub
 claude-hooks setup-github             # Configure GitHub token
+claude-hooks setup-linear             # Configure Linear token
 
 # Version management
 claude-hooks bump-version patch       # Bump version (commits, tags locally)

package/README.md

@@ -41,10 +41,11 @@ claude-hooks create-pr develop
 - Prompts for confirmation (configurable)
 - Handles diverged branches gracefully
 
-### GitHub Token Setup
+### Token Setup
 
 ```bash
-claude-hooks setup-github  # Shows status and configuration options
+claude-hooks setup-github  # Configure GitHub token for PR creation
+claude-hooks setup-linear  # Configure Linear token for ticket enrichment
 ```
 
 **Option 1 - Settings file (recommended):**
@@ -94,6 +95,24 @@ claude-hooks analyze-diff develop
 # Generates PR metadata without creating
 ```
 
+### Analyze PR from GitHub URL
+
+```bash
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123
+# Fetches PR, applies preset guidelines, posts review comments
+
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123 --dry-run
+# Analyze without posting comments
+
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123 --preset backend --model opus
+# Override preset and model
+```
+
+- Auto-detects preset from PR labels, Linear ticket labels, or file extensions
+- Enriches with Linear ticket context when `[AUT-1234]` found in PR title
+- Interactive comment workflow: confirm/skip each finding before posting
+- Classifies into inline (file:line) and general (review-level) categories
+
 ### Bump Version
 
 Automatic version management with CHANGELOG generation and Git tagging:
@@ -261,10 +280,12 @@ claude-hooks update   # Update to latest version
 | `hooks.js` | **Hook management** - enable, disable, status, uninstall | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()` |
 | `analyze.js` | **Interactive code analysis** - analyze before committing | `runAnalyze()` |
 | `analyze-diff.js` | **Diff analysis** - generate PR metadata from git diff | `runAnalyzeDiff()` |
+| `analyze-pr.js` | **PR analysis** - analyze GitHub PR with team guidelines | `runAnalyzePr()` |
 | `create-pr.js` | **PR creation** - full workflow via Octokit | `runCreatePr()` |
 | `bump-version.js` | **Version management** - bump with CHANGELOG and Git tag | `runBumpVersion()` |
 | `generate-changelog.js` | **CHANGELOG generation** - standalone command | `runGenerateChangelog()` |
 | `setup-github.js` | **Token setup** - interactive GitHub configuration | `runSetupGitHub()` |
+| `setup-linear.js` | **Token setup** - interactive Linear configuration | `runSetupLinear()` |
 | `presets.js` | **Preset management** - list, set, show current | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()` |
 | `update.js` | **Self-update** - check and install latest version | `runUpdate()` |
 | `migrate-config.js` | **Config migration** - legacy to v2.8.0 format | `runMigrateConfig()` |
@@ -283,7 +304,10 @@ claude-hooks update   # Update to latest version
 | `prompt-builder.js` | **Prompt construction** - load templates, replace variables, inject commit context | `buildAnalysisPrompt()`, `loadPrompt()` |
 | `git-operations.js` | **Git abstractions** - staged files, diff, branch comparison | `getStagedFiles()`, `getDiff()`, `getRepoRoot()`, `resolveBaseBranch()`, `getDiffBetweenRefs()` |
 | `pr-metadata-engine.js` | **PR metadata generation** - branch context, diff reduction (v2.14.0) | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` |
-| `github-api.js` | **Octokit integration** - PR creation, token validation, content fetching | `createPullRequest()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
+| `github-api.js` | **Octokit integration** - PR creation, PR analysis, token validation, content fetching | `createPullRequest()`, `fetchPullRequest()`, `fetchPullRequestFiles()`, `createPullRequestReview()`, `parseGitHubPRUrl()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
+| `token-store.js` | **Token persistence** - centralized settings.local.json read/write | `loadToken()`, `saveToken()`, `hasToken()`, `loadLocalSettings()` |
+| `linear-connector.js` | **Linear integration** - ticket context fetching with retry | `fetchTicket()`, `extractLinearTicketFromTitle()`, `testConnection()`, `loadLinearToken()` |
+| `pr-statistics.js` | **PR statistics** - write-only JSONL analytics | `recordPRAnalysis()` |
 | `github-client.js` | **GitHub helpers** - CODEOWNERS parsing, reviewers | `getReviewersForFiles()`, `parseGitHubRepo()` |
 | `preset-loader.js` | **Preset system** - load tech-stack configurations | `loadPreset()`, `listPresets()` |
 | `task-id.js` | **Task ID extraction** - Jira, GitHub, Linear patterns | `getOrPromptTaskId()`, `formatWithTaskId()` |
@@ -338,6 +362,21 @@ claude-hooks analyze-diff|create-pr → bin/claude-hooks (router)
   → create-pr: additionally creates PR via Octokit API
 ```
 
+#### PR Analysis (analyze-pr)
+
+```
+claude-hooks analyze-pr <url> → bin/claude-hooks (router)
+  → lib/commands/analyze-pr.js
+  → parseGitHubPRUrl() → fetchPullRequest() + fetchPullRequestFiles()
+  → extractLinearTicketFromTitle() → fetchTicket() (optional enrichment)
+  → resolvePreset() (labels → ticket → auto-detect → default)
+  → loadPrompt('ANALYZE_PR.md') with preset guidelines + categories
+  → executeClaudeWithRetry() → extractJSON() → normalizeCategory()
+  → interactive comment workflow (confirm/skip)
+  → createPullRequestReview() → inline + general comments
+  → recordPRAnalysis() (JSONL statistics)
+```
+
 ### Config Priority
 
 ```
@@ -384,6 +423,7 @@ Preset always wins - tech-stack specific has priority over user preferences.
 | CLI argument parsing | `bin/claude-hooks` |
 | Install workflow | `lib/commands/install.js` |
 | PR creation flow | `lib/commands/create-pr.js` |
+| PR analysis from URL | `lib/commands/analyze-pr.js` |
 | Analysis logic | `lib/hooks/pre-commit.js` |
 | Message generation | `lib/hooks/prepare-commit-msg.js` |
 | Prompt templates | `templates/*.md` or `.claude/prompts/*.md` |
@@ -407,8 +447,10 @@ claude-git-hooks/
 │   │   ├── install.js            # Install command - hooks, templates
 │   │   ├── hooks.js              # Hook management - enable/disable
 │   │   ├── analyze-diff.js       # Diff analysis - PR metadata
+│   │   ├── analyze-pr.js         # PR analysis - GitHub PR review
 │   │   ├── create-pr.js          # PR creation - Octokit workflow
-│   │   ├── setup-github.js       # Token setup - interactive config
+│   │   ├── setup-github.js       # Token setup - interactive GitHub config
+│   │   ├── setup-linear.js       # Token setup - interactive Linear config
 │   │   ├── presets.js            # Preset commands - list/set
 │   │   ├── update.js             # Self-update - npm latest
 │   │   ├── migrate-config.js     # Migration - legacy to v2.8.0
@@ -421,7 +463,8 @@ claude-git-hooks/
 │   │   └── prepare-commit-msg.js # Message generation
 │   └── utils/                    # Reusable modules - shared logic
 │       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration
-│       └── judge.js                      # Auto-fix judge (v2.20.0)
+│       ├── judge.js                      # Auto-fix judge (v2.20.0)
+│       └── token-store.js               # Token persistence - settings.local.json
 ├── templates/
 │   ├── pre-commit                # Bash wrapper - invokes Node.js
 │   ├── prepare-commit-msg        # Bash wrapper - invokes Node.js

package/bin/claude-hooks

@@ -93,6 +93,7 @@ async function main() {
         [
             'install',
             'analyze-diff',
+            'analyze-pr',
             'create-pr',
             'bump-version',
             'generate-changelog',

package/lib/cli-metadata.js

@@ -5,7 +5,7 @@
  * Three consumers read from this registry:
  * 1. bin/claude-hooks — routing (replaces switch/case)
  * 2. installCompletions() — generates shell completion scripts at install time
- * 3. showStaticHelp() — can derive help text from metadata
+ * 3. showStaticHelp() — generates help text from this registry
  *
  * Adding a new command = adding one entry here.
  * Completions auto-update for every user at next install.
@@ -115,6 +115,21 @@ export const commands = [
             completion: "git branch --format='%(refname:short)'"
         }
     },
+    {
+        name: 'analyze-pr',
+        description: 'Analyze a GitHub PR with team guidelines',
+        handler: async () => (await import('./commands/analyze-pr.js')).runAnalyzePr,
+        args: { name: 'pr-url' },
+        flags: {
+            '--preset': {
+                description: 'Override preset selection',
+                takesValue: true,
+                values: PRESET_NAMES
+            },
+            '--model': { description: 'Claude model override', takesValue: true },
+            '--dry-run': { description: 'Analyze without posting comments' }
+        }
+    },
     {
         name: 'create-pr',
         description: 'Create PR with auto-generated metadata',
@@ -129,6 +144,11 @@ export const commands = [
         description: 'Configure GitHub token for PR creation',
         handler: async () => (await import('./commands/setup-github.js')).runSetupGitHub
     },
+    {
+        name: 'setup-linear',
+        description: 'Configure Linear token for ticket enrichment',
+        handler: async () => (await import('./commands/setup-linear.js')).runSetupLinear
+    },
     {
         name: 'presets',
         description: 'List all available presets',