difit 1.1.5 → 1.1.6

package/README.md

@@ -8,14 +8,9 @@ A lightweight command-line tool that spins up a local web server to display Git
 
 ## ✨ Features
 
-- 🌙 **GitHub-like UI**: Familiar dark theme file list and diff interface
-- 💬 **Inline Comments**: Add comments to specific lines and generate Claude Code prompts
-- 🔄 **Side-by-Side & Inline Views**: Choose your preferred diff viewing mode
-- 🖥️ **Terminal UI Mode**: View diffs directly in your terminal with `--tui` flag
 - ⚡ **Zero Config**: Just run `npx reviewit <commit>` and it works
-- 🔐 **Local Only**: Never exposes data over network - runs on localhost only
-- 🛠️ **Modern Stack**: React 18 + TypeScript + Tailwind CSS
-- 🎨 **Syntax Highlighting**: Dynamic language loading for Bash, PHP, SQL, Ruby, Java, and more
+- 🌙 **Review for AI**: Add comments and generate Claude Code prompts
+- 🖥️ **Terminal UI**: View diffs directly in terminal with `--tui`
 
 ## ⚡ Quick Start
 
@@ -30,6 +25,7 @@ npx reviewit    # View HEAD commit changes in a beautiful diff viewer
 ```bash
 npx reviewit <commit-ish>                # View single commit diff
 npx reviewit <commit-ish> [compare-with] # Compare two commits/branches
+npx reviewit --pr <github-pr-url>        # Review GitHub pull request
 ```
 
 ### Single commit review
@@ -65,16 +61,29 @@ npx reviewit working  # Unstaged changes only (cannot use compare-with)
 | `staged`  | Shows staged changes ready to be committed             | ✅ Yes               |
 | `working` | Shows unstaged changes in your working directory       | ❌ No                |
 
-### ⚙️ CLI Options
+### GitHub PR
 
-| Flag             | Default      | Description                                                         |
-| ---------------- | ------------ | ------------------------------------------------------------------- |
-| `<commit-ish>`   | HEAD         | Any Git reference: hash, tag, HEAD~n, branch, or Special Arguments  |
-| `[compare-with]` | (optional)   | Optional second commit to compare with (shows diff between the two) |
-| `--port`         | auto         | Preferred port; falls back if occupied                              |
-| `--no-open`      | false        | Don't automatically open browser                                    |
-| `--mode`         | side-by-side | Diff mode: `inline` or `side-by-side`                               |
-| `--tui`          | false        | Use terminal UI mode instead of web interface                       |
+```bash
+npx reviewit --pr https://github.com/owner/repo/pull/123
+```
+
+ReviewIt automatically handles GitHub authentication using:
+
+1. **GitHub CLI** (recommended): If you're logged in with `gh auth login`, ReviewIt uses your existing credentials
+2. **Environment Variable**: Set `GITHUB_TOKEN` environment variable
+3. **No Authentication**: Public repositories work without authentication (rate-limited)
+
+## ⚙️ CLI Options
+
+| Flag             | Default      | Description                                                            |
+| ---------------- | ------------ | ---------------------------------------------------------------------- |
+| `<commit-ish>`   | HEAD         | Any Git reference: hash, tag, HEAD~n, branch, or Special Arguments     |
+| `[compare-with]` | (optional)   | Optional second commit to compare with (shows diff between the two)    |
+| `--pr <url>`     | -            | GitHub PR URL to review (e.g., https://github.com/owner/repo/pull/123) |
+| `--port`         | auto         | Preferred port; falls back if occupied                                 |
+| `--no-open`      | false        | Don't automatically open browser                                       |
+| `--mode`         | side-by-side | Diff mode: `inline` or `side-by-side`                                  |
+| `--tui`          | false        | Use terminal UI mode instead of web interface                          |
 
 ## 💬 Comment System
 
@@ -88,10 +97,9 @@ ReviewIt includes an inline commenting system that integrates with Claude Code:
 
 ### Comment Prompt Format
 
-```
-File: src/components/Button.tsx
-Line: 42
-Comment: This function name should probably be more specific
+```sh
+src/components/Button.tsx:42 # Automatically added this line
+This name should probably be more specific.
 ```
 
 ## 🎨 Syntax Highlighting
@@ -150,19 +158,13 @@ pnpm run typecheck
 
 - **CLI**: Commander.js for argument parsing with comprehensive validation
 - **Backend**: Express server with simple-git for diff processing
+- **GitHub Integration**: Octokit for GitHub API with automatic authentication (GitHub CLI + env vars)
 - **Frontend**: React 18 + TypeScript + Vite
 - **Styling**: Tailwind CSS v4 with GitHub-like dark theme
 - **Syntax Highlighting**: Prism.js with dynamic language loading
 - **Testing**: Vitest for unit tests with co-located test files
 - **Quality**: ESLint, Prettier, lefthook pre-commit hooks
 
-### Key Components
-
-- **Validation System**: Unified validation logic for CLI arguments with comprehensive error handling
-- **Dual Parameter System**: Internal refactoring splits commitish into targetCommitish and baseCommitish for flexibility
-- **Special Argument Support**: Working directory, staging area, and uncommitted changes detection
-- **Hash Utilities**: Consistent short hash generation for commit display
-
 ## 📋 Requirements
 
 - Node.js ≥ 21.0.0

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import React from 'react';
 import pkg from '../../package.json' with { type: 'json' };
 import { startServer } from '../server/server.js';
-import { validateDiffArguments } from './utils.js';
+import { validateDiffArguments, resolvePrCommits } from './utils.js';
 function isSpecialArg(arg) {
     return arg === 'working' || arg === 'staged' || arg === '.';
 }
@@ -18,18 +18,42 @@ program
     .option('--no-open', 'do not automatically open browser')
     .option('--mode <mode>', 'diff mode (inline only for now)', 'inline')
     .option('--tui', 'use terminal UI instead of web interface')
+    .option('--pr <url>', 'GitHub PR URL to review (e.g., https://github.com/owner/repo/pull/123)')
     .action(async (commitish, compareWith, options) => {
     try {
         // Determine target and base commitish
         let targetCommitish = commitish;
         let baseCommitish;
-        if (compareWith) {
+        // Handle PR URL option
+        if (options.pr) {
+            if (commitish !== 'HEAD' || compareWith) {
+                console.error('Error: --pr option cannot be used with positional arguments');
+                process.exit(1);
+            }
+            try {
+                const prCommits = await resolvePrCommits(options.pr);
+                targetCommitish = prCommits.targetCommitish;
+                baseCommitish = prCommits.baseCommitish;
+                console.log(`📋 Reviewing PR: ${options.pr}`);
+                console.log(`🎯 Target commit: ${targetCommitish.substring(0, 7)}`);
+                console.log(`📍 Base commit: ${baseCommitish.substring(0, 7)}`);
+            }
+            catch (error) {
+                console.error(`Error resolving PR: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                process.exit(1);
+            }
+        }
+        else if (compareWith) {
             // If compareWith is provided, use it as base
             baseCommitish = compareWith;
         }
         else {
             // Handle special arguments
-            if (isSpecialArg(commitish)) {
+            if (commitish === 'working') {
+                // working compares working directory with staging area
+                baseCommitish = 'staged';
+            }
+            else if (isSpecialArg(commitish)) {
                 baseCommitish = 'HEAD';
             }
             else {
@@ -49,10 +73,13 @@ program
             render(React.createElement(TuiApp, { targetCommitish, baseCommitish }));
             return;
         }
-        const validation = validateDiffArguments(targetCommitish, compareWith);
-        if (!validation.valid) {
-            console.error(`Error: ${validation.error}`);
-            process.exit(1);
+        // Skip validation for PR URLs as they're already resolved to valid commits
+        if (!options.pr) {
+            const validation = validateDiffArguments(targetCommitish, compareWith);
+            if (!validation.valid) {
+                console.error(`Error: ${validation.error}`);
+                process.exit(1);
+            }
         }
         const { url, port } = await startServer({
             targetCommitish,

package/dist/cli/utils.d.ts

@@ -1,6 +1,27 @@
 export declare function validateCommitish(commitish: string): boolean;
 export declare function shortHash(hash: string): string;
 export declare function createCommitRangeString(baseHash: string, targetHash: string): string;
+export interface PullRequestInfo {
+    owner: string;
+    repo: string;
+    pullNumber: number;
+}
+export interface PullRequestDetails {
+    baseSha: string;
+    headSha: string;
+    baseRef: string;
+    headRef: string;
+}
+export declare function parseGitHubPrUrl(url: string): PullRequestInfo | null;
+export declare function fetchPrDetails(prInfo: PullRequestInfo): Promise<PullRequestDetails>;
+export declare function resolveCommitInLocalRepo(sha: string, context?: {
+    owner: string;
+    repo: string;
+}): string;
+export declare function resolvePrCommits(prUrl: string): Promise<{
+    targetCommitish: string;
+    baseCommitish: string;
+}>;
 export declare function validateDiffArguments(targetCommitish: string, baseCommitish?: string): {
     valid: boolean;
     error?: string;

package/dist/cli/utils.js

@@ -23,9 +23,117 @@ export function validateCommitish(commitish) {
 export function shortHash(hash) {
     return hash.substring(0, 7);
 }
+import { execSync } from 'child_process';
+import { Octokit } from '@octokit/rest';
 export function createCommitRangeString(baseHash, targetHash) {
     return `${baseHash}...${targetHash}`;
 }
+export function parseGitHubPrUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        if (urlObj.hostname !== 'github.com') {
+            return null;
+        }
+        const pathParts = urlObj.pathname.split('/').filter(Boolean);
+        if (pathParts.length < 4 || pathParts[2] !== 'pull') {
+            return null;
+        }
+        const owner = pathParts[0];
+        const repo = pathParts[1];
+        const pullNumber = parseInt(pathParts[3], 10);
+        if (isNaN(pullNumber)) {
+            return null;
+        }
+        return { owner, repo, pullNumber };
+    }
+    catch {
+        return null;
+    }
+}
+function getGitHubToken() {
+    // Try to get token from environment variable first
+    if (process.env.GITHUB_TOKEN) {
+        return process.env.GITHUB_TOKEN;
+    }
+    // Try to get token from GitHub CLI
+    try {
+        const result = execSync('gh auth token', { encoding: 'utf8', stdio: 'pipe' });
+        return result.trim();
+    }
+    catch {
+        // GitHub CLI not available or not authenticated
+        return undefined;
+    }
+}
+export async function fetchPrDetails(prInfo) {
+    const token = getGitHubToken();
+    const octokit = new Octokit({
+        auth: token,
+    });
+    try {
+        const { data: pr } = await octokit.rest.pulls.get({
+            owner: prInfo.owner,
+            repo: prInfo.repo,
+            pull_number: prInfo.pullNumber,
+        });
+        return {
+            baseSha: pr.base.sha,
+            headSha: pr.head.sha,
+            baseRef: pr.base.ref,
+            headRef: pr.head.ref,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            const authHint = token
+                ? ''
+                : ' (Try: gh auth login or set GITHUB_TOKEN environment variable)';
+            throw new Error(`Failed to fetch PR details: ${error.message}${authHint}`);
+        }
+        throw new Error('Failed to fetch PR details: Unknown error');
+    }
+}
+export function resolveCommitInLocalRepo(sha, context) {
+    try {
+        // Verify if the commit exists locally
+        execSync(`git cat-file -e ${sha}`, { stdio: 'ignore' });
+        return sha;
+    }
+    catch {
+        // If commit doesn't exist, try to fetch from remote
+        try {
+            execSync('git fetch origin', { stdio: 'ignore' });
+            execSync(`git cat-file -e ${sha}`, { stdio: 'ignore' });
+            return sha;
+        }
+        catch {
+            const errorMessage = [
+                `Commit ${sha} not found in local repository.`,
+                '',
+                'Common causes:',
+                '  • Are you running this command in the correct repository directory?',
+                context ? `    • Expected repository: ${context.owner}/${context.repo}` : '',
+                '  • Is this PR from a fork?',
+                '    • Try: git remote add upstream <original-repo-url> && git fetch upstream',
+                '    • Try: git fetch --all to fetch from all remotes',
+            ]
+                .filter(Boolean)
+                .join('\n');
+            throw new Error(errorMessage);
+        }
+    }
+}
+export async function resolvePrCommits(prUrl) {
+    const prInfo = parseGitHubPrUrl(prUrl);
+    if (!prInfo) {
+        throw new Error('Invalid GitHub PR URL format. Expected: https://github.com/owner/repo/pull/123');
+    }
+    const prDetails = await fetchPrDetails(prInfo);
+    const context = { owner: prInfo.owner, repo: prInfo.repo };
+    const targetCommitish = resolveCommitInLocalRepo(prDetails.headSha, context);
+    const baseCommitish = resolveCommitInLocalRepo(prDetails.baseSha, context);
+    return { targetCommitish, baseCommitish };
+}
 export function validateDiffArguments(targetCommitish, baseCommitish) {
     // Validate target commitish format
     if (!validateCommitish(targetCommitish)) {
@@ -35,20 +143,26 @@ export function validateDiffArguments(targetCommitish, baseCommitish) {
     if (baseCommitish !== undefined && !validateCommitish(baseCommitish)) {
         return { valid: false, error: 'Invalid base commit-ish format' };
     }
-    // Special arguments are only allowed in target, not base
+    // Special arguments are only allowed in target, not base (except staged with working)
     const specialArgs = ['working', 'staged', '.'];
     if (baseCommitish && specialArgs.includes(baseCommitish)) {
-        return {
-            valid: false,
-            error: `Special arguments (working, staged, .) are only allowed as target, not base. Got base: ${baseCommitish}`,
-        };
+        // Allow 'staged' as base only when target is 'working'
+        if (baseCommitish === 'staged' && targetCommitish === 'working') {
+            // This is valid: working vs staged
+        }
+        else {
+            return {
+                valid: false,
+                error: `Special arguments (working, staged, .) are only allowed as target, not base. Got base: ${baseCommitish}`,
+            };
+        }
     }
     // Cannot compare same values
     if (targetCommitish === baseCommitish) {
         return { valid: false, error: `Cannot compare ${targetCommitish} with itself` };
     }
-    // "working" shows unstaged changes and cannot be compared with another commit
-    if (targetCommitish === 'working' && baseCommitish) {
+    // "working" shows unstaged changes and can only be compared with staging area
+    if (targetCommitish === 'working' && baseCommitish && baseCommitish !== 'staged') {
         return {
             valid: false,
             error: '"working" shows unstaged changes and cannot be compared with another commit. Use "." instead to compare all uncommitted changes with a specific commit.',

package/dist/cli/utils.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateCommitish, validateDiffArguments, shortHash } from './utils';
+import { validateCommitish, validateDiffArguments, shortHash, parseGitHubPrUrl } from './utils';
 describe('CLI Utils', () => {
     describe('validateCommitish', () => {
         it('should validate full SHA hashes', () => {
@@ -73,6 +73,12 @@ describe('CLI Utils', () => {
                 expect(validateDiffArguments('staged', 'HEAD')).toEqual({ valid: true });
                 expect(validateDiffArguments('.', 'main')).toEqual({ valid: true });
             });
+            it('should allow staged as base only with working target', () => {
+                expect(validateDiffArguments('working', 'staged')).toEqual({ valid: true });
+                const result = validateDiffArguments('HEAD', 'staged');
+                expect(result.valid).toBe(false);
+                expect(result.error).toBe('Special arguments (working, staged, .) are only allowed as target, not base. Got base: staged');
+            });
         });
         describe('same value comparison', () => {
             it('should reject same target and base values', () => {
@@ -97,6 +103,17 @@ describe('CLI Utils', () => {
             it('should allow working without compareWith', () => {
                 expect(validateDiffArguments('working')).toEqual({ valid: true });
             });
+            it('should allow working with staged', () => {
+                expect(validateDiffArguments('working', 'staged')).toEqual({ valid: true });
+            });
+            it('should reject working with other commits', () => {
+                const result1 = validateDiffArguments('working', 'main');
+                expect(result1.valid).toBe(false);
+                expect(result1.error).toBe('"working" shows unstaged changes and cannot be compared with another commit. Use "." instead to compare all uncommitted changes with a specific commit.');
+                const result2 = validateDiffArguments('working', 'abc123');
+                expect(result2.valid).toBe(false);
+                expect(result2.error).toBe('"working" shows unstaged changes and cannot be compared with another commit. Use "." instead to compare all uncommitted changes with a specific commit.');
+            });
             it('should allow other special args with compareWith', () => {
                 expect(validateDiffArguments('staged', 'HEAD')).toEqual({ valid: true });
                 expect(validateDiffArguments('.', 'main')).toEqual({ valid: true });
@@ -127,4 +144,51 @@ describe('CLI Utils', () => {
             expect(shortHash('')).toBe('');
         });
     });
+    describe('parseGitHubPrUrl', () => {
+        it('should parse valid GitHub PR URLs', () => {
+            const result = parseGitHubPrUrl('https://github.com/owner/repo/pull/123');
+            expect(result).toEqual({
+                owner: 'owner',
+                repo: 'repo',
+                pullNumber: 123,
+            });
+        });
+        it('should parse GitHub PR URLs with additional path segments', () => {
+            const result = parseGitHubPrUrl('https://github.com/owner/repo/pull/456/files');
+            expect(result).toEqual({
+                owner: 'owner',
+                repo: 'repo',
+                pullNumber: 456,
+            });
+        });
+        it('should parse GitHub PR URLs with query parameters', () => {
+            const result = parseGitHubPrUrl('https://github.com/owner/repo/pull/789?tab=files');
+            expect(result).toEqual({
+                owner: 'owner',
+                repo: 'repo',
+                pullNumber: 789,
+            });
+        });
+        it('should handle URLs with hyphens and underscores in owner/repo names', () => {
+            const result = parseGitHubPrUrl('https://github.com/owner-name/repo_name/pull/123');
+            expect(result).toEqual({
+                owner: 'owner-name',
+                repo: 'repo_name',
+                pullNumber: 123,
+            });
+        });
+        it('should return null for invalid URLs', () => {
+            expect(parseGitHubPrUrl('not-a-url')).toBe(null);
+            expect(parseGitHubPrUrl('https://example.com/owner/repo/pull/123')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com/owner/repo/issues/123')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com/owner/repo')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com/owner/repo/pull/abc')).toBe(null);
+        });
+        it('should handle malformed URLs gracefully', () => {
+            expect(parseGitHubPrUrl('')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com/owner')).toBe(null);
+            expect(parseGitHubPrUrl('https://github.com/owner/repo/pull')).toBe(null);
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "difit",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "A lightweight command-line tool that spins up a local web server to display Git commit diffs in a GitHub-like Files changed view",
   "type": "module",
   "engines": {
@@ -34,6 +34,7 @@
     "prepublishOnly": "NODE_ENV=production pnpm run build"
   },
   "dependencies": {
+    "@octokit/rest": "^22.0.0",
     "commander": "^14.0.0",
     "express": "^5.1.0",
     "ink": "^6.0.1",