@m3hti/commit-genie 3.0.0 → 3.1.0

package/CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md - CommitGenie
+
+## Project Overview
+
+CommitGenie (`@m3hti/commit-genie`) is a Node.js CLI tool that generates intelligent Git commit messages by analyzing staged code changes. It uses rule-based pattern matching, AST analysis (via `@typescript-eslint/typescript-estree`), and optional AI integration to produce Conventional Commits-formatted messages.
+
+## Tech Stack
+
+- **Language**: TypeScript 5.3 (strict mode)
+- **Runtime**: Node.js >= 16
+- **CLI Framework**: Commander.js
+- **AST Parsing**: @typescript-eslint/typescript-estree
+- **Testing**: Jest 30 + ts-jest
+- **Build Target**: ES2020, compiled to CommonJS
+
+## Project Structure
+
+```
+src/
+├── index.ts              # CLI entry point (Commander setup)
+├── commands/             # Command handlers (generate, hook, config, stats)
+├── services/             # Core business logic (static service classes)
+│   ├── gitService.ts     # Git operations (status, diff, history)
+│   ├── analyzerService.ts # Change analysis & message generation
+│   ├── astAnalyzer.ts    # AST parsing utilities
+│   ├── astClassifier.ts  # AST-based commit type classification
+│   ├── astDiffEngine.ts  # AST diff computation
+│   ├── astExportAnalyzer.ts # Export tracking for breaking changes
+│   ├── historyService.ts # Commit history learning & ticket detection
+│   ├── configService.ts  # .commitgenierc.json loading
+│   ├── lintService.ts    # Commit message linting
+│   ├── spellService.ts   # Spell checking
+│   ├── splitService.ts   # Commit splitting suggestions
+│   ├── statsService.ts   # Repository statistics
+│   ├── hookService.ts    # Git hook management
+│   └── aiService.ts      # Optional LLM integration
+├── data/
+│   └── wordlist.ts       # Bundled wordlist for spell check
+├── utils/
+│   ├── filePatterns.ts   # File type detection patterns
+│   └── prompt.ts         # Interactive CLI prompts (readline)
+└── types/
+    └── index.ts          # All TypeScript interfaces & types
+```
+
+Test files are colocated with source files (`*.test.ts`).
+
+## Common Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build (compile TypeScript to dist/)
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Watch mode for continuous compilation
+npm run watch
+
+# Run compiled version
+npm start
+```
+
+## Architecture Notes
+
+- **Service layer pattern**: All business logic lives in service classes with static methods (no instantiation needed).
+- **No barrel exports**: Each file imports directly from its source, not via index re-exports.
+- **Entry point**: `src/index.ts` sets up the Commander CLI; the default command is `generate`.
+- **Config**: User configuration loaded from `.commitgenierc.json` at the git root or current directory.
+- **Binary**: Published as `commit-genie` CLI via the `bin` field in package.json.
+
+## Code Conventions
+
+- 2-space indentation
+- Single quotes for strings
+- Semicolons required
+- PascalCase for classes and interfaces
+- camelCase for functions and variables
+- TypeScript strict mode is on — all strict checks enforced
+- No ESLint or Prettier configured; follow existing style
+
+## Testing
+
+- Tests use Jest with the `ts-jest` preset
+- Test files live alongside source: `src/services/gitService.test.ts`
+- Tests use `describe`/`it` structure with `expect` assertions
+- Dependencies are mocked with `jest.mock()` and manual mock implementations
+- Coverage excludes `*.d.ts` files and `src/index.ts`
+- Run `npm test` before submitting changes
+
+## Key Types
+
+Defined in `src/types/index.ts`:
+
+- `CommitType`: `'feat' | 'fix' | 'docs' | 'style' | 'refactor' | 'test' | 'chore' | 'perf'`
+- `ChangeAnalysis`: The central analysis result including commit type, scope, description, file changes, semantic analysis, and AST results
+- `CommitMessage`: Formatted commit message with type, scope, description, body, footer
+- `CommitGenieConfig`: Full user configuration interface
+- `SemanticAnalysis`: Role-based analysis (UI, logic, data, API, style, config, test)
+- `ASTClassifierResult`: AST-based commit classification output

package/dist/services/analyzerService.d.ts

@@ -106,9 +106,32 @@ export declare class AnalyzerService {
      * Generate the WHAT changed description
      */
     private static generateWhatChanged;
+    /**
+     * Generate a description from AST analysis results.
+     * Produces specific, human-readable descriptions based on structural signals.
+     * Returns empty string if AST data is insufficient for a good description.
+     */
+    private static generateASTDescription;
+    /**
+     * Detect test+implementation file pairs.
+     * Returns the pair info if files match naming conventions, null otherwise.
+     */
+    private static detectTestImplPair;
+    /**
+     * Generate description using lightweight file content analysis (JSON, CSS, YAML, MD).
+     * Returns null if no structural info is available.
+     */
+    private static generateFileContentDescription;
+    /**
+     * Generate description using hunk header context (function/class names).
+     * Works for any language that git can identify scope for.
+     * Returns null if no hunk context is available.
+     */
+    private static generateHunkDescription;
     /**
      * Generate a descriptive commit message
-     * Uses semantic analysis when available for intent-based descriptions
+     * Uses AST analysis for specific descriptions when available,
+     * falls back to semantic analysis and regex-based descriptions.
      */
     private static generateDescription;
     /**
@@ -151,6 +174,7 @@ export declare class AnalyzerService {
     static generateSuggestionsWithAI(useAI?: boolean): Promise<MessageSuggestion[]>;
     /**
      * Generate an alternative description style
+     * Uses AST data when available, otherwise falls back to regex extraction.
      */
     private static generateAlternativeDescription;
 }

package/dist/services/analyzerService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzerService.d.ts","sourceRoot":"","sources":["../../src/services/analyzerService.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,cAAc,EAEd,aAAa,EAKb,iBAAiB,EAKlB,MAAM,UAAU,CAAC;AAsOlB,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,cAAc;IAqJvC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6EpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA6TlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IA4B9B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA8DrC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAyF5C;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAkEvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6BvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA+ClC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkCrC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA8ChC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAkBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAkD/B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA6BnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAsD9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAuEtC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAmDjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkClC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IA0C5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA8CrC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAUlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IA2BxC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAgDlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAwFlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,2BAA2B;IAyE1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAiD7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAK1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAmD3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IA8B5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAkE/B;;OAEG;IACH,MAAM,CAAC,qBAAqB,IAAI,aAAa;IAkC7C;;OAEG;IACH,MAAM,CAAC,2BAA2B,IAAI,iBAAiB,EAAE;IAqLzD;;OAEG;WACU,yBAAyB,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0E5F;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;CAoE9C"}
+{"version":3,"file":"analyzerService.d.ts","sourceRoot":"","sources":["../../src/services/analyzerService.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,cAAc,EAEd,aAAa,EAKb,iBAAiB,EAKlB,MAAM,UAAU,CAAC;AAsOlB,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,cAAc;IAuJvC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6EpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA+TlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IA4B9B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA8DrC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAyF5C;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAkEvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAsCvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA+ClC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkCrC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA8ChC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAkBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAkD/B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA6BnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAsD9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAuEtC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAmDjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkClC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IA0C5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA8CrC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAUlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IA2BxC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAgDlC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA4HrC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAyCjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAuB7C;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAyBtC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAqIlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,2BAA2B;IAyE1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAiD7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAK1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAmD3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IA8B5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAkE/B;;OAEG;IACH,MAAM,CAAC,qBAAqB,IAAI,aAAa;IAkC7C;;OAEG;IACH,MAAM,CAAC,2BAA2B,IAAI,iBAAiB,EAAE;IAqLzD;;OAEG;WACU,yBAAyB,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0E5F;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;CAiG9C"}

package/dist/services/analyzerService.js

@@ -8,6 +8,7 @@ const aiService_1 = require("./aiService");
 const filePatterns_1 = require("../utils/filePatterns");
 const astExportAnalyzer_1 = require("./astExportAnalyzer");
 const astClassifier_1 = require("./astClassifier");
+const fileContentAnalyzer_1 = require("./fileContentAnalyzer");
 const COMMIT_EMOJIS = {
     feat: '✨',
     fix: '🐛',
@@ -335,13 +336,13 @@ class AnalyzerService {
                 commitType = mappedType;
             }
         }
-        // Generate description (uses semantic analysis when available)
+        // Generate description (uses AST analysis, then semantic analysis as fallback)
         const description = this.generateDescription(filesAffected, {
             added: fileChanges.added.length,
             modified: fileChanges.modified.length,
             deleted: fileChanges.deleted.length,
             renamed: fileChanges.renamed.length
-        }, stagedFiles, diff, semanticAnalysis);
+        }, stagedFiles, diff, semanticAnalysis, astResult, commitType);
         return {
             commitType,
             scope,
@@ -419,6 +420,8 @@ class AnalyzerService {
      */
     static determineCommitType(filesAffected, diff, stagedFiles, exportDiff) {
         const diffLower = diff.toLowerCase();
+        const cleanedDiff = this.extractNonCommentChanges(diff);
+        const cleanedDiffLower = cleanedDiff.toLowerCase();
         const filePaths = stagedFiles.map((f) => f.path.toLowerCase());
         // === FILE TYPE BASED DETECTION (highest priority) ===
         // If only test files changed
@@ -496,7 +499,7 @@ class AnalyzerService {
             /\bparallel\b/i,
             /\bbatch(ing)?\b/i,
         ];
-        if (perfPatterns.some(p => p.test(diffLower))) {
+        if (perfPatterns.some(p => p.test(cleanedDiffLower))) {
             return 'perf';
         }
         // === DETECT NEW FUNCTIONALITY FIRST ===
@@ -555,7 +558,7 @@ class AnalyzerService {
             /\benable(s|d|ing)?\s+(new\s+)?\w+/i,
             /\bnew\s+(feature|function|method|api|endpoint)/i,
         ];
-        if (featPatterns.some(p => p.test(diff))) {
+        if (featPatterns.some(p => p.test(cleanedDiff))) {
             return 'feat';
         }
         // === FIX DETECTION ===
@@ -612,7 +615,7 @@ class AnalyzerService {
             /\bwas\s*broken\b/i, // "was broken" indicates fixing
             /\bbroken\b.*\bfix/i, // broken...fix pattern
         ];
-        if (fixPatterns.some(p => p.test(diff))) {
+        if (fixPatterns.some(p => p.test(cleanedDiff))) {
             return 'fix';
         }
         // === REFACTOR DETECTION ===
@@ -629,7 +632,7 @@ class AnalyzerService {
             /\bDRY\b/,
             /\breorganiz(e|es|ed|ing)\b/i,
         ];
-        if (refactorPatterns.some(p => p.test(diff))) {
+        if (refactorPatterns.some(p => p.test(cleanedDiff))) {
             return 'refactor';
         }
         // If modifications with balanced adds/removes and no new functionality, likely refactor
@@ -666,7 +669,7 @@ class AnalyzerService {
             /\bci\b.*\b(config|setup)\b/i,
             /\blint(er|ing)?\b/i,
         ];
-        if (chorePatterns.some(p => p.test(diff)) || chorePatterns.some(p => filePaths.some(f => p.test(f)))) {
+        if (chorePatterns.some(p => p.test(cleanedDiff)) || chorePatterns.some(p => filePaths.some(f => p.test(f)))) {
             return 'chore';
         }
         // === FALLBACK ===
@@ -917,7 +920,7 @@ class AnalyzerService {
             if (trimmed.length === 0)
                 return false;
             // Filter out comment lines
-            return !(trimmed.startsWith('//') ||
+            if (trimmed.startsWith('//') ||
                 trimmed.startsWith('/*') ||
                 trimmed.startsWith('*') ||
                 trimmed.startsWith('*/') ||
@@ -927,7 +930,14 @@ class AnalyzerService {
                 trimmed.startsWith('"""') ||
                 trimmed.startsWith("'''") ||
                 /^\/\*\*/.test(trimmed) ||
-                /^\*\s*@\w+/.test(trimmed));
+                /^\*\s*@\w+/.test(trimmed)) {
+                return false;
+            }
+            // Filter out lines that are purely string literals
+            if (/^(?:return\s+)?(['"`]).*\1[;,]?\s*$/.test(trimmed)) {
+                return false;
+            }
+            return true;
         })
             .join('\n');
     }
@@ -1498,11 +1508,209 @@ class AnalyzerService {
         }
         return 'code';
     }
+    /**
+     * Generate a description from AST analysis results.
+     * Produces specific, human-readable descriptions based on structural signals.
+     * Returns empty string if AST data is insufficient for a good description.
+     */
+    static generateASTDescription(astResult, commitType) {
+        const { declarations, signals } = astResult;
+        // Handle renames — most specific and readable
+        if (declarations.renamed.length > 0) {
+            const r = declarations.renamed[0];
+            if (declarations.renamed.length === 1) {
+                return `rename ${r.oldName} to ${r.newName}`;
+            }
+            return `rename ${r.oldName} to ${r.newName} and ${declarations.renamed.length - 1} more`;
+        }
+        // Handle removed exported declarations (breaking refactor)
+        const removedExported = declarations.removed.filter(d => d.exported);
+        if (removedExported.length > 0) {
+            if (removedExported.length === 1) {
+                return `remove ${removedExported[0].name} export`;
+            }
+            return `remove ${removedExported[0].name} and ${removedExported.length - 1} more exports`;
+        }
+        // Handle breaking signature changes
+        const sigChangeSignals = signals.filter(s => s.signal === 'changed-exported-sig');
+        if (sigChangeSignals.length > 0) {
+            const nameMatch = sigChangeSignals[0].detail.match(/on '([^']+)'/);
+            if (nameMatch) {
+                return `change ${nameMatch[1]} signature`;
+            }
+        }
+        // Handle new declarations (feat)
+        if (commitType === 'feat' && declarations.added.length > 0) {
+            const exported = declarations.added.filter(d => d.exported);
+            const target = exported.length > 0 ? exported : declarations.added;
+            if (target.length === 1) {
+                return `add ${target[0].name} ${target[0].kind}`;
+            }
+            if (target.length === 2) {
+                return `add ${target[0].name} and ${target[1].name}`;
+            }
+            return `add ${target[0].name}, ${target[1].name} and ${target.length - 2} more`;
+        }
+        // Handle fix signals (error handling, guards)
+        if (commitType === 'fix') {
+            const errorSignals = signals.filter(s => s.signal === 'error-handling-change');
+            if (errorSignals.length > 0) {
+                const nameMatch = errorSignals[0].detail.match(/in '([^']+)'/);
+                if (nameMatch) {
+                    return `handle errors in ${nameMatch[1]}`;
+                }
+            }
+            const guardSignals = signals.filter(s => s.signal === 'guard-added');
+            if (guardSignals.length > 0) {
+                const nameMatch = guardSignals[0].detail.match(/in '([^']+)'/);
+                if (nameMatch) {
+                    return `add validation to ${nameMatch[1]}`;
+                }
+            }
+            // Literal-only changes
+            const literalSignals = signals.filter(s => s.signal === 'literal-only-change');
+            if (literalSignals.length > 0) {
+                const nameMatch = literalSignals[0].detail.match(/in '([^']+)'/);
+                if (nameMatch) {
+                    return `fix values in ${nameMatch[1]}`;
+                }
+            }
+        }
+        // Handle perf signals
+        if (commitType === 'perf') {
+            const perfSignals = signals.filter(s => s.signal === 'perf-pattern');
+            if (perfSignals.length > 0) {
+                const nameMatch = perfSignals[0].detail.match(/in '([^']+)'/);
+                if (nameMatch) {
+                    return `optimize ${nameMatch[1]} performance`;
+                }
+            }
+        }
+        // Handle refactor signals (control flow, modified)
+        if (commitType === 'refactor') {
+            const controlFlowSignals = signals.filter(s => s.signal === 'control-flow-restructured');
+            if (controlFlowSignals.length > 0) {
+                const nameMatch = controlFlowSignals[0].detail.match(/in '([^']+)'/);
+                if (nameMatch) {
+                    return `simplify ${nameMatch[1]} control flow`;
+                }
+            }
+            if (declarations.modified.length > 0) {
+                const names = declarations.modified.map(m => m.name);
+                if (names.length === 1) {
+                    return `refactor ${names[0]}`;
+                }
+                if (names.length === 2) {
+                    return `refactor ${names[0]} and ${names[1]}`;
+                }
+                return `refactor ${names[0]}, ${names[1]} and ${names.length - 2} more`;
+            }
+        }
+        // Generic fallback using affectedElements
+        if (astResult.affectedElements.length > 0) {
+            const verb = commitType === 'feat' ? 'add' :
+                commitType === 'fix' ? 'fix' :
+                    commitType === 'refactor' ? 'refactor' :
+                        commitType === 'perf' ? 'optimize' : 'update';
+            const els = astResult.affectedElements;
+            if (els.length === 1) {
+                return `${verb} ${els[0]}`;
+            }
+            if (els.length === 2) {
+                return `${verb} ${els[0]} and ${els[1]}`;
+            }
+            return `${verb} ${els[0]}, ${els[1]} and ${els.length - 2} more`;
+        }
+        return '';
+    }
+    /**
+     * Detect test+implementation file pairs.
+     * Returns the pair info if files match naming conventions, null otherwise.
+     */
+    static detectTestImplPair(stagedFiles) {
+        if (stagedFiles.length < 2)
+            return null;
+        for (const file of stagedFiles) {
+            const path = file.path;
+            // Check if this is a test file
+            const testMatch = path.match(/^(.+)\.(test|spec)\.(ts|tsx|js|jsx|mts|cts)$/);
+            const dirTestMatch = path.match(/^(.+\/)__tests__\/(.+)\.(ts|tsx|js|jsx|mts|cts)$/);
+            if (testMatch) {
+                const implPath = `${testMatch[1]}.${testMatch[3]}`;
+                const implFile = stagedFiles.find(f => f.path === implPath);
+                if (implFile) {
+                    return {
+                        implFile: this.getFileName(implFile.path),
+                        testFile: this.getFileName(file.path),
+                        implStatus: implFile.status,
+                        testStatus: file.status,
+                    };
+                }
+            }
+            if (dirTestMatch) {
+                const implPath = `${dirTestMatch[1]}${dirTestMatch[2]}.${dirTestMatch[3]}`;
+                const implFile = stagedFiles.find(f => f.path === implPath);
+                if (implFile) {
+                    return {
+                        implFile: this.getFileName(implFile.path),
+                        testFile: this.getFileName(file.path),
+                        implStatus: implFile.status,
+                        testStatus: file.status,
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Generate description using lightweight file content analysis (JSON, CSS, YAML, MD).
+     * Returns null if no structural info is available.
+     */
+    static generateFileContentDescription(stagedFiles, diff) {
+        if (stagedFiles.length !== 1)
+            return null;
+        const file = stagedFiles[0];
+        const analysis = (0, fileContentAnalyzer_1.analyzeFileContent)(file.path, diff);
+        if (!analysis || analysis.changedElements.length === 0)
+            return null;
+        const fileName = this.getFileName(file.path);
+        const elements = analysis.changedElements;
+        const elementStr = elements.length <= 2
+            ? elements.join(' and ')
+            : `${elements[0]} and ${elements.length - 1} more`;
+        const verb = analysis.changeKind === 'added' ? 'add'
+            : analysis.changeKind === 'removed' ? 'remove'
+                : 'update';
+        return `${verb} ${elementStr} in ${fileName}`;
+    }
+    /**
+     * Generate description using hunk header context (function/class names).
+     * Works for any language that git can identify scope for.
+     * Returns null if no hunk context is available.
+     */
+    static generateHunkDescription(stagedFiles, diff, commitType) {
+        const hunkNames = this.extractHunkContext(diff);
+        if (hunkNames.length === 0)
+            return null;
+        const verb = commitType === 'feat' ? 'add' :
+            commitType === 'fix' ? 'fix' :
+                commitType === 'refactor' ? 'refactor' :
+                    commitType === 'perf' ? 'optimize' : 'update';
+        const nameStr = hunkNames.length <= 2
+            ? hunkNames.join(' and ')
+            : `${hunkNames[0]} and ${hunkNames.length - 1} more`;
+        if (stagedFiles.length === 1) {
+            const fileName = this.getFileName(stagedFiles[0].path);
+            return `${verb} ${nameStr} in ${fileName}`;
+        }
+        return `${verb} ${nameStr}`;
+    }
     /**
      * Generate a descriptive commit message
-     * Uses semantic analysis when available for intent-based descriptions
+     * Uses AST analysis for specific descriptions when available,
+     * falls back to semantic analysis and regex-based descriptions.
      */
-    static generateDescription(filesAffected, fileStatuses, stagedFiles, diff, semanticAnalysis) {
+    static generateDescription(filesAffected, fileStatuses, stagedFiles, diff, semanticAnalysis, astResult, commitType) {
         // Check for comment-only changes (documentation in source files)
         if (this.isCommentOnlyChange(diff)) {
             const fileName = stagedFiles.length === 1 ? this.getFileName(stagedFiles[0].path) : null;
@@ -1523,10 +1731,52 @@ class AnalyzerService {
         if (this.isFormattingOnlyChange(diff)) {
             return this.generateFormattingDescription(diff, stagedFiles);
         }
+        // Use AST analysis for specific, human-readable descriptions when available
+        // AST descriptions are preferred because they name exact functions/classes
+        if (astResult && commitType) {
+            const astMaxWeight = astResult.signals.length > 0
+                ? Math.max(...astResult.signals.map(s => s.weight), 0)
+                : 0;
+            if (astMaxWeight > 1 || astResult.declarations.renamed.length > 0) {
+                const astDesc = this.generateASTDescription(astResult, commitType);
+                if (astDesc) {
+                    return astDesc;
+                }
+            }
+        }
         // Use semantic analysis for intent-based descriptions when available
         if (semanticAnalysis && semanticAnalysis.roleChanges.length > 0) {
             return this.generateSemanticDescription(semanticAnalysis, stagedFiles);
         }
+        // Detect test + implementation file pairs
+        const pair = this.detectTestImplPair(stagedFiles);
+        if (pair) {
+            const implName = pair.implFile.replace(/\.\w+$/, '');
+            if (pair.implStatus === 'A' && pair.testStatus === 'A') {
+                return `add ${implName} with tests`;
+            }
+            else if (pair.implStatus === 'M' && pair.testStatus === 'A') {
+                return `update ${implName} and add tests`;
+            }
+            else if (pair.implStatus === 'A' && pair.testStatus === 'M') {
+                return `add ${implName} and update tests`;
+            }
+            else {
+                return `update ${implName} and tests`;
+            }
+        }
+        // Use lightweight file content analysis (JSON keys, CSS selectors, etc.)
+        const fileContentDesc = this.generateFileContentDescription(stagedFiles, diff);
+        if (fileContentDesc) {
+            return fileContentDesc;
+        }
+        // Use hunk header context for function/class names (works for any language)
+        if (commitType) {
+            const hunkDesc = this.generateHunkDescription(stagedFiles, diff, commitType);
+            if (hunkDesc) {
+                return hunkDesc;
+            }
+        }
         // Single file changes (fallback)
         if (stagedFiles.length === 1) {
             const file = stagedFiles[0];
@@ -2009,11 +2259,38 @@ class AnalyzerService {
     }
     /**
      * Generate an alternative description style
+     * Uses AST data when available, otherwise falls back to regex extraction.
      */
     static generateAlternativeDescription(analysis, diff) {
         const { fileChanges, filesAffected } = analysis;
         const totalFiles = fileChanges.added.length + fileChanges.modified.length +
             fileChanges.deleted.length + fileChanges.renamed.length;
+        // Use AST data to build a detailed alternative with file context
+        if (analysis.astResult && analysis.astResult.affectedElements.length > 0) {
+            const elements = analysis.astResult.affectedElements;
+            const verb = analysis.commitType === 'feat' ? 'add' :
+                analysis.commitType === 'fix' ? 'fix' :
+                    analysis.commitType === 'refactor' ? 'refactor' : 'update';
+            // For single file, include file name for extra context
+            if (totalFiles === 1) {
+                const fileName = fileChanges.added[0] || fileChanges.modified[0] || fileChanges.deleted[0] || fileChanges.renamed[0];
+                if (elements.length === 1) {
+                    return `${verb} ${elements[0]} in ${fileName}`;
+                }
+                if (elements.length === 2) {
+                    return `${verb} ${elements[0]} and ${elements[1]} in ${fileName}`;
+                }
+                return `${verb} ${elements[0]}, ${elements[1]} and ${elements.length - 2} more in ${fileName}`;
+            }
+            // For multiple files, list elements across files
+            if (elements.length === 1) {
+                return `${verb} ${elements[0]}`;
+            }
+            if (elements.length === 2) {
+                return `${verb} ${elements[0]} and ${elements[1]}`;
+            }
+            return `${verb} ${elements[0]}, ${elements[1]} and ${elements.length - 2} more`;
+        }
         // For single file, provide more detail using extracted elements when available
         if (totalFiles === 1) {
             const elements = this.extractAffectedElements(diff);