qa360 2.1.7 → 2.2.1

package/core/src/generation/source-analyzer.ts

@@ -0,0 +1,830 @@
+/**
+ * QA360 Source Code Analyzer
+ *
+ * Analyzes source code to extract test requirements and generate test specifications.
+ * Supports TypeScript, JavaScript, Python, and Go source code.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new SourceAnalyzer();
+ * const spec = await analyzer.analyzeFile('./src/userService.ts');
+ * const tests = await analyzer.generateTests(spec);
+ * ```
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, extname, basename } from 'path';
+import type {
+  TestSpec,
+  UnitTestSpec,
+  ApiTestSpec,
+  GenerationSource,
+  ApiEndpoint
+} from './types.js';
+
+/**
+ * Analysis result for a source file
+ */
+export interface SourceAnalysis {
+  filePath: string;
+  language: 'typescript' | 'javascript' | 'python' | 'go';
+  exports: string[];
+  functions: FunctionInfo[];
+  classes: ClassInfo[];
+  imports: ImportInfo[];
+  hasTests: boolean;
+  testFilePath?: string;
+  complexity: number;
+  linesOfCode: number;
+}
+
+/**
+ * Function information
+ */
+export interface FunctionInfo {
+  name: string;
+  params: string[];
+  returnType?: string;
+  isAsync: boolean;
+  isPublic: boolean;
+  lineNumber: number;
+  complexity: number;
+}
+
+/**
+ * Class information
+ */
+export interface ClassInfo {
+  name: string;
+  methods: FunctionInfo[];
+  properties: string[];
+  extends?: string;
+  lineNumber: number;
+}
+
+/**
+ * Import information
+ */
+export interface ImportInfo {
+  module: string;
+  imports: string[];
+  isExternal: boolean;
+}
+
+/**
+ * Source analyzer options
+ */
+export interface SourceAnalyzerOptions {
+  /** Include private members in analysis */
+  includePrivate?: boolean;
+  /** Maximum complexity threshold */
+  maxComplexity?: number;
+  /** Exclude patterns */
+  exclude?: string[];
+  /** Follow imports for dependency analysis */
+  followImports?: boolean;
+}
+
+/**
+ * Test generation suggestion
+ */
+export interface TestSuggestion {
+  type: 'unit' | 'integration' | 'e2e';
+  priority: 'high' | 'medium' | 'low';
+  description: string;
+  functionName?: string;
+  assertions: string[];
+  mocks: string[];
+}
+
+/**
+ * Source Analyzer
+ *
+ * Analyzes source code to extract testable elements and suggest tests.
+ */
+export class SourceAnalyzer {
+  private readonly options: Required<SourceAnalyzerOptions>;
+
+  private readonly defaultOptions: Required<SourceAnalyzerOptions> = {
+    includePrivate: false,
+    maxComplexity: 10,
+    exclude: ['node_modules', 'dist', 'build', '.git', 'coverage'],
+    followImports: false
+  };
+
+  constructor(options: SourceAnalyzerOptions = {}) {
+    this.options = { ...this.defaultOptions, ...options };
+  }
+
+  /**
+   * Analyze a single source file
+   */
+  analyzeFile(filePath: string): SourceAnalysis {
+    if (!existsSync(filePath)) {
+      throw new Error(`Source file not found: ${filePath}`);
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const ext = extname(filePath);
+    const language = this.getLanguage(ext);
+
+    const analysis: SourceAnalysis = {
+      filePath,
+      language,
+      exports: [],
+      functions: [],
+      classes: [],
+      imports: [],
+      hasTests: false,
+      complexity: 0,
+      linesOfCode: content.split('\n').length
+    };
+
+    switch (language) {
+      case 'typescript':
+      case 'javascript':
+        this.analyzeTypeScriptScript(content, analysis);
+        break;
+      case 'python':
+        this.analyzePython(content, analysis);
+        break;
+      case 'go':
+        this.analyzeGo(content, analysis);
+        break;
+    }
+
+    // Calculate overall complexity
+    analysis.complexity = this.calculateComplexity(analysis);
+
+    // Check if test file exists
+    analysis.testFilePath = this.findTestFile(filePath);
+    analysis.hasTests = analysis.testFilePath !== undefined;
+
+    return analysis;
+  }
+
+  /**
+   * Analyze a directory recursively
+   */
+  analyzeDirectory(dirPath: string): SourceAnalysis[] {
+    const results: SourceAnalysis[] = [];
+
+    if (!existsSync(dirPath)) {
+      throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    this.traverseDirectory(dirPath, (filePath) => {
+      try {
+        const ext = extname(filePath);
+        if (this.isSourceFile(ext)) {
+          results.push(this.analyzeFile(filePath));
+        }
+      } catch (error) {
+        // Skip files that fail to analyze
+        console.warn(`Warning: Failed to analyze ${filePath}:`, error);
+      }
+    });
+
+    return results;
+  }
+
+  /**
+   * Generate test specification from analysis
+   */
+  generateSpec(analysis: SourceAnalysis): UnitTestSpec {
+    const functionsToTest = analysis.exports.filter(e => {
+      const fn = analysis.functions.find(f => f.name === e);
+      return fn && fn.isPublic && fn.complexity <= this.options.maxComplexity;
+    });
+
+    return {
+      type: 'unit',
+      name: this.generateTestName(analysis.filePath),
+      source: {
+        language: analysis.language,
+        filePath: analysis.filePath,
+        exports: functionsToTest
+      },
+      framework: this.recommendFramework(analysis.language)
+    };
+  }
+
+  /**
+   * Generate test suggestions
+   */
+  generateSuggestions(analysis: SourceAnalysis): TestSuggestion[] {
+    const suggestions: TestSuggestion[] = [];
+
+    // Suggest unit tests for each public function
+    for (const fn of analysis.functions) {
+      if (!fn.isPublic) continue;
+
+      const complexity = fn.complexity;
+      let priority: 'high' | 'medium' | 'low' = 'low';
+
+      if (complexity > this.options.maxComplexity) {
+        priority = 'high';
+      } else if (complexity > 5) {
+        priority = 'medium';
+      }
+
+      suggestions.push({
+        type: 'unit',
+        priority,
+        description: `Test function ${fn.name}`,
+        functionName: fn.name,
+        assertions: this.generateAssertions(fn),
+        mocks: this.generateMocks(fn, analysis.imports)
+      });
+    }
+
+    // Suggest integration tests for classes with multiple methods
+    for (const cls of analysis.classes) {
+      if (cls.methods.length >= 3) {
+        suggestions.push({
+          type: 'integration',
+          priority: 'medium',
+          description: `Test class ${cls.name} interactions`,
+          assertions: ['class instance created', 'methods work together'],
+          mocks: this.generateMocksForClass(cls, analysis.imports)
+        });
+      }
+    }
+
+    // Suggest E2E tests if external APIs are used
+    const hasExternalCalls = analysis.imports.some(i => i.isExternal && this.isHttpModule(i.module));
+    if (hasExternalCalls) {
+      suggestions.push({
+        type: 'e2e',
+        priority: 'low',
+        description: 'Test external API integrations',
+        assertions: ['API calls succeed', 'error handling works'],
+        mocks: []
+      });
+    }
+
+    return suggestions.sort((a, b) => {
+      const priorityOrder = { high: 0, medium: 1, low: 2 };
+      return priorityOrder[a.priority] - priorityOrder[b.priority];
+    });
+  }
+
+  /**
+   * Generate API spec from Express/HTTP handlers
+   */
+  generateApiSpec(analysis: SourceAnalysis): ApiTestSpec | null {
+    const endpoints: ApiEndpoint[] = [];
+    const baseUrl = this.extractBaseUrl(analysis);
+
+    for (const fn of analysis.functions) {
+      const endpoint = this.extractEndpoint(fn, analysis);
+      if (endpoint) {
+        endpoints.push(endpoint);
+      }
+    }
+
+    for (const cls of analysis.classes) {
+      for (const method of cls.methods) {
+        const endpoint = this.extractEndpoint(method, analysis);
+        if (endpoint) {
+          endpoints.push(endpoint);
+        }
+      }
+    }
+
+    if (endpoints.length === 0) {
+      return null;
+    }
+
+    return {
+      type: 'api',
+      name: `${basename(analysis.filePath)} API`,
+      baseUrl,
+      endpoints
+    };
+  }
+
+  /**
+   * Analyze TypeScript/JavaScript code
+   */
+  private analyzeTypeScriptScript(content: string, analysis: SourceAnalysis): void {
+    const lines = content.split('\n');
+
+    // Extract exports
+    const exportRegex = /export\s+(?:async\s+)?(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)\s*=>|function))/g;
+    for (const match of content.matchAll(exportRegex)) {
+      const name = match[1] || match[2];
+      if (name && !analysis.exports.includes(name)) {
+        analysis.exports.push(name);
+      }
+    }
+
+    // Extract class declarations
+    const classRegex = /export\s+class\s+(\w+)(?:\s+extends\s+(\w+))?\s*\{/g;
+    for (const match of content.matchAll(classRegex)) {
+      const className = match[1];
+      const extendsClass = match[2];
+      const classInfo: ClassInfo = {
+        name: className,
+        methods: [],
+        properties: [],
+        extends: extendsClass,
+        lineNumber: this.findLineNumber(content, match.index)
+      };
+
+      // Extract class methods
+      const classContent = this.extractClassContent(content, match.index);
+      const methodRegex = /(?:public|private|protected)?\s*(?:async\s+)?(\w+)\s*\(([^)]*)\)(?:\s*:\s*(\w+))?/g;
+      for (const methodMatch of classContent.matchAll(methodRegex)) {
+        if (methodMatch[1] === 'constructor') continue;
+        classInfo.methods.push({
+          name: methodMatch[1],
+          params: this.parseParams(methodMatch[2]),
+          returnType: methodMatch[3],
+          isAsync: classContent.includes('async') && classContent.indexOf('async') < classContent.indexOf(methodMatch[1]),
+          isPublic: !classContent.slice(0, methodMatch.index).includes('private'),
+          lineNumber: analysis.linesOfCode,
+          complexity: this.estimateFunctionComplexity(classContent)
+        });
+      }
+
+      analysis.classes.push(classInfo);
+    }
+
+    // Extract function declarations
+    const fnRegex = /((?:export\s+)?(?:async\s+)?function\s+\w+\s*\([^)]*\)(?:\s*:\s*\w+)?)/g;
+    for (const match of content.matchAll(fnRegex)) {
+      const fullMatch = match[1];
+      const fnNameMatch = /function\s+(\w+)/.exec(fullMatch);
+      const paramsMatch = /\(([^)]*)\)/.exec(fullMatch);
+      const returnMatch = /:\s*(\w+)/.exec(fullMatch);
+
+      if (fnNameMatch) {
+        // Get more context for complexity estimation (function body)
+        const fnStart = match.index;
+        const fnEnd = Math.min(fnStart + 1000, content.length); // Look ahead up to 1000 chars
+        const fnContext = content.slice(fnStart, fnEnd);
+
+        analysis.functions.push({
+          name: fnNameMatch[1],
+          params: paramsMatch ? this.parseParams(paramsMatch[1]) : [],
+          returnType: returnMatch ? returnMatch[1] : undefined,
+          isAsync: fullMatch.includes('async'),
+          isPublic: this.options.includePrivate || !fullMatch.includes('private'),
+          lineNumber: this.findLineNumber(content, match.index),
+          complexity: this.estimateFunctionComplexity(fnContext)
+        });
+      }
+    }
+
+    // Extract imports
+    const importRegex = /import\s+(?:(\{[^}]+\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"]([^'"]+)['"]/g;
+    for (const match of content.matchAll(importRegex)) {
+      const module = match[2];
+      const imports = match[1] ? match[1].replace(/[{}*\s]/g, '').split(',').filter(Boolean) : [module.split('/').pop() || module];
+      analysis.imports.push({
+        module,
+        imports,
+        isExternal: this.isExternalModule(module)
+      });
+    }
+
+    // Check for require statements
+    const requireRegex = /(?:const|let|var)\s+(\w+)\s*=\s*require\(['"]([^'"]+)['"]\)/g;
+    for (const match of content.matchAll(requireRegex)) {
+      analysis.imports.push({
+        module: match[2],
+        imports: [match[1]],
+        isExternal: this.isExternalModule(match[2])
+      });
+    }
+  }
+
+  /**
+   * Analyze Python code
+   */
+  private analyzePython(content: string, analysis: SourceAnalysis): void {
+    // Extract class definitions
+    const classRegex = /^class\s+(\w+)(?:\(([^)]+)\))?\s*:/gm;
+    for (const match of content.matchAll(classRegex)) {
+      const className = match[1];
+      const baseClass = match[2];
+      analysis.classes.push({
+        name: className,
+        methods: [],
+        properties: [],
+        extends: baseClass,
+        lineNumber: this.findLineNumber(content, match.index)
+      });
+    }
+
+    // Extract function definitions
+    const fnRegex = /^def\s+(\w+)\s*\(([^)]*)\)(?:\s*->\s*(\w+))?:/gm;
+    for (const match of content.matchAll(fnRegex)) {
+      const isPrivate = match[1].startsWith('_');
+      analysis.functions.push({
+        name: match[1],
+        params: this.parseParams(match[2]),
+        returnType: match[3],
+        isAsync: content.slice(0, match.index).trimEnd().endsWith('async'),
+        isPublic: this.options.includePrivate || !isPrivate,
+        lineNumber: this.findLineNumber(content, match.index),
+        complexity: this.estimateFunctionComplexity(content.slice(match.index, Math.min(match.index + 500, content.length)))
+      });
+
+      // Top-level functions are exports
+      if (!isPrivate && !content.slice(0, match.index).includes('class ')) {
+        analysis.exports.push(match[1]);
+      }
+    }
+
+    // Extract imports
+    const importRegex = /^(?:from\s+(\S+)\s+)?import\s+(.+)/gm;
+    for (const match of content.matchAll(importRegex)) {
+      const module = match[1] || match[2].split('.')[0];
+      const imports = match[1] ? match[2].split(',').map(s => s.trim()) : [module];
+      analysis.imports.push({
+        module,
+        imports,
+        isExternal: !module.startsWith('.')
+      });
+    }
+  }
+
+  /**
+   * Analyze Go code
+   */
+  private analyzeGo(content: string, analysis: SourceAnalysis): void {
+    // Extract function definitions
+    const fnRegex = /func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)\s*\(([^)]*)\)(?:\s*\(([^)]*)\))?/g;
+    for (const match of content.matchAll(fnRegex)) {
+      const isPrivate = match[1] && match[1][0] === match[1][0].toLowerCase();
+      analysis.exports.push(match[1]);
+      analysis.functions.push({
+        name: match[1],
+        params: this.parseParams(match[2]),
+        returnType: match[3],
+        isAsync: false,
+        isPublic: this.options.includePrivate || !isPrivate,
+        lineNumber: this.findLineNumber(content, match.index),
+        complexity: this.estimateFunctionComplexity(content.slice(match.index, match.index + 500))
+      });
+    }
+
+    // Extract type definitions (similar to classes)
+    const typeRegex = /type\s+(\w+)\s+struct\s*\{([^}]*)\}/g;
+    for (const match of content.matchAll(typeRegex)) {
+      analysis.classes.push({
+        name: match[1],
+        methods: [],
+        properties: match[2].split('\n').map(l => l.trim()).filter(Boolean),
+        lineNumber: this.findLineNumber(content, match.index)
+      });
+    }
+
+    // Extract imports
+    const importRegex = /import\s+(?:\(\s*)?["']([^"']+)["']/g;
+    for (const match of content.matchAll(importRegex)) {
+      analysis.imports.push({
+        module: match[1],
+        imports: [],
+        isExternal: !match[1].startsWith('.')
+      });
+    }
+  }
+
+  /**
+   * Get language from file extension
+   */
+  private getLanguage(ext: string): 'typescript' | 'javascript' | 'python' | 'go' {
+    const langMap: Record<string, 'typescript' | 'javascript' | 'python' | 'go'> = {
+      '.ts': 'typescript',
+      '.tsx': 'typescript',
+      '.js': 'javascript',
+      '.jsx': 'javascript',
+      '.py': 'python',
+      '.go': 'go'
+    };
+    return langMap[ext] || 'typescript';
+  }
+
+  /**
+   * Check if file is a source file
+   */
+  private isSourceFile(ext: string): boolean {
+    return ['.ts', '.tsx', '.js', '.jsx', '.py', '.go'].includes(ext);
+  }
+
+  /**
+   * Traverse directory recursively
+   */
+  private traverseDirectory(dir: string, callback: (filePath: string) => void): void {
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      // Skip excluded directories
+      if (this.options.exclude.some(pattern => fullPath.includes(pattern))) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        this.traverseDirectory(fullPath, callback);
+      } else if (entry.isFile()) {
+        callback(fullPath);
+      }
+    }
+  }
+
+  /**
+   * Find test file for a source file
+   */
+  private findTestFile(filePath: string): string | undefined {
+    const dir = join(filePath, '..');
+    const base = basename(filePath, extname(filePath));
+    const ext = extname(filePath);
+
+    const testPatterns = [
+      join(dir, `${base}.test.ts`),
+      join(dir, `${base}.spec.ts`),
+      join(dir, `${base}.test.js`),
+      join(dir, `${base}.spec.js`),
+      join(dir, '__tests__', `${base}.test.ts`),
+      join(dir, '__tests__', `${base}.spec.ts`),
+      join(dir, 'tests', `${base}.test.ts`)
+    ];
+
+    for (const pattern of testPatterns) {
+      if (existsSync(pattern)) {
+        return pattern;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Calculate overall complexity score
+   */
+  private calculateComplexity(analysis: SourceAnalysis): number {
+    let complexity = 0;
+
+    for (const fn of analysis.functions) {
+      complexity += fn.complexity;
+    }
+
+    for (const cls of analysis.classes) {
+      for (const method of cls.methods) {
+        complexity += method.complexity;
+      }
+    }
+
+    return complexity;
+  }
+
+  /**
+   * Estimate function complexity
+   */
+  private estimateFunctionComplexity(code: string): number {
+    let complexity = 1; // Base complexity
+
+    // Count decision points
+    const decisionPatterns = [
+      /\bif\b/g,
+      /\belse\b/g,
+      /\bfor\b/g,
+      /\bwhile\b/g,
+      /\bswitch\b/g,
+      /\bcase\b/g,
+      /\bcatch\b/g,
+      /\?\s*:/g, // ternary
+      /\|\|/g, // logical OR
+      /&&/g   // logical AND
+    ];
+
+    for (const pattern of decisionPatterns) {
+      const matches = code.match(pattern);
+      if (matches) {
+        complexity += matches.length;
+      }
+    }
+
+    return complexity;
+  }
+
+  /**
+   * Parse function parameters
+   */
+  private parseParams(paramsStr: string): string[] {
+    if (!paramsStr.trim()) return [];
+    return paramsStr.split(',').map(p => p.trim()).filter(Boolean);
+  }
+
+  /**
+   * Extract class content
+   */
+  private extractClassContent(content: string, startIndex: number): string {
+    let depth = 0;
+    let inClass = false;
+    let result = '';
+
+    for (let i = startIndex; i < content.length; i++) {
+      const char = content[i];
+      if (char === '{') {
+        depth++;
+        inClass = true;
+      } else if (char === '}') {
+        depth--;
+        if (inClass && depth === 0) {
+          break;
+        }
+      }
+      if (inClass) {
+        result += char;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Find line number for a position in content
+   */
+  private findLineNumber(content: string, index: number): number {
+    return content.slice(0, index).split('\n').length;
+  }
+
+  /**
+   * Generate test name from file path
+   */
+  private generateTestName(filePath: string): string {
+    const base = basename(filePath, extname(filePath));
+    return base.replace(/[^a-zA-Z0-9]/g, ' ') + ' Tests';
+  }
+
+  /**
+   * Recommend testing framework based on language
+   */
+  private recommendFramework(language: string): 'vitest' | 'jest' | 'pytest' | 'go test' {
+    const frameworkMap: Record<string, 'vitest' | 'jest' | 'pytest' | 'go test'> = {
+      typescript: 'vitest',
+      javascript: 'vitest',
+      python: 'pytest',
+      go: 'go test'
+    };
+    return frameworkMap[language] || 'vitest';
+  }
+
+  /**
+   * Generate assertions for a function
+   */
+  private generateAssertions(fn: FunctionInfo): string[] {
+    const assertions: string[] = [];
+
+    if (fn.isAsync) {
+      assertions.push('function resolves', 'function completes without timeout');
+    }
+
+    if (fn.returnType?.toLowerCase().includes('void') || fn.params.length === 0) {
+      assertions.push('function executes without error');
+    } else {
+      assertions.push('function returns expected value');
+    }
+
+    if (fn.params.length > 0) {
+      assertions.push('function handles invalid input');
+    }
+
+    return assertions;
+  }
+
+  /**
+   * Generate mocks for a function
+   */
+  private generateMocks(fn: FunctionInfo, imports: ImportInfo[]): string[] {
+    const mocks: string[] = [];
+
+    for (const imp of imports) {
+      if (imp.isExternal && this.isHttpModule(imp.module)) {
+        mocks.push(imp.module);
+      }
+    }
+
+    return mocks;
+  }
+
+  /**
+   * Generate mocks for a class
+   */
+  private generateMocksForClass(cls: ClassInfo, imports: ImportInfo[]): string[] {
+    const mocks: string[] = [];
+
+    for (const imp of imports) {
+      if (imp.isExternal) {
+        mocks.push(imp.module);
+      }
+    }
+
+    return mocks;
+  }
+
+  /**
+   * Check if module is an HTTP module
+   */
+  private isHttpModule(module: string): boolean {
+    const httpModules = ['http', 'https', 'axios', 'fetch', 'node-fetch', 'request', 'supertest'];
+    return httpModules.some(m => module.toLowerCase().includes(m));
+  }
+
+  /**
+   * Check if module is external
+   */
+  private isExternalModule(module: string): boolean {
+    return !module.startsWith('.') && !module.startsWith('/');
+  }
+
+  /**
+   * Extract base URL from imports
+   */
+  private extractBaseUrl(analysis: SourceAnalysis): string {
+    // Try to find a base URL in constants or config
+    const urlConstants = analysis.imports.filter(i =>
+      i.module.toLowerCase().includes('config') ||
+      i.module.toLowerCase().includes('constants')
+    );
+
+    if (urlConstants.length > 0) {
+      return 'https://api.example.com'; // Placeholder
+    }
+
+    return 'https://localhost:3000';
+  }
+
+  /**
+   * Extract API endpoint from function
+   */
+  private extractEndpoint(fn: FunctionInfo, analysis: SourceAnalysis): ApiEndpoint | null {
+    const name = fn.name.toLowerCase();
+
+    // Check for HTTP method prefixes
+    const httpMethods = ['get', 'post', 'put', 'patch', 'delete'];
+    let method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | undefined;
+    let path = `/${fn.name}`;
+
+    for (const httpMethod of httpMethods) {
+      if (name.startsWith(httpMethod)) {
+        method = httpMethod.toUpperCase() as any;
+        path = `/${name.slice(httpMethod.length)}`;
+        break;
+      }
+    }
+
+    // Check for Express/Fastify patterns
+    if (fn.params.some(p => p.includes('req') || p.includes('request') || p.includes('res') || p.includes('response'))) {
+      return {
+        method: method || 'GET',
+        path,
+        description: fn.name,
+        expectations: [{ status: 200 }]
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get analysis as GenerationSource
+   */
+  toGenerationSource(analysis: SourceAnalysis): GenerationSource {
+    return {
+      type: 'code',
+      code: readFileSync(analysis.filePath, 'utf-8'),
+      language: analysis.language
+    };
+  }
+}
+
+/**
+ * Convenience function to analyze a source file
+ */
+export function analyzeSourceFile(filePath: string, options?: SourceAnalyzerOptions): SourceAnalysis {
+  const analyzer = new SourceAnalyzer(options);
+  return analyzer.analyzeFile(filePath);
+}
+
+/**
+ * Convenience function to analyze a directory
+ */
+export function analyzeSourceDirectory(dirPath: string, options?: SourceAnalyzerOptions): SourceAnalysis[] {
+  const analyzer = new SourceAnalyzer(options);
+  return analyzer.analyzeDirectory(dirPath);
+}
+
+/**
+ * Convenience function to generate test spec from analysis
+ */
+export function generateTestSpec(analysis: SourceAnalysis): UnitTestSpec {
+  const analyzer = new SourceAnalyzer();
+  return analyzer.generateSpec(analysis);
+}