difit 1.1.0 → 1.1.2

package/README.md

@@ -18,59 +18,64 @@ A lightweight command-line tool that spins up a local web server to display Git
 - 🎨 **Syntax Highlighting**: Dynamic language loading for Bash, PHP, SQL, Ruby, Java, and more
 - ✨ **100% vibe coding**: Built with pure coding energy and good vibes
 
-## 📦 Installation
+## ⚡ Quick Start
 
 ```bash
-# use npx (no installation needed)
-npx reviewit <commit-ish>
-
-# or Global install
-npm install -g reviewit
+npx reviewit    # View HEAD commit changes in a beautiful diff viewer
 ```
 
 ## 🚀 Usage
 
+### Basic Usage
+
 ```bash
-# default: HEAD commit changes
-npx reviewit
+npx reviewit <commit-ish>                # View single commit diff
+npx reviewit <commit-ish> [compare-with] # Compare two commits/branches
+```
 
-# Review a specific commit changes
-npx reviewit 6f4a9b7
-npx reviewit HEAD^
-npx reviewit HEAD~3
+### Single commit review
 
-# Special Arguments
-npx reviewit staging  # staging area changes
-npx reviewit working  # working directory changes
-npx reviewit .        # uncommited all changes
+```bash
+npx reviewit 6f4a9b7  # Specific commit
+npx reviewit HEAD^    # Previous commit
+npx reviewit feature  # Latest commit on branch
+```
 
-# Custom port, don't auto-open browser
-npx reviewit 6f4a9b7 --port 4300 --no-open
+### Compare two commits
 
-# Terminal UI mode (no browser)
-npx reviewit --tui
-npx reviewit working --tui
+```bash
+npx reviewit HEAD main      # Compare HEAD with main branch
+npx reviewit feature main   # Compare branches
+npx reviewit . origin/main  # Compare working directory with remote main
 ```
 
-### ⚙️ CLI Options
+### Special Arguments
 
-| Flag           | Default      | Description                                                        |
-| -------------- | ------------ | ------------------------------------------------------------------ |
-| `<commit-ish>` | (required)   | Any Git reference: hash, tag, HEAD~n, branch, or Special Arguments |
-| `--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                      |
+ReviewIt supports special keywords for common diff scenarios:
 
-### 🔑 Special Arguments
+```bash
+npx reviewit          # HEAD commit changes
+npx reviewit .        # All uncommitted changes (staged + unstaged)
+npx reviewit staged   # Staged changes ready for commit
+npx reviewit working  # Unstaged changes only (cannot use compare-with)
+```
 
-ReviewIt supports special arguments for common diff scenarios:
+| Keyword   | Description                                            | Compare-with Support |
+| --------- | ------------------------------------------------------ | -------------------- |
+| `.`       | Shows all uncommitted changes (both staged & unstaged) | ✅ Yes               |
+| `staged`  | Shows staged changes ready to be committed             | ✅ Yes               |
+| `working` | Shows unstaged changes in your working directory       | ❌ No                |
+
+### ⚙️ CLI Options
 
-| Keyword   | Description                                            |
-| --------- | ------------------------------------------------------ |
-| `working` | Shows unstaged changes in your working directory       |
-| `staged`  | Shows staged changes ready to be committed             |
-| `.`       | Shows all uncommitted changes (both staged & unstaged) |
+| 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                       |
 
 ## 💬 Comment System
 
@@ -118,15 +123,10 @@ pnpm install
 
 # Start development server (with hot reload)
 # This runs both Vite dev server and CLI with NODE_ENV=development
-pnpm run dev                    # defaults to HEAD
-pnpm run dev HEAD~3            # review HEAD~3
-pnpm run dev main              # review main branch
-
-# For development CLI only (connects to separate Vite server)
-pnpm run dev:cli <commit-ish>
+pnpm run dev
 
 # Build and start production server
-pnpm run start HEAD
+pnpm run start <commit-ish>
 
 # Build for production
 pnpm run build
@@ -143,20 +143,27 @@ pnpm run typecheck
 ### Development Workflow
 
 - **`pnpm run dev`**: Starts both Vite dev server (with hot reload) and CLI server simultaneously
-- **`pnpm run start <commit>`**: Builds everything and starts production server (for testing final build)
+- **`pnpm run start <commit-ish>`**: Builds everything and starts production server (for testing final build)
 - **Development mode**: Uses Vite's dev server for hot reload and fast development
 - **Production mode**: Serves built static files (used by npx and production builds)
 
 ## 🏗️ Architecture
 
-- **CLI**: Commander.js for argument parsing
+- **CLI**: Commander.js for argument parsing with comprehensive validation
 - **Backend**: Express server with simple-git for diff processing
 - **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
+- **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 ≥ 18.0.0

package/dist/cli/index.js

@@ -3,30 +3,38 @@ import { Command } from 'commander';
 import React from 'react';
 import pkg from '../../package.json' with { type: 'json' };
 import { startServer } from '../server/server.js';
-import { validateCommitish } from './utils.js';
+import { validateDiffArguments } from './utils.js';
+function isSpecialArg(arg) {
+    return arg === 'working' || arg === 'staged' || arg === '.';
+}
 const program = new Command();
 program
     .name('reviewit')
     .description('A lightweight Git diff viewer with GitHub-like interface')
     .version(pkg.version)
     .argument('[commit-ish]', 'Git commit, tag, branch, HEAD~n reference, or "working"/"staged"/"." (default: HEAD)', 'HEAD')
+    .argument('[compare-with]', 'Optional: Compare with this commit/branch (shows diff between commit-ish and compare-with)')
     .option('--port <port>', 'preferred port (auto-assigned if occupied)', parseInt)
     .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')
-    .action(async (commitish, options) => {
+    .action(async (commitish, compareWith, options) => {
     try {
-        // Determine what to show
+        // Determine target and base commitish
         let targetCommitish = commitish;
-        // Handle special arguments
-        if (commitish === 'working') {
-            targetCommitish = 'working';
+        let baseCommitish;
+        if (compareWith) {
+            // If compareWith is provided, use it as base
+            baseCommitish = compareWith;
         }
-        else if (commitish === 'staged') {
-            targetCommitish = 'staged';
-        }
-        else if (commitish === '.') {
-            targetCommitish = '.';
+        else {
+            // Handle special arguments
+            if (isSpecialArg(commitish)) {
+                baseCommitish = 'HEAD';
+            }
+            else {
+                baseCommitish = commitish + '^';
+            }
         }
         if (options.tui) {
             // Check if we're in a TTY environment
@@ -38,15 +46,17 @@ program
             // Dynamic import for TUI mode
             const { render } = await import('ink');
             const { default: TuiApp } = await import('../tui/App.js');
-            render(React.createElement(TuiApp, { commitish: targetCommitish }));
+            render(React.createElement(TuiApp, { targetCommitish, baseCommitish }));
             return;
         }
-        if (!validateCommitish(targetCommitish)) {
-            console.error('Error: Invalid commit-ish format');
+        const validation = validateDiffArguments(targetCommitish, compareWith);
+        if (!validation.valid) {
+            console.error(`Error: ${validation.error}`);
             process.exit(1);
         }
-        const { url } = await startServer({
-            commitish: targetCommitish,
+        const { url, port } = await startServer({
+            targetCommitish,
+            baseCommitish,
             preferredPort: options.port,
             openBrowser: options.open,
             mode: options.mode,
@@ -59,8 +69,21 @@ program
         else {
             console.log('💡 Use --open to automatically open browser\n');
         }
-        process.on('SIGINT', () => {
+        process.on('SIGINT', async () => {
             console.log('\n👋 Shutting down ReviewIt server...');
+            // Try to fetch comments before shutting down
+            try {
+                const response = await fetch(`http://localhost:${port}/api/comments-output`);
+                if (response.ok) {
+                    const data = await response.text();
+                    if (data.trim()) {
+                        console.log(data);
+                    }
+                }
+            }
+            catch {
+                // Silently ignore fetch errors during shutdown
+            }
             process.exit(0);
         });
     }

package/dist/cli/utils.d.ts

@@ -1 +1,6 @@
 export declare function validateCommitish(commitish: string): boolean;
+export declare function shortHash(hash: string): string;
+export declare function validateDiffArguments(targetCommitish: string, baseCommitish?: string): {
+    valid: boolean;
+    error?: string;
+};

package/dist/cli/utils.js

@@ -20,3 +20,36 @@ export function validateCommitish(commitish) {
     ];
     return validPatterns.some((pattern) => pattern.test(trimmed));
 }
+export function shortHash(hash) {
+    return hash.substring(0, 7);
+}
+export function validateDiffArguments(targetCommitish, baseCommitish) {
+    // Validate target commitish format
+    if (!validateCommitish(targetCommitish)) {
+        return { valid: false, error: 'Invalid target commit-ish format' };
+    }
+    // Validate base commitish format if provided
+    if (baseCommitish !== undefined && !validateCommitish(baseCommitish)) {
+        return { valid: false, error: 'Invalid base commit-ish format' };
+    }
+    // Special arguments are only allowed in target, not base
+    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}`,
+        };
+    }
+    // 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) {
+        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.',
+        };
+    }
+    return { valid: true };
+}

package/dist/cli/utils.test.js

@@ -1,23 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { validateCommitish, validateDiffArguments, shortHash, parseGitHubPrUrl } from './utils';
+import { validateCommitish, validateDiffArguments, shortHash } from './utils';
 describe('CLI Utils', () => {
     describe('validateCommitish', () => {
         it('should validate full SHA hashes', () => {
             expect(validateCommitish('a1b2c3d4e5f6789012345678901234567890abcd')).toBe(true);
             expect(validateCommitish('abc123')).toBe(true);
         });
-        it('should validate SHA hashes with parent references', () => {
-            expect(validateCommitish('a1b2c3d4e5f6789012345678901234567890abcd^')).toBe(true);
-            expect(validateCommitish('abc123^')).toBe(true);
-            expect(validateCommitish('abc123^^')).toBe(true);
-            expect(validateCommitish('bd4b7513e075b5b245284c38fd23427b9bd0f42e^')).toBe(true);
-        });
-        it('should validate SHA hashes with ancestor references', () => {
-            expect(validateCommitish('a1b2c3d4e5f6789012345678901234567890abcd~1')).toBe(true);
-            expect(validateCommitish('abc123~5')).toBe(true);
-            expect(validateCommitish('abc123~10')).toBe(true);
-            expect(validateCommitish('bd4b7513e075b5b245284c38fd23427b9bd0f42e~2')).toBe(true);
-        });
         it('should validate HEAD references', () => {
             expect(validateCommitish('HEAD')).toBe(true);
             expect(validateCommitish('HEAD~1')).toBe(true);
@@ -85,12 +73,6 @@ 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', () => {
@@ -115,17 +97,6 @@ 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 });
@@ -143,14 +114,6 @@ describe('CLI Utils', () => {
                     valid: true,
                 });
             });
-            it('should handle SHA hashes with parent/ancestor references', () => {
-                expect(validateDiffArguments('bd4b7513e075b5b245284c38fd23427b9bd0f42e^', 'abc123')).toEqual({ valid: true });
-                expect(validateDiffArguments('abc123', 'def456^')).toEqual({ valid: true });
-                expect(validateDiffArguments('abc123~1', 'def456~2')).toEqual({ valid: true });
-                expect(validateDiffArguments('a1b2c3d4e5f6789012345678901234567890abcd^', 'HEAD')).toEqual({
-                    valid: true,
-                });
-            });
         });
     });
     describe('shortHash', () => {
@@ -164,51 +127,4 @@ 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);
-        });
-    });
 });