cadr-cli 0.0.1 → 1.9.2

package/src/git.ts

@@ -14,6 +14,15 @@ export class GitError extends Error {
   }
 }
 
+/**
+ * Options for specifying what diff to analyze
+ */
+export interface DiffOptions {
+  mode: 'staged' | 'all' | 'branch-diff';
+  base?: string;  // For branch-diff: base git reference (e.g., 'origin/main')
+  head?: string;  // For branch-diff: head git reference (e.g., 'HEAD')
+}
+
 /**
  * Retrieves the list of staged files in the current Git repository
  * @returns Promise<string[]> Array of staged file paths
@@ -58,3 +67,234 @@ export async function getStagedFiles(): Promise<string[]> {
     );
   }
 }
+
+/**
+ * Retrieves the full diff content for staged files
+ * Uses minimal context to reduce token usage
+ * @returns Promise<string> Full diff content of staged changes
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getStagedDiff(): Promise<string> {
+  try {
+    // Use --unified=1 for minimal context (1 line before/after instead of 3)
+    // This significantly reduces token usage while maintaining readability
+    const { stdout } = await execAsync('git diff --cached --unified=1');
+    return stdout;
+  } catch (error: unknown) {
+    // Handle different Git error scenarios (same as getStagedFiles)
+    const errorWithCode = error as { code?: number };
+    
+    if (errorWithCode.code === 128) {
+      throw new GitError(
+        'Not in a Git repository. Please run \'cadr\' from within a Git repository.',
+        'NOT_GIT_REPO',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    if (errorWithCode.code === 127) {
+      throw new GitError(
+        'Git is not installed. Please install Git and try again.',
+        'GIT_NOT_FOUND',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    // Handle other Git errors (permissions, corruption, etc.)
+    throw new GitError(
+      'Unable to read Git repository. Please check repository permissions.',
+      'GIT_ERROR',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+}
+
+/**
+ * Retrieves the list of all uncommitted files (staged + unstaged) in the current Git repository
+ * @returns Promise<string[]> Array of uncommitted file paths
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getUncommittedFiles(): Promise<string[]> {
+  try {
+    const { stdout } = await execAsync('git diff HEAD --name-only');
+    
+    // Split by newlines and filter out empty strings
+    const uncommittedFiles = stdout
+      .split('\n')
+      .map(file => file.trim())
+      .filter(file => file.length > 0);
+    
+    return uncommittedFiles;
+  } catch (error: unknown) {
+    // Handle different Git error scenarios
+    const errorWithCode = error as { code?: number };
+    
+    if (errorWithCode.code === 128) {
+      throw new GitError(
+        'Not in a Git repository. Please run \'cadr\' from within a Git repository.',
+        'NOT_GIT_REPO',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    if (errorWithCode.code === 127) {
+      throw new GitError(
+        'Git is not installed. Please install Git and try again.',
+        'GIT_NOT_FOUND',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    // Handle other Git errors (permissions, corruption, etc.)
+    throw new GitError(
+      'Unable to read Git repository. Please check repository permissions.',
+      'GIT_ERROR',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+}
+
+/**
+ * Retrieves the full diff content for all uncommitted files (staged + unstaged)
+ * Uses minimal context to reduce token usage
+ * @returns Promise<string> Full diff content of uncommitted changes
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getUncommittedDiff(): Promise<string> {
+  try {
+    // Use --unified=1 for minimal context (1 line before/after instead of 3)
+    // This significantly reduces token usage while maintaining readability
+    const { stdout } = await execAsync('git diff HEAD --unified=1');
+    return stdout;
+  } catch (error: unknown) {
+    // Handle different Git error scenarios (same as getUncommittedFiles)
+    const errorWithCode = error as { code?: number };
+    
+    if (errorWithCode.code === 128) {
+      throw new GitError(
+        'Not in a Git repository. Please run \'cadr\' from within a Git repository.',
+        'NOT_GIT_REPO',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    if (errorWithCode.code === 127) {
+      throw new GitError(
+        'Git is not installed. Please install Git and try again.',
+        'GIT_NOT_FOUND',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    // Handle other Git errors (permissions, corruption, etc.)
+    throw new GitError(
+      'Unable to read Git repository. Please check repository permissions.',
+      'GIT_ERROR',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+}
+
+/**
+ * Generic function to get changed files based on diff options
+ * @param options - Diff options specifying which changes to analyze
+ * @returns Promise<string[]> Array of changed file paths
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getChangedFiles(options: DiffOptions = { mode: 'all' }): Promise<string[]> {
+  switch (options.mode) {
+    case 'staged':
+      return getStagedFiles();
+    case 'all':
+      return getUncommittedFiles();
+    case 'branch-diff': {
+      const base = options.base || 'origin/main';
+      const head = options.head || 'HEAD';
+      try {
+        // Use triple-dot syntax for merge-base diff (standard in CI/CD)
+        const { stdout } = await execAsync(`git diff ${base}...${head} --name-only`);
+        
+        const files = stdout
+          .split('\n')
+          .map(file => file.trim())
+          .filter(file => file.length > 0);
+        
+        return files;
+      } catch (error: unknown) {
+        // Handle different Git error scenarios
+        const errorWithCode = error as { code?: number };
+        
+        if (errorWithCode.code === 128) {
+          throw new GitError(
+            `Invalid git references: ${base}...${head}. Please ensure both references exist.`,
+            'GIT_ERROR',
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+        
+        if (errorWithCode.code === 127) {
+          throw new GitError(
+            'Git is not installed. Please install Git and try again.',
+            'GIT_NOT_FOUND',
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+        
+        throw new GitError(
+          'Unable to read Git repository. Please check repository permissions.',
+          'GIT_ERROR',
+          error instanceof Error ? error : new Error(String(error))
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Generic function to get diff content based on diff options
+ * @param options - Diff options specifying which changes to analyze
+ * @returns Promise<string> Full diff content
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getDiff(options: DiffOptions = { mode: 'all' }): Promise<string> {
+  switch (options.mode) {
+    case 'staged':
+      return getStagedDiff();
+    case 'all':
+      return getUncommittedDiff();
+    case 'branch-diff': {
+      const base = options.base || 'origin/main';
+      const head = options.head || 'HEAD';
+      try {
+        // Use triple-dot syntax for merge-base diff with minimal context
+        const { stdout } = await execAsync(`git diff ${base}...${head} --unified=1`);
+        return stdout;
+      } catch (error: unknown) {
+        // Handle different Git error scenarios
+        const errorWithCode = error as { code?: number };
+        
+        if (errorWithCode.code === 128) {
+          throw new GitError(
+            `Invalid git references: ${base}...${head}. Please ensure both references exist.`,
+            'GIT_ERROR',
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+        
+        if (errorWithCode.code === 127) {
+          throw new GitError(
+            'Git is not installed. Please install Git and try again.',
+            'GIT_NOT_FOUND',
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+        
+        throw new GitError(
+          'Unable to read Git repository. Please check repository permissions.',
+          'GIT_ERROR',
+          error instanceof Error ? error : new Error(String(error))
+        );
+      }
+    }
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,59 @@
+import { showHelp, showVersion } from './index';
+
+describe('CLI Help', () => {
+  let stdoutSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    stdoutSpy = jest.spyOn(process.stdout, 'write').mockImplementation();
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+  });
+
+  test('showHelp displays product name', () => {
+    showHelp();
+    expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('cADR'));
+  });
+
+  test('showHelp displays available commands', () => {
+    showHelp();
+    const output = stdoutSpy.mock.calls[0][0];
+    expect(output).toContain('init');
+    expect(output).toContain('analyze');
+    expect(output).toContain('help');
+  });
+
+  test('showHelp displays usage examples', () => {
+    showHelp();
+    const output = stdoutSpy.mock.calls[0][0];
+    expect(output).toContain('USAGE');
+    expect(output).toContain('COMMANDS');
+    expect(output).toContain('OPTIONS');
+    expect(output).toContain('EXAMPLES');
+  });
+
+  test('showHelp displays version info', () => {
+    showHelp();
+    const output = stdoutSpy.mock.calls[0][0];
+    expect(output).toContain('0.0.1');
+  });
+});
+
+describe('CLI Version', () => {
+  let stdoutSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    stdoutSpy = jest.spyOn(process.stdout, 'write').mockImplementation();
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+  });
+
+  test('showVersion displays version information', () => {
+    showVersion();
+    expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('cADR version'));
+    expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('0.0.1'));
+  });
+});

package/src/index.ts

@@ -1,80 +1,100 @@
-import { getStagedFiles, GitError } from './git';
-import { loggerInstance } from './logger';
+import { initCommand } from './commands/init';
+import { analyzeCommand } from './commands/analyze';
 
 // Version constants
 const CORE_VERSION = '0.0.1';
 const CLI_VERSION = '0.0.1';
 
-// Parse command line arguments
-const args = process.argv.slice(2);
-const isVerbose = args.includes('--verbose') || args.includes('-v');
+export function showHelp(): void {
+  const help = `
+cADR - Continuous Architectural Decision Records
+Version: ${CLI_VERSION}
 
-export function getWelcomeMessage(): string {
-  return `🎉 Hello, cADR!
+USAGE
+  cadr [command] [options]
 
-cADR (Continuous Architectural Decision Records) helps you automatically
-capture and document architectural decisions as you code.
+COMMANDS
+  init              Create a cadr.yaml configuration file
+  analyze           Analyze code changes and generate ADRs (default)
+  help              Show this help message
 
-Version: ${CLI_VERSION}
-Core: ${CORE_VERSION}
-Learn more: https://github.com/YotpoLtd/cADR
+ANALYZE OPTIONS
+  --all             Analyze all uncommitted changes (staged + unstaged) [default]
+  --staged          Analyze only staged changes
+  --base <ref>      Base git reference for CI/CD (e.g., origin/main)
+  --head <ref>      Head git reference for CI/CD (default: HEAD)
+
+GLOBAL OPTIONS
+  -h, --help        Show help message
+  -v, --version     Show version information
+  --verbose         Enable verbose logging
 
-Get started by running 'cadr --verbose' to see detailed logs
+EXAMPLES
+  # Local development
+  cadr                                # Analyze all uncommitted files (default)
+  cadr analyze                        # Analyze all uncommitted files
+  cadr analyze --staged               # Analyze only staged files
+  cadr analyze --all                  # Analyze all uncommitted files (explicit)
+  
+  # CI/CD (Pull Requests)
+  cadr analyze --base origin/main     # Compare current HEAD to main
+  cadr analyze --base origin/main --head feature-branch
+  cadr analyze --base HEAD~1          # Compare to previous commit
+  
+  # Other commands
+  cadr init                           # Initialize configuration
+  cadr --verbose analyze              # Analyze with debug logs
+
+LEARN MORE
+  GitHub: https://github.com/YotpoLtd/cADR
+  Docs:   https://github.com/YotpoLtd/cADR#readme
 `;
+  process.stdout.write(help);
 }
 
-export function displayWelcome(): void {
-  // Use process.stdout.write instead of console.log (Constitution: no console.log)
-  process.stdout.write(getWelcomeMessage());
+export function showVersion(): void {
+  process.stdout.write(`cADR version ${CLI_VERSION} (core: ${CORE_VERSION})\n`);
 }
 
-export async function processStagedFiles(): Promise<void> {
-  try {
-    const stagedFiles = await getStagedFiles();
-    
-    // Display staged files to user
-    if (stagedFiles.length > 0) {
-      process.stdout.write(`\n📁 Found ${stagedFiles.length} staged file${stagedFiles.length === 1 ? '' : 's'}:\n`);
-      stagedFiles.forEach((file: string) => {
-        process.stdout.write(`  • ${file}\n`);
-      });
-    } else {
-      process.stdout.write(`\n📁 No staged files found.\n`);
-    }
-    
-    // Only log for debugging when verbose mode is enabled
-    if (isVerbose) {
-      loggerInstance.info('Retrieved staged files', {
-        staged_files: stagedFiles,
-        count: stagedFiles.length
-      });
-    }
-  } catch (error: unknown) {
-    if (error instanceof GitError) {
-      // Display helpful error message to stdout
-      process.stdout.write(`\n❌ ${error.message}\n`);
-      process.exit(1);
-    } else {
-      // Log unexpected errors (always show errors)
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      loggerInstance.error('Unexpected error occurred', { 
-        error: errorMessage
-      });
-      process.exit(1);
-    }
-  }
-}
 
 // Main execution block - run when module is executed directly
 if (require.main === module) {
-  // Display welcome message first
-  displayWelcome();
+  const args = process.argv.slice(2);
+  const command = args[0];
   
-  // Then process staged files
-  processStagedFiles().catch((error) => {
-    loggerInstance.error('Failed to process staged files', { 
-      error: error instanceof Error ? error.message : String(error)
-    });
+  // Handle commands
+  (async () => {
+    // Help flags
+    if (!command || command === 'help' || args.includes('--help') || args.includes('-h')) {
+      showHelp();
+      return;
+    }
+    
+    // Version flag
+    if (args.includes('--version')) {
+      showVersion();
+      return;
+    }
+    
+    // Commands
+    switch (command) {
+      case 'init':
+        await initCommand();
+        break;
+        
+      case 'analyze':
+        await analyzeCommand(args);
+        break;
+        
+      default:
+        // Unknown command - show error and help
+        process.stdout.write(`\n❌ Unknown command: ${command}\n`);
+        showHelp();
+        process.exit(1);
+    }
+  })().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error('Error:', error.message || error);
     process.exit(1);
   });
-}
+}