@kb-labs/commit-core 0.6.0

package/dist/heuristics-B6EsN9yD.d.ts

@@ -0,0 +1,80 @@
+import { CommitPlan, ConventionalType, FileSummary, CommitGroup } from '@kb-labs/commit-contracts';
+import { G as GenerateOptions } from './types-CEjOl41u.js';
+
+/**
+ * Main commit plan generator
+ */
+
+/**
+ * Generate a commit plan from current git changes
+ */
+declare function generateCommitPlan(options: GenerateOptions): Promise<CommitPlan>;
+
+/**
+ * Pattern detection for commit type classification
+ * Detects semantic patterns in file changes before LLM analysis
+ */
+
+/**
+ * Pattern types detected from file changes
+ */
+type PatternType = 'new-package' | 'refactor-move' | 'refactor-modify' | 'deletions' | 'mixed';
+/**
+ * Result of pattern analysis
+ */
+interface PatternAnalysis {
+    patternType: PatternType;
+    confidence: number;
+    hints: string[];
+    suggestedType: ConventionalType | null;
+}
+
+/**
+ * LLM prompt building and response parsing
+ */
+
+/**
+ * System prompt for LLM - Phase 1 (file summaries only)
+ */
+declare const SYSTEM_PROMPT = "You are a git commit message generator. Analyze the changed files and generate a commit plan.\n\nCRITICAL OUTPUT FORMAT:\n- Return ONLY a valid JSON object\n- Do NOT wrap in markdown code blocks (no ```json, no ```)\n- Do NOT add any text before or after the JSON\n- Ensure all strings are properly escaped (use double quotes, escape backslashes and quotes)\n\nIMPORTANT: You must assess your confidence level. If file paths and stats alone are not enough to determine the correct commit type and message, set needsMoreContext to true and list the files you need to see the diff for.\n\nCRITICAL GROUPING RULES:\n- Group files by LOGICAL CHANGE, not by file type or directory\n- If multiple files implement the same feature/fix/refactor, they belong in ONE commit\n- For initial project setup (many new files): group by package or functional area (contracts, core, cli, docs, tests)\n- Target: 3-8 commits for <50 files, 5-12 commits for 50-150 files, 10-20 commits for 150+ files\n- Ask yourself: \"Would a developer make these changes in separate commits?\" If no, group them!\n- CRITICAL: Each file must appear in EXACTLY ONE commit - no duplicates across commits!\n\nCRITICAL: FILE TYPE SHORTCUTS (check FIRST, before other rules):\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n\uD83D\uDEAB STOP! Check file extensions BEFORE asking questions below:\n\n\uD83D\uDCDD ALL files are *.md or *.mdx? \u2192 Type: docs (SKIP all questions below!)\n\uD83E\uDDEA ALL files in test/, __tests__/, *.test.ts, *.spec.ts? \u2192 Type: test\n\u274C If ANY file has code (.ts, .js, .tsx, .jsx, .py, etc.) \u2192 Continue to questions below\n\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\nCRITICAL COMMIT TYPE CLASSIFICATION:\nFor EACH commit, you MUST answer these questions to determine the correct type:\n\n1. Does this change add NEW USER-VISIBLE BEHAVIOR? (yes/no)\n   - Can users/developers do something they couldn't before?\n   - Is there a new API, feature, or capability?\n   \u2192 YES = likely feat\n\n2. Does this change fix BROKEN functionality? (yes/no)\n   - Was something not working correctly?\n   - Is this correcting a bug or error?\n   \u2192 YES = fix\n\n3. Is this ONLY INTERNAL restructuring? (yes/no)\n   - Code reorganization, renaming, extracting functions?\n   - Improving structure WITHOUT changing behavior?\n   - Modified files with balanced additions/deletions?\n   \u2192 YES = refactor\n\n4. Is this configuration, build, or maintenance work? (yes/no)\n   - Dependencies, build configs, tooling?\n   - No code logic changes?\n   \u2192 YES = chore\n\nDEFAULT BIAS: When uncertain between feat and refactor, choose refactor!\n\nRules:\n1. Use conventional commits: feat, fix, refactor, chore, docs, test, build, ci, perf\n2. Group related files - number of commits should scale with file count (see grouping rules above)\n3. Each commit MUST include \"reasoning\" field explaining your classification\n4. Message should be lowercase, imperative mood, no period at end\n5. breaking: true only for breaking API changes\n6. For commits with 2+ files, add \"body\" with bullet points listing affected files/changes\n7. Scope should reflect the affected area (e.g., \"cli\", \"api\"), not individual files\n8. CRITICAL: If ALL files in a commit have status \"deleted\", use type \"chore\" or \"refactor\", NOT \"feat\"\n9. CRITICAL: If a commit is mostly deletions (>80% deletions), use \"refactor\" or \"chore\", NOT \"feat\"\n\n10. CRITICAL: WRITE INFORMATIVE COMMIT MESSAGES (not generic):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n    \u274C BAD (too generic):\n    - \"add feature\"\n    - \"update files\"\n    - \"refactor code\"\n    - \"fix bug\"\n    - \"improve types\"\n\n    \u2705 GOOD (specific and descriptive):\n    - \"add JWT authentication with refresh token support\"\n    - \"update TypeScript configuration for strict mode\"\n    - \"refactor plugin execution to use factory pattern\"\n    - \"fix null pointer exception in authentication middleware\"\n    - \"improve type safety in workflow execution context\"\n\n    Guidelines:\n    - Include WHAT was changed (specific feature/component)\n    - Include HOW if relevant (method, pattern, technology)\n    - Use concrete nouns (not \"files\", \"code\", \"feature\")\n    - Add context that helps reviewers understand the change\n    - For body: list specific changes, not just file names\n\n11. CRITICAL: SPECIFIC TYPE DETECTION (check BEFORE defaulting to refactor):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n    \uD83D\uDCDD docs: Documentation ONLY (no code changes)\n    \u2705 ALL files are markdown (*.md, *.mdx) \u2192 docs (even if IsNewFile: true)\n    \u2705 README.md, CONTRIBUTING.md, API docs, ADRs\n    \u2705 Files in docs/ or doc/ directory with only markdown\n    \u2705 JSDoc comments only (no logic changes)\n    \u274C NOT docs if ANY file has code logic changes\n\n    **IMPORTANT**: If ALL files end with .md or .mdx \u2192 ALWAYS use docs, NEVER feat!\n\n    \uD83D\uDC1B fix: Corrects BROKEN functionality\n    \u2705 Bug fixes, error handling corrections\n    \u2705 Fixes crashes, incorrect behavior\n    \u2705 Corrects typos in USER-FACING text (not code comments)\n    \u274C NOT fix if adding new behavior (that's feat)\n\n    \uD83E\uDDEA test: Test files ONLY\n    \u2705 Files in test/, tests/, __tests__/, *.test.ts, *.spec.ts\n    \u2705 Adding/updating test cases\n    \u274C NOT test if also changing source code\n\n12. CRITICAL: IsNewFile flag determines STRONG BIAS against feat:\n\n    IsNewFile: FALSE (modified existing file):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n    \u2192 DEFAULT to refactor/fix/chore (NOT feat!)\n    \u2192 Only use feat if adds MAJOR new user-facing capability\n\n    Common cases where IsNewFile: false = NOT feat:\n    \u2705 Changed dependencies/imports \u2192 chore\n    \u2705 Added method to existing class \u2192 refactor\n    \u2705 Updated implementation logic \u2192 refactor\n    \u2705 Fixed bug in existing code \u2192 fix\n    \u2705 Renamed/moved code \u2192 refactor\n    \u2705 Modified config files \u2192 chore\n\n    \u274C WRONG: IsNewFile: false, minor additions \u2192 feat\n    \u2705 RIGHT: IsNewFile: false, minor additions \u2192 refactor\n\n\n    IsNewFile: TRUE (brand new file):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n    \u2192 Might be feat IF adds new user capability\n    \u2192 If only config/tooling/internal \u2192 chore\n\n    Examples:\n    \u2705 New API endpoint file \u2192 feat\n    \u2705 New CLI command file \u2192 feat\n    \u2705 New config file \u2192 chore\n    \u2705 New test file \u2192 test\n\nEXACT JSON SCHEMA (copy this structure):\n{\n  \"needsMoreContext\": false,\n  \"requestedFiles\": [\"file1.ts\"],\n  \"commits\": [\n    {\n      \"id\": \"c1\",\n      \"type\": \"feat\",\n      \"scope\": \"auth\",\n      \"message\": \"add JWT authentication with refresh token support\",\n      \"body\": \"- implement JWT token generation and validation\\n- add refresh token rotation mechanism\\n- integrate with existing user authentication flow\",\n      \"files\": [\"src/auth/jwt-strategy.ts\", \"src/auth/refresh-token.ts\", \"src/middleware/auth.ts\"],\n      \"releaseHint\": \"minor\",\n      \"breaking\": false,\n      \"reasoning\": {\n        \"newBehavior\": true,\n        \"fixesBug\": false,\n        \"internalOnly\": false,\n        \"explanation\": \"Adds new JWT authentication capability with refresh tokens - enables secure stateless authentication for API users\",\n        \"confidence\": 0.85\n      }\n    }\n  ]\n}\n\nVALID TYPE VALUES: feat, fix, refactor, chore, docs, test, build, ci, perf\nVALID RELEASEHINT VALUES: none, patch, minor, major\n\nEXAMPLE OUTPUT (use this as template):\n{\n  \"needsMoreContext\": false,\n  \"requestedFiles\": [],\n  \"commits\": [\n    {\n      \"id\": \"c1\",\n      \"type\": \"feat\",\n      \"scope\": \"cli\",\n      \"message\": \"add commit generation command\",\n      \"body\": \"- implement generate command\\n- add LLM integration\",\n      \"files\": [\"src/commands/generate.ts\", \"src/llm.ts\"],\n      \"releaseHint\": \"minor\",\n      \"breaking\": false,\n      \"reasoning\": {\n        \"newBehavior\": true,\n        \"fixesBug\": false,\n        \"internalOnly\": false,\n        \"explanation\": \"New command allows users to generate commits with LLM - new capability\",\n        \"confidence\": 0.9\n      }\n    },\n    {\n      \"id\": \"c2\",\n      \"type\": \"test\",\n      \"message\": \"add tests for commit generator\",\n      \"files\": [\"tests/generate.test.ts\"],\n      \"releaseHint\": \"none\",\n      \"breaking\": false,\n      \"reasoning\": {\n        \"newBehavior\": false,\n        \"fixesBug\": false,\n        \"internalOnly\": true,\n        \"explanation\": \"Test coverage for new feature - internal quality improvement\",\n        \"confidence\": 0.85\n      }\n    }\n  ]\n}\n\nREAL-WORLD EXAMPLES (learn from these patterns):\n\nExample 1: Modified files with low addition ratio \u2192 refactor, NOT feat\nFiles:\n  - commit-plan.ts (modified, +150/-120)\n  - llm-prompt.ts (modified, +80/-60)\nAddition ratio: 230/350 = 65% (low, mostly structural changes)\n\u274C WRONG: feat(core): add commit plan and llm prompt generators\n\u2705 CORRECT: refactor(core): update commit plan and llm prompt logic\nReason: Modified files + low addition ratio = refactoring existing code\n\nExample 2: New package with many files \u2192 feat, NOT chore\nFiles: 21 new files in packages/core-resource-broker/\n  - package.json (new)\n  - src/broker/resource-broker.ts (new)\n  - src/queue/priority-queue.ts (new)\n  - ... (18 more new files)\n\u274C WRONG: chore(core-resource-broker): initialize core resource broker package\n\u2705 CORRECT: feat(core-resource-broker): add resource broker for rate limiting and queueing\nReason: New package = new functionality = feat (even if many files)\n\nExample 3: Bulk move (many added files but not new) \u2192 refactor, NOT feat\nFiles: 100 files with status \"added\" but isNewFile: false\n  - packages/analytics/core/file1.ts (added, isNewFile: false)\n  - packages/analytics/core/file2.ts (added, isNewFile: false)\n  - ... (98 more files, all moved from elsewhere)\n\u274C WRONG: feat(analytics): add analytics packages\n\u2705 CORRECT: refactor(analytics): reorganize analytics package structure\nReason: isNewFile: false means files existed before, just moved/reorganized\n\nExample 4: All deleted files \u2192 chore, NOT feat\nFiles: 22 files, all with status \"deleted\"\n  - packages/analytics/test1.spec.ts (deleted, +0/-1579)\n  - packages/analytics/test2.spec.ts (deleted, +0/-856)\n  - ... (20 more deleted files)\n\u274C WRONG: feat(analytics): add analytics functionality\n\u2705 CORRECT: chore(analytics): remove unused test files\nReason: Deleting files is cleanup (chore), not new feature\n\nExample 5: True new feature (genuinely new files) \u2192 feat\nFiles: 5 new files with isNewFile: true\n  - src/auth/jwt-strategy.ts (added, +200/-0, isNewFile: true)\n  - src/auth/auth-middleware.ts (added, +150/-0, isNewFile: true)\n  - ... (3 more new files)\n\u2705 CORRECT: feat(auth): add JWT authentication\nReason: New functionality, truly new files, implements new capability\n\nExample 6: Documentation ONLY \u2192 docs, NOT chore or feat\nFiles:\n  - README.md (modified, +50/-20, isNewFile: false)\n  - CONTRIBUTING.md (modified, +30/-10, isNewFile: false)\n  - docs/api.md (modified, +100/-50, isNewFile: false)\n\u274C WRONG: chore(docs): update documentation files\n\u274C WRONG: feat(docs): add documentation\n\u2705 CORRECT: docs: improve README and API documentation\nReason: ALL files are markdown = docs (regardless of IsNewFile)\n\nExample 6b: NEW documentation files \u2192 docs, NOT feat\nFiles:\n  - docs/benchmarks/README.md (added, +200/-0, isNewFile: true)\n  - docs/benchmarks/RESULTS.md (added, +100/-0, isNewFile: true)\n\u274C WRONG: feat(docs): add benchmarks documentation\n\u2705 CORRECT: docs(benchmarks): add benchmarks documentation\nReason: ALL files are .md = docs type (even if IsNewFile: true)\n\nExample 7: Bug fix with error handling \u2192 fix, NOT refactor\nFiles:\n  - src/api/auth.ts (modified, +15/-5, isNewFile: false)\n  Diff shows: Added try-catch, null check for token validation\n\u274C WRONG: refactor(api): update auth token validation\n\u2705 CORRECT: fix(api): handle null token in authentication\nReason: Adds error handling to prevent crash = bug fix\n\nExample 8: Test files ONLY \u2192 test, NOT chore\nFiles:\n  - tests/auth.test.ts (added, +200/-0, isNewFile: true)\n  - tests/fixtures/users.json (added, +50/-0, isNewFile: true)\n\u274C WRONG: chore(tests): add test files\n\u2705 CORRECT: test(auth): add authentication test suite\nReason: Test files only = test type\n";
+/**
+ * System prompt for LLM - Phase 2 (with diff context)
+ */
+declare const SYSTEM_PROMPT_WITH_DIFF = "You are a git commit message generator. You now have the actual diff content for better context.\n\nCRITICAL OUTPUT FORMAT:\n- Return ONLY a valid JSON object\n- Do NOT wrap in markdown code blocks (no ```json, no ```)\n- Do NOT add any text before or after the JSON\n- Ensure all strings are properly escaped (use double quotes, escape backslashes and quotes)\n\nCRITICAL: USE IsNewFile METADATA TO DISTINGUISH NEW vs MODIFIED FILES:\n- Each file includes \"IsNewFile: true\" or \"IsNewFile: false\"\n- IsNewFile: false \u2192 File EXISTED BEFORE in git history \u2192 Use \"refactor\", \"fix\", or \"chore\"\n- IsNewFile: true \u2192 File is TRULY NEW (never existed) \u2192 Use \"feat\" for new functionality\n- NEVER use \"feat: add initial\" for files with \"IsNewFile: false\" - these are modifications!\n- For files marked \"[EXISTING FILE - was modified]\" in diff section \u2192 Use refactor/fix/chore, NOT feat\n\nCRITICAL GROUPING RULES:\n- Group files by LOGICAL CHANGE based on diff content\n- If files are changed for the same reason, they belong in ONE commit\n- IMPORTANT: Most files with status \"modified\" are REFACTORING, not new features\n- For refactoring: analyze the diff to understand what changed (renamed variables, restructured code, etc.)\n- Only use \"add initial\" or \"setup\" messages if you see truly NEW functionality being created from scratch\n- Target: 3-8 commits for <50 files, 5-12 commits for 50-150 files, 10-20 commits for 150+ files\n- Only separate genuinely DIFFERENT changes\n- CRITICAL: Each file must appear in EXACTLY ONE commit - no duplicates across commits!\n\nCRITICAL: FILE TYPE SHORTCUTS (check FIRST, before other rules):\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n\uD83D\uDEAB STOP! Check file extensions in DIFF BEFORE asking questions below:\n\n\uD83D\uDCDD ALL files in diff are *.md or *.mdx? \u2192 Type: docs (SKIP all questions below!)\n\uD83E\uDDEA ALL files in diff are test/, __tests__/, *.test.ts, *.spec.ts? \u2192 Type: test\n\u274C If ANY file has code (.ts, .js, .tsx, .jsx, .py, etc.) \u2192 Continue to questions below\n\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\nCRITICAL COMMIT TYPE CLASSIFICATION (same as Phase 1):\nFor EACH commit, answer these questions using the DIFF content:\n\n1. Does this change add NEW USER-VISIBLE BEHAVIOR?\n   - Look at the diff: is there a new API, feature, or capability?\n   - Check IsNewFile: false = likely refactor, true = might be feat\n   \u2192 YES = feat\n\n2. Does this change fix BROKEN functionality?\n   - Look for bug fixes, error handling corrections\n   \u2192 YES = fix\n\n3. Is this ONLY INTERNAL restructuring?\n   - Renaming, extracting functions, reorganizing code?\n   - IsNewFile: false with balanced +/- = refactor\n   \u2192 YES = refactor\n\nDEFAULT BIAS: When uncertain between feat and refactor, choose refactor!\n\nRules:\n\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n!!! RULE 0 (HIGHEST PRIORITY - OVERRIDES ALL OTHER RULES):                    !!!\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n!!!\n!!! IF a file has \"IsNewFile: false\" in its metadata, IT IS A MODIFIED FILE.\n!!! Modified files CANNOT be feat UNLESS they add ENTIRELY NEW user-facing APIs.\n!!!\n!!! BEFORE classifying ANY commit as \"feat\", CHECK ALL files' IsNewFile flags:\n!!! - If ANY file has IsNewFile: false \u2192 START with refactor/fix/chore\n!!! - If ALL files have IsNewFile: true \u2192 MIGHT be feat (check diff content)\n!!!\n!!! EXAMPLES OF MODIFIED FILES (IsNewFile: false) \u2192 NOT FEAT:\n!!! \u274C WRONG: Modified file adds new function \u2192 feat\n!!! \u2705 RIGHT: Modified file adds new function \u2192 refactor\n!!!\n!!! \u274C WRONG: Modified file adds new class \u2192 feat\n!!! \u2705 RIGHT: Modified file adds new class \u2192 refactor\n!!!\n!!! \u274C WRONG: Modified file adds new CLI command \u2192 feat\n!!! \u2705 RIGHT: Modified file adds new CLI command \u2192 refactor\n!!!\n!!! ONLY USE FEAT for modified files if:\n!!! - Diff shows COMPLETELY NEW public API endpoint (e.g., POST /api/new-resource)\n!!! - Diff shows COMPLETELY NEW product feature visible to end users\n!!!\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n\n1. Use conventional commits: feat, fix, refactor, chore, docs, test, build, ci, perf\n2. Group related files - number of commits should scale with file count (see grouping rules above)\n3. Each commit MUST include \"reasoning\" field based on actual diff content\n4. Message should be lowercase, imperative mood, no period at end\n5. breaking: true only for breaking API changes\n6. Add \"body\" with bullet points explaining the actual changes you see in the diff\n7. Scope should reflect the affected area (e.g., \"cli\", \"api\"), not individual files\n8. CRITICAL: If ALL files in a commit are being DELETED (only deletions in diff), use type \"chore\" or \"refactor\", NOT \"feat\"\n9. CRITICAL: If a commit is mostly deletions (>80% of lines are deletions), use \"refactor\" or \"chore\", NOT \"feat\"\n\n10. CRITICAL: WRITE INFORMATIVE COMMIT MESSAGES (look at diff content):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n    \u274C BAD (too generic):\n    - \"add feature\"\n    - \"update files\"\n    - \"refactor code\"\n    - \"fix bug\"\n    - \"improve implementation\"\n\n    \u2705 GOOD (specific, based on diff):\n    - \"add rate limiting middleware with Redis backend\"\n    - \"update API client to support pagination parameters\"\n    - \"refactor workflow executor to use async/await pattern\"\n    - \"fix memory leak in event listener cleanup\"\n    - \"improve error handling in authentication flow\"\n\n    Guidelines:\n    - Read the DIFF to understand WHAT changed\n    - Include specific component/module names from diff\n    - Mention the technology/pattern if relevant (Redis, JWT, factory pattern)\n    - For body: describe concrete changes, not just \"update X file\"\n    - Use technical terms that developers will understand\n\n12. CRITICAL: SPECIFIC TYPE DETECTION (check diff content BEFORE defaulting to refactor):\n    \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n    \uD83D\uDCDD docs: Documentation ONLY (no code logic changes)\n    \u2705 ALL files in diff are markdown (*.md, *.mdx) \u2192 docs (even if IsNewFile: true)\n    \u2705 Diff shows ONLY markdown content changes\n    \u2705 README.md, ADR files, API docs, benchmarks docs\n    \u2705 Files in docs/ or doc/ directory with only markdown\n    \u274C NOT docs if diff includes ANY code logic changes\n\n    **IMPORTANT**: If ALL files end with .md or .mdx \u2192 ALWAYS use docs, NEVER feat!\n\n    \uD83D\uDC1B fix: Corrects BROKEN functionality (look for bug-fix patterns in diff)\n    \u2705 Diff adds try-catch, null checks, validation\n    \u2705 Diff fixes incorrect calculations or logic errors\n    \u2705 Diff corrects typos in user-facing strings\n    \u2705 Commit message/body mentions \"fix\", \"bug\", \"error\", \"crash\"\n    \u274C NOT fix if adding new behavior\n\n    \uD83E\uDDEA test: Test files ONLY\n    \u2705 Diff shows files in test/, __tests__/, *.test.ts, *.spec.ts\n    \u2705 Adding test cases, updating test fixtures\n    \u274C NOT test if diff also changes source code\n\n13. IsNewFile flag (see RULE 0 above for detailed logic):\n    - IsNewFile: false \u2192 refactor/fix/chore/docs/test (NOT feat)\n    - IsNewFile: true \u2192 might be feat (check diff)\n\nEXACT JSON SCHEMA (copy this structure):\n{\n  \"commits\": [\n    {\n      \"id\": \"c1\",\n      \"type\": \"refactor\",\n      \"scope\": \"workflow\",\n      \"message\": \"extract job executor to separate class with dependency injection\",\n      \"body\": \"- create JobExecutor class with injectable dependencies\\n- move execution logic from runtime to executor\\n- add unit tests for isolated executor behavior\",\n      \"files\": [\"src/runtime/workflow-runtime.ts\", \"src/executor/job-executor.ts\", \"tests/executor.test.ts\"],\n      \"releaseHint\": \"patch\",\n      \"breaking\": false,\n      \"reasoning\": {\n        \"newBehavior\": false,\n        \"fixesBug\": false,\n        \"internalOnly\": true,\n        \"explanation\": \"Diff shows extraction of JobExecutor class from runtime - improves testability through dependency injection pattern, no user-facing changes\",\n        \"confidence\": 0.95\n      }\n    }\n  ]\n}\n\nVALID TYPE VALUES: feat, fix, refactor, chore, docs, test, build, ci, perf\nVALID RELEASEHINT VALUES: none, patch, minor, major\n\nEXAMPLE OUTPUT (based on actual diff content):\n{\n  \"commits\": [\n    {\n      \"id\": \"c1\",\n      \"type\": \"refactor\",\n      \"scope\": \"cli\",\n      \"message\": \"migrate command routing to builder pattern with fluent API\",\n      \"body\": \"- replace imperative routing with CommandRouterBuilder\\n- add fluent API for route registration (addRoute, withMiddleware)\\n- extract plugin discovery to PluginDiscoveryService class\\n- update integration tests for new routing pattern\",\n      \"files\": [\"src/commands/routing.ts\", \"src/commands/router-builder.ts\", \"src/plugins/discovery-service.ts\", \"tests/integration/routing.test.ts\"],\n      \"releaseHint\": \"patch\",\n      \"breaking\": false,\n      \"reasoning\": {\n        \"newBehavior\": false,\n        \"fixesBug\": false,\n        \"internalOnly\": true,\n        \"explanation\": \"IsNewFile: false for routing.ts (modified). Diff shows refactoring to builder pattern - improves code organization and testability without changing CLI behavior\",\n        \"confidence\": 0.95\n      }\n    }\n  ]\n}\n\nREAL-WORLD EXAMPLES WITH DIFF CONTEXT (learn from these):\n\nExample 1: Modified files - use diff to determine if feat or refactor\nDiff shows:\n  - Renamed variables (oldName \u2192 newName)\n  - Restructured functions (extract to separate modules)\n  - Updated imports and exports\n\u274C WRONG: feat(core): add new commit plan logic\n\u2705 CORRECT: refactor(core): restructure commit plan and prompt generation\nReason: Diff shows reorganization, not new functionality\n\nExample 2: New package - check IsNewFile flags in diff\nAll files show: IsNewFile: true, implements resource broker from scratch\n\u2705 CORRECT: feat(core-resource-broker): add resource broker for rate limiting\nReason: Genuinely new package with new functionality\n\nExample 3: Moved files - IsNewFile: false despite status \"added\"\nDiff shows: [EXISTING FILE - was modified], same content as before\n\u2705 CORRECT: refactor(analytics): reorganize analytics package structure\nReason: Files moved/reorganized, not newly created\n\nExample 4: Bug fix in existing files\nDiff shows: Fix null pointer exception, add validation check\n\u2705 CORRECT: fix(auth): handle null token in authentication middleware\nReason: Fixing broken functionality = fix, not feat\n\nExample 5: Documentation ONLY \u2192 docs, NOT chore or feat\nFiles:\n  - README.md (modified, +50/-20, IsNewFile: false)\n  - docs/API.md (modified, +30/-10, IsNewFile: false)\nDiff shows: Updated markdown content, improved examples, no code changes\n\u274C WRONG: chore(docs): update documentation\n\u274C WRONG: feat(docs): add documentation\n\u2705 CORRECT: docs: improve README and API documentation\nReason: ALL files are markdown = docs (regardless of IsNewFile)\n\nExample 5b: NEW documentation files \u2192 docs, NOT feat\nFiles:\n  - docs/benchmarks/README.md (added, +200/-0, IsNewFile: true)\n  - docs/benchmarks/RESULTS.md (added, +100/-0, IsNewFile: true)\nDiff shows: New markdown files with benchmarks documentation\n\u274C WRONG: feat(docs): add benchmarks documentation\n\u2705 CORRECT: docs(benchmarks): add benchmarks documentation\nReason: ALL files are .md = docs type (even if IsNewFile: true)\n\nExample 6: Bug fix with error handling \u2192 fix, NOT refactor\nFiles:\n  - src/api/auth.ts (modified, +15/-5, IsNewFile: false)\nDiff shows: Added try-catch around token validation, null check before access\n\u2705 CORRECT: fix(api): handle null token in authentication\nReason: Adds error handling to prevent crash = bug fix\n\nExample 7: Test files ONLY \u2192 test, NOT chore\nFiles:\n  - tests/auth.test.ts (added, +200/-0, IsNewFile: true)\n  - tests/helpers/mock-data.ts (added, +50/-0, IsNewFile: true)\nDiff shows: New test suites for authentication module\n\u2705 CORRECT: test(auth): add authentication test suite\nReason: Test files only = test type\n";
+/**
+ * Build prompt for LLM from file summaries (Phase 1)
+ */
+declare function buildPrompt(summaries: FileSummary[], recentCommits: string[]): string;
+/**
+ * Build prompt for LLM with diff content (Phase 2 - escalation)
+ */
+declare function buildPromptWithDiff(summaries: FileSummary[], diffs: Map<string, string>, recentCommits: string[]): string;
+/**
+ * Parsed LLM response with confidence assessment
+ */
+interface ParsedLLMResponse {
+    needsMoreContext: boolean;
+    requestedFiles: string[];
+    commits: CommitGroup[];
+    averageConfidence: number;
+}
+/**
+ * Parse LLM response into commit groups with confidence
+ */
+declare function parseResponse(response: string, summaries?: FileSummary[], patternAnalysis?: PatternAnalysis): ParsedLLMResponse;
+
+/**
+ * Heuristic commit plan generation (fallback when LLM unavailable)
+ */
+
+/**
+ * Generate commit plan using heuristics (no LLM)
+ *
+ * Enhanced grouping strategy:
+ * 1. Package.json changes + related files in same directory
+ * 2. Test files paired with their implementation
+ * 3. Remaining files grouped by directory + category
+ */
+declare function generateHeuristicPlan(summaries: FileSummary[]): CommitGroup[];
+
+export { SYSTEM_PROMPT as S, generateHeuristicPlan as a, buildPrompt as b, buildPromptWithDiff as c, SYSTEM_PROMPT_WITH_DIFF as d, generateCommitPlan as g, parseResponse as p };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { A as ApplyOptions, G as GenerateOptions, a as GitStatusWithStaleness, L as LLMCompleteFunction, P as PushOptions } from './types-CEjOl41u.js';
+export { F as FileDiff, j as detectCommitStyle, f as formatFileSummary, a as getAllChangedFiles, b as getCurrentBranch, d as getFileDiff, c as getFileSummaries, g as getGitStatus, e as getRecentCommits, h as hasChanges, i as isProtectedBranch } from './recent-commits-DD6LX2OI.js';
+export { S as SYSTEM_PROMPT, b as buildPrompt, g as generateCommitPlan, a as generateHeuristicPlan, p as parseResponse } from './heuristics-B6EsN9yD.js';
+export { applyCommitPlan, formatCommitMessage, pushCommits } from './applier/index.js';
+export { clearPlan, getCommitStoragePath, getCurrentPlanPath, getCurrentStatusPath, hasPlan, initStorage, listHistory, loadPlan, loadStatus, savePlan, saveToHistory } from './storage/index.js';
+export { ApplyResult, CommitGroup, CommitPlan, ConventionalType, FileSummary, GitStatus, GitStatusSnapshot, PushResult, ReleaseHint } from '@kb-labs/commit-contracts';