{"_id":"@api-extractor-tools/change-detector-semantic-release-plugin","_rev":"4-7f127ea963c2b429ddafe9285765069e","name":"@api-extractor-tools/change-detector-semantic-release-plugin","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0"},"versions":{"0.1.0-alpha.0":{"name":"@api-extractor-tools/change-detector-semantic-release-plugin","version":"0.1.0-alpha.0","keywords":["semantic-release","semantic-versioning","api-extractor","change-detector"],"author":"","license":"MIT","_id":"@api-extractor-tools/change-detector-semantic-release-plugin@0.1.0-alpha.0","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"dist":{"shasum":"e5bd3e44f934a06fef7c8409976fedec61727e56","tarball":"https://registry.npmjs.org/@api-extractor-tools/change-detector-semantic-release-plugin/-/change-detector-semantic-release-plugin-0.1.0-alpha.0.tgz","fileCount":38,"integrity":"sha512-1Deh9ZYVfHbGYAEgPedrO9194DvLOUmK2TJUNA05nadhgFSwdBb3QBDgJvWxQDfz3E2O6ydyZlDofJAEhlzHag==","signatures":[{"sig":"MEQCIGEQL3Y7TXk+CdhNNx00YsB2LY5cdpJ2Sll68O/0Q8pmAiAUtWA1TOMcy+uT3WcOSlZATjRyCN1cY2JvwpkAS/wyVg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":150765},"main":"dist/index.js","_from":"file:api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.0.tgz","types":"dist/change-detector-semantic-release-plugin-public.d.ts","scripts":{"test":"vitest run","build":"tsc","check":"pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report","check:eslint":"eslint src","test:coverage":"vitest run --coverage","check:api-report":"api-extractor run","generate:api-report":"api-extractor run --local --verbose","check:typecheck-tests":"tsc -p test/tsconfig.json"},"_npmUser":{"name":"northm","email":"michael.l.north@gmail.com"},"_resolved":"/tmp/4c74375c1b95fcd531c746c5726ee9ca/api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.0.tgz","_integrity":"sha512-1Deh9ZYVfHbGYAEgPedrO9194DvLOUmK2TJUNA05nadhgFSwdBb3QBDgJvWxQDfz3E2O6ydyZlDofJAEhlzHag==","_npmVersion":"10.8.2","description":"semantic-release plugin that uses change-detector to validate and enhance version bumping","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@api-extractor-tools/change-detector":"0.1.0-alpha.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"^5.9.3","@types/node":"^22.10.2","semantic-release":"^24.2.0","fixturify-project":"^7.1.3","@vitest/coverage-v8":"^4.0.15","@microsoft/api-extractor":"^7.55.1"},"peerDependencies":{"semantic-release":">=20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/change-detector-semantic-release-plugin_0.1.0-alpha.0_1765153641437_0.6680380997750586","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"@api-extractor-tools/change-detector-semantic-release-plugin","version":"0.1.0-alpha.1","keywords":["semantic-release","semantic-versioning","api-extractor","change-detector"],"author":"","license":"MIT","_id":"@api-extractor-tools/change-detector-semantic-release-plugin@0.1.0-alpha.1","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"dist":{"shasum":"79e1e2dd3a25e508307fb6b4a717bd96618ddc56","tarball":"https://registry.npmjs.org/@api-extractor-tools/change-detector-semantic-release-plugin/-/change-detector-semantic-release-plugin-0.1.0-alpha.1.tgz","fileCount":40,"integrity":"sha512-Zy3QYGL38ZtxUqpOJ11+e21bz79urfU9LoJ5ioTtpyRTdJCP1mfB5aJugb9Z3aX9X/XYjugN+UEeuSpV9BWE1w==","signatures":[{"sig":"MEUCIQDdXqR/2AUHZBJ1PGz91jcmXeocY8dPvnaybVXD7+H4kAIgEyAqiuOzMgCurU8TzeibqgwuQuh5PIJzfUwtonJ72mg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":198375},"main":"dist/index.js","_from":"file:api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.1.tgz","types":"dist/change-detector-semantic-release-plugin-public.d.ts","scripts":{"test":"vitest run","build":"tsc","check":"pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report","check:eslint":"eslint src","test:coverage":"vitest run --coverage","check:api-report":"api-extractor run","generate:api-report":"api-extractor run --local --verbose","check:typecheck-tests":"tsc -p test/tsconfig.json"},"_npmUser":{"name":"northm","email":"michael.l.north@gmail.com"},"_resolved":"/tmp/914baeb388e1126cfc391517ec1a59cf/api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.1.tgz","_integrity":"sha512-Zy3QYGL38ZtxUqpOJ11+e21bz79urfU9LoJ5ioTtpyRTdJCP1mfB5aJugb9Z3aX9X/XYjugN+UEeuSpV9BWE1w==","_npmVersion":"10.8.2","description":"semantic-release plugin that uses change-detector to validate and enhance version bumping","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@api-extractor-tools/change-detector":"0.1.0-alpha.1"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"^5.9.3","@types/node":"^22.10.2","semantic-release":"^24.2.0","fixturify-project":"^7.1.3","@vitest/coverage-v8":"^4.0.15","@microsoft/api-extractor":"^7.55.1"},"peerDependencies":{"semantic-release":">=20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/change-detector-semantic-release-plugin_0.1.0-alpha.1_1765481035943_0.07724748738766496","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@api-extractor-tools/change-detector-semantic-release-plugin","version":"0.1.0-alpha.2","keywords":["semantic-release","semantic-versioning","api-extractor","change-detector"],"author":"","license":"MIT","_id":"@api-extractor-tools/change-detector-semantic-release-plugin@0.1.0-alpha.2","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"dist":{"shasum":"a6f58c1a90d2bc89d3fc7f9c1d14d5ab5dc71e5a","tarball":"https://registry.npmjs.org/@api-extractor-tools/change-detector-semantic-release-plugin/-/change-detector-semantic-release-plugin-0.1.0-alpha.2.tgz","fileCount":40,"integrity":"sha512-0biuzOyrHVyvaFmIhu5y+LeVLzvNkZ09zMoq5LMx0JHgXqMT4S2Ghdf4x7lEOf3qUaHALbRjYGaNvAXLmis0IA==","signatures":[{"sig":"MEUCIQC5n6Tkij8DuoOSUBQHQmrn5juBEjt5SBgwyp6Oae5fiQIganhH3QvDWEDntDJMXzgwExaP6cMfhh5VxSzzOuckx1A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":204742},"main":"dist/index.js","_from":"file:api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.2.tgz","types":"dist/change-detector-semantic-release-plugin-public.d.ts","scripts":{"test":"vitest run","build":"tsc && node ../declaration-file-normalizer/dist/cli.js dist/index.d.ts","check":"pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report","clean":"rm -rf dist","check:eslint":"eslint src test","test:coverage":"vitest run --coverage","check:api-report":"api-extractor run","generate:api-report":"api-extractor run --local --verbose","check:typecheck-tests":"tsc -p test/tsconfig.json"},"_npmUser":{"name":"northm","email":"michael.l.north@gmail.com"},"_resolved":"/tmp/a2e900bd419c7d3d182110c06c1837c9/api-extractor-tools-change-detector-semantic-release-plugin-0.1.0-alpha.2.tgz","_integrity":"sha512-0biuzOyrHVyvaFmIhu5y+LeVLzvNkZ09zMoq5LMx0JHgXqMT4S2Ghdf4x7lEOf3qUaHALbRjYGaNvAXLmis0IA==","_npmVersion":"10.8.2","description":"semantic-release plugin that uses change-detector to validate and enhance version bumping","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@api-extractor-tools/change-detector":"0.1.0-alpha.2"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"^5.9.3","@types/node":"^22.10.2","semantic-release":"^24.2.0","fixturify-project":"^7.1.3","@vitest/coverage-v8":"^4.0.15","@microsoft/api-extractor":"^7.55.1","@api-extractor-tools/declaration-file-normalizer":"0.0.1-alpha.2"},"peerDependencies":{"semantic-release":">=20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/change-detector-semantic-release-plugin_0.1.0-alpha.2_1767304041032_0.27586776998857077","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@api-extractor-tools/change-detector-semantic-release-plugin","version":"0.1.0","description":"semantic-release plugin that uses change-detector to validate and enhance version bumping","main":"dist/index.js","types":"dist/change-detector-semantic-release-plugin-public.d.ts","keywords":["semantic-release","semantic-versioning","api-extractor","change-detector"],"author":"","license":"MIT","dependencies":{"@api-extractor-tools/change-detector":"0.1.0"},"peerDependencies":{"semantic-release":">=20.0.0"},"devDependencies":{"@microsoft/api-extractor":"^7.55.1","@types/node":"^22.10.2","fixturify-project":"^7.1.3","semantic-release":"^24.2.0","typescript":"^5.9.3","@vitest/coverage-v8":"^4.0.15","vitest":"^4.0.15","@api-extractor-tools/declaration-file-normalizer":"0.1.0"},"scripts":{"clean":"rm -rf dist","build":"tsc && node ../declaration-file-normalizer/dist/cli.js dist/index.d.ts","generate:api-report":"api-extractor run --local --verbose","test":"vitest run","test:coverage":"vitest run --coverage","check":"pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report","check:eslint":"eslint src test","check:typecheck-tests":"tsc -p test/tsconfig.json","check:api-report":"api-extractor run"},"_id":"@api-extractor-tools/change-detector-semantic-release-plugin@0.1.0","_integrity":"sha512-Dqgf+z7jxC+anRaDYrYOV2q6bzfEBLb9LsC7BIkQRCFiTvUjHyrStluwJ9CIB3CzEHJdDqHKSn6aArbvwZW/9A==","_resolved":"/tmp/1cea462ea638293633c868b8e37120ce/api-extractor-tools-change-detector-semantic-release-plugin-0.1.0.tgz","_from":"file:api-extractor-tools-change-detector-semantic-release-plugin-0.1.0.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Dqgf+z7jxC+anRaDYrYOV2q6bzfEBLb9LsC7BIkQRCFiTvUjHyrStluwJ9CIB3CzEHJdDqHKSn6aArbvwZW/9A==","shasum":"24fbfc969577ca704f3fa8554e17a0e18b9a9874","tarball":"https://registry.npmjs.org/@api-extractor-tools/change-detector-semantic-release-plugin/-/change-detector-semantic-release-plugin-0.1.0.tgz","fileCount":40,"unpackedSize":208357,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDYJkjiQ09nBfDASzo1GplhTvNw9uSQS84PfKccbcpxBwIhANHIdATFrHpLp0joEKFnn6jIwfuJappa2nipnMg8/IJe"}]},"_npmUser":{"name":"northm","email":"michael.l.north@gmail.com"},"directories":{},"maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/change-detector-semantic-release-plugin_0.1.0_1771015666425_0.148497917475239"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-08T00:27:21.378Z","modified":"2026-02-13T20:47:46.716Z","0.1.0-alpha.0":"2025-12-08T00:27:21.584Z","0.1.0-alpha.1":"2025-12-11T19:23:56.112Z","0.1.0-alpha.2":"2026-01-01T21:47:21.200Z","0.1.0":"2026-02-13T20:47:46.590Z"},"license":"MIT","keywords":["semantic-release","semantic-versioning","api-extractor","change-detector"],"description":"semantic-release plugin that uses change-detector to validate and enhance version bumping","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"readme":"# @api-extractor-tools/change-detector-semantic-release-plugin\n\n[![npm version](https://img.shields.io/npm/v/%40api-extractor-tools%2Fchange-detector-semantic-release-plugin)](https://www.npmjs.com/package/@api-extractor-tools/change-detector-semantic-release-plugin)\n\nA [semantic-release](https://semantic-release.gitbook.io/) plugin that uses `@api-extractor-tools/change-detector` to validate and enhance version bumping based on actual API changes in TypeScript declaration files.\n\n## Features\n\n- **Version Bump Validation**: Ensures that commit-derived version bumps match (or exceed) what the actual API changes require\n- **API Change Detection**: Analyzes TypeScript `.d.ts` files to detect breaking changes, new features, and modifications\n- **Enhanced Release Notes**: Automatically adds detailed API change information to release notes\n- **Multiple Modes**: Supports validate, override, and advisory modes for different workflows\n\n## Installation\n\n```bash\nnpm install @api-extractor-tools/change-detector-semantic-release-plugin --save-dev\n# or\npnpm add @api-extractor-tools/change-detector-semantic-release-plugin --save-dev\n```\n\n## Usage\n\nAdd the plugin to your semantic-release configuration:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"validate\",\n        \"declarationPath\": \"./dist/index.d.ts\",\n        \"includeAPIChangesInNotes\": true\n      }\n    ],\n    \"@semantic-release/release-notes-generator\",\n    \"@semantic-release/npm\",\n    \"@semantic-release/github\"\n  ]\n}\n```\n\n## Configuration\n\n| Option                     | Type                                     | Default      | Description                                                                                           |\n| -------------------------- | ---------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |\n| `mode`                     | `'validate' \\| 'override' \\| 'advisory'` | `'validate'` | Operating mode for the plugin                                                                         |\n| `declarationPath`          | `string`                                 | `null`       | Path to the declaration file (relative or absolute). If not provided, uses `package.json` types field |\n| `apiExtractorConfig`       | `string`                                 | `null`       | Path to api-extractor.json config file                                                                |\n| `includeAPIChangesInNotes` | `boolean`                                | `true`       | Whether to add API changes to release notes                                                           |\n| `failOnMismatch`           | `boolean`                                | `true`       | Fail release when version bump doesn't match API changes (validate mode only)                         |\n| `baseRef`                  | `string`                                 | `null`       | Git ref to use as baseline (defaults to last release tag or main)                                     |\n\n### Modes\n\n#### Validate Mode (Default)\n\nValidates that the commit-derived version bump is sufficient for the detected API changes. Fails the release if:\n\n- A `patch` bump is proposed but breaking changes are detected (requires `major`)\n- A `minor` bump is proposed but breaking changes are detected (requires `major`)\n\n```json\n{\n  \"mode\": \"validate\",\n  \"failOnMismatch\": true\n}\n```\n\n**Use when:** You want to enforce consistency between commit messages and actual API changes.\n\n#### Override Mode\n\nIgnores commit messages and uses the API analysis to determine the version bump automatically.\n\n```json\n{\n  \"mode\": \"override\"\n}\n```\n\n**Use when:** You trust the API analysis more than commit messages and want fully automated versioning.\n\n#### Advisory Mode\n\nWarns about version bump mismatches but doesn't fail the release. Useful for gradual adoption.\n\n```json\n{\n  \"mode\": \"advisory\"\n}\n```\n\n**Use when:** You're evaluating the plugin or have a gradual migration strategy.\n\n## Common Pitfalls\n\n### 1. Running semantic-release Before Building\n\n**Problem:**\n\n```bash\nnpm run semantic-release  # Declaration files don't exist yet!\n```\n\n**Solution:**\n\n```json\n{\n  \"scripts\": {\n    \"release\": \"npm run build && npx semantic-release\"\n  }\n}\n```\n\nOr in CI:\n\n```yaml\n- run: npm run build\n- run: npx semantic-release\n```\n\n### 2. Incorrect Plugin Order\n\n**Problem:**\n\n```json\n{\n  \"plugins\": [\n    \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n    \"@semantic-release/commit-analyzer\" // ❌ Wrong order!\n  ]\n}\n```\n\n**Solution:**\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    \"@api-extractor-tools/change-detector-semantic-release-plugin\" // ✅ After commit-analyzer\n  ]\n}\n```\n\n### 3. Multiple Declaration Files Not Consolidated\n\n**Problem:** Your package exports from multiple `.d.ts` files, and the plugin only checks one.\n\n**Solution:** Use a bundler or API Extractor to create a single consolidated declaration file:\n\n```json\n{\n  \"main\": \"dist/index.js\",\n  \"types\": \"dist/index.d.ts\" // Single entry point\n}\n```\n\n### 4. Using Shallow Git Clones in CI\n\n**Problem:** Shallow clones don't include tags/history needed for baseline comparison.\n\n**Solution:**\n\n```yaml\n- uses: actions/checkout@v4\n  with:\n    fetch-depth: 0 # Get full git history\n```\n\n### 5. Not Handling Internal vs. Public APIs\n\n**Problem:** The plugin detects changes in internal APIs that shouldn't affect versioning.\n\n**Solution:** Use API Extractor to mark APIs as `@internal` and exclude them from the public declaration file:\n\n```typescript\n/**\n * Public API\n * @public\n */\nexport function publicFunction(): void {}\n\n/**\n * Internal implementation detail\n * @internal\n */\nexport function _internalHelper(): void {} // Won't be in public .d.ts\n```\n\n### 6. Expecting Implementation Changes to Trigger Bumps\n\n**Problem:** You changed implementation code but not the types, and no version bump occurs.\n\n**Solution:** This is by design. Use conventional commits for implementation-only changes:\n\n```bash\ngit commit -m \"fix: improve performance of calculation\"\n```\n\n## Advanced Configuration Examples\n\n### Monorepo Setup\n\nFor monorepos with multiple packages:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"validate\",\n        \"declarationPath\": \"packages/my-package/dist/index.d.ts\",\n        \"includeAPIChangesInNotes\": true\n      }\n    ],\n    \"@semantic-release/release-notes-generator\",\n    \"@semantic-release/npm\"\n  ]\n}\n```\n\n### With API Extractor\n\nIf using Microsoft's API Extractor:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"validate\",\n        \"apiExtractorConfig\": \"./api-extractor.json\",\n        \"includeAPIChangesInNotes\": true\n      }\n    ],\n    \"@semantic-release/release-notes-generator\",\n    \"@semantic-release/npm\",\n    \"@semantic-release/github\"\n  ]\n}\n```\n\n### Strict Validation for Libraries\n\nFor library projects where API stability is critical:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"validate\",\n        \"failOnMismatch\": true,\n        \"includeAPIChangesInNotes\": true\n      }\n    ],\n    \"@semantic-release/release-notes-generator\",\n    [\n      \"@semantic-release/npm\",\n      {\n        \"npmPublish\": true\n      }\n    ]\n  ]\n}\n```\n\n### Gradual Adoption\n\nFor projects adopting API-based versioning gradually:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"advisory\",\n        \"includeAPIChangesInNotes\": true,\n        \"failOnMismatch\": false\n      }\n    ],\n    \"@semantic-release/release-notes-generator\",\n    \"@semantic-release/npm\"\n  ]\n}\n```\n\n### Custom Baseline\n\nTo compare against a specific git reference:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"validate\",\n        \"baseRef\": \"production\",\n        \"declarationPath\": \"./dist/index.d.ts\"\n      }\n    ],\n    \"@semantic-release/release-notes-generator\"\n  ]\n}\n```\n\n### Private Packages (No Release Notes)\n\nFor private packages where you don't need detailed API notes in GitHub:\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    [\n      \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n      {\n        \"mode\": \"override\",\n        \"includeAPIChangesInNotes\": false\n      }\n    ],\n    \"@semantic-release/npm\"\n  ]\n}\n```\n\n## Example Output\n\n### Validation Failure\n\n```text\n╔══════════════════════════════════════════════════════════════════╗\n║              API CHANGE VALIDATION FAILED                        ║\n╚══════════════════════════════════════════════════════════════════╝\n\nProposed minor bump is insufficient. API analysis detected major-level changes.\n\nBreaking changes detected:\n  • Function oldFunction was removed\n  • Required parameter added to authenticate()\n\nTo fix this:\n  1. Update your commit messages to reflect the major changes\n  2. Or set \"mode\": \"override\" to use API-detected version\n  3. Or set \"mode\": \"advisory\" to proceed with warnings only\n```\n\n### Enhanced Release Notes\n\n```markdown\n## API Changes\n\n### Breaking Changes\n\n- **function** `oldFunction`: Function oldFunction was removed\n\n### Added Exports\n\n- **function** `function newHelper(): string`\n- **interface** `NewInterface`\n\n### Modified Exports\n\n- **function** `authenticate`: Added optional parameter\n  - Before: `function authenticate(user: string): Promise<Token>`\n  - After: `function authenticate(user: string, options?: AuthOptions): Promise<Token>`\n\n### Summary\n\n- **Added**: 2\n- **Removed**: 1\n- **Modified**: 1\n```\n\n## Programmatic Usage\n\n```typescript\nimport {\n  analyzeAPIChanges,\n  validateVersionBump,\n  formatAPIChangesAsMarkdown,\n  resolveConfig,\n} from '@api-extractor-tools/change-detector-semantic-release-plugin'\n\n// Resolve configuration\nconst config = resolveConfig({\n  declarationPath: './dist/index.d.ts',\n})\n\n// Analyze API changes\nconst analysis = analyzeAPIChanges(process.cwd(), config, {\n  gitTag: 'v1.0.0',\n  version: '1.0.0',\n})\n\nconsole.log(analysis.recommendedBump) // 'major' | 'minor' | 'patch' | 'none'\n\n// Validate a proposed version bump\nconst validation = validateVersionBump('minor', analysis, 'validate')\nconsole.log(validation.valid) // true or false\nconsole.log(validation.message)\n\n// Generate release notes\nif (analysis.report) {\n  const notes = formatAPIChangesAsMarkdown(analysis.report)\n  console.log(notes)\n}\n```\n\n## How It Works\n\n1. **verifyConditions**: Checks that declaration files exist and configuration is valid\n2. **analyzeCommits**: Compares current declaration file against the baseline (last release tag) using `change-detector`\n3. **verifyRelease**: Validates that the proposed version bump matches the detected API changes\n4. **generateNotes**: Appends detailed API change information to the release notes\n\n## Requirements\n\n- Node.js 20+\n- Your package must be built with TypeScript declaration files before running semantic-release\n- A git repository with release tags (for baseline comparison)\n\n## Troubleshooting\n\n### \"Could not find declaration file\"\n\n**Problem**: The plugin can't locate your TypeScript declaration files.\n\n**Solutions**:\n\n1. Ensure your package is built before semantic-release runs:\n\n   ```json\n   {\n     \"scripts\": {\n       \"semantic-release\": \"npm run build && semantic-release\"\n     }\n   }\n   ```\n\n2. Explicitly specify the declaration path:\n\n   ```json\n   {\n     \"plugins\": [\n       [\n         \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n         {\n           \"declarationPath\": \"./dist/index.d.ts\"\n         }\n       ]\n     ]\n   }\n   ```\n\n3. Add the `types` field to your `package.json`:\n\n   ```json\n   {\n     \"types\": \"./dist/index.d.ts\"\n   }\n   ```\n\n### Version Bump Mismatch Errors\n\n**Problem**: Release fails with \"API CHANGE VALIDATION FAILED\"\n\n**Explanation**: Your commits suggest a smaller version bump than what the API changes require.\n\n**Solutions**:\n\n1. **Update your commit messages** to reflect the actual changes:\n\n   ```bash\n   # For breaking changes:\n   git commit -m \"feat!: remove deprecated API\"\n\n   # For new features:\n   git commit -m \"feat: add new helper function\"\n\n   # For bug fixes:\n   git commit -m \"fix: correct return type\"\n   ```\n\n2. **Use override mode** to let the plugin determine the version automatically:\n\n   ```json\n   {\n     \"mode\": \"override\"\n   }\n   ```\n\n3. **Use advisory mode** to proceed with warnings:\n\n   ```json\n   {\n     \"mode\": \"advisory\"\n   }\n   ```\n\n### \"No baseline found\" or New Package Issues\n\n**Problem**: Plugin reports it can't find a baseline for comparison.\n\n**Explanation**: This is normal for:\n\n- Initial releases\n- First time using the plugin\n- Repositories without release tags\n\n**Solutions**:\n\n1. For new packages, the plugin will automatically detect this and recommend a `minor` release in override mode\n2. In validate mode, proceed normally - the plugin won't block new packages\n3. If you have releases but no tags, create tags for past releases:\n\n   ```bash\n   git tag v1.0.0 <commit-hash>\n   git push --tags\n   ```\n\n### Plugin Not Running During Release\n\n**Problem**: The plugin doesn't appear to be executing.\n\n**Solutions**:\n\n1. Ensure the plugin is listed in the correct order (after `@semantic-release/commit-analyzer`):\n\n   ```json\n   {\n     \"plugins\": [\n       \"@semantic-release/commit-analyzer\",\n       \"@api-extractor-tools/change-detector-semantic-release-plugin\",\n       \"@semantic-release/release-notes-generator\"\n     ]\n   }\n   ```\n\n2. Check that declaration files exist before the plugin runs\n3. Review semantic-release logs for errors during plugin execution\n\n### False Positive Breaking Changes\n\n**Problem**: The plugin detects breaking changes that you don't consider breaking.\n\n**Explanation**: The plugin uses strict semantic versioning rules based on TypeScript's type system.\n\n**Solutions**:\n\n1. Use advisory mode if your package has different versioning requirements:\n\n   ```json\n   {\n     \"mode\": \"advisory\"\n   }\n   ```\n\n2. Consider if the changes are truly non-breaking from a consumer perspective\n3. Use `@deprecated` JSDoc tags to mark symbols before removing them\n\n### CI/CD Integration Issues\n\n**Problem**: Plugin works locally but fails in CI.\n\n**Solutions**:\n\n1. Ensure your build step runs before semantic-release in CI:\n\n   ```yaml\n   # GitHub Actions example\n   - name: Build\n     run: npm run build\n   - name: Release\n     run: npx semantic-release\n   ```\n\n2. Verify git history is available (some CI systems use shallow clones):\n\n   ```yaml\n   - uses: actions/checkout@v4\n     with:\n       fetch-depth: 0 # Get full history\n   ```\n\n3. Ensure tags are available:\n\n   ```yaml\n   - run: git fetch --tags\n   ```\n\n## FAQ\n\n### Q: Can I use this with JavaScript projects?\n\n**A:** The plugin requires TypeScript declaration files (`.d.ts`). If you have a JavaScript project with generated declaration files (via JSDoc or manual `.d.ts` files), it will work.\n\n### Q: What happens if I change the implementation but not the types?\n\n**A:** The plugin only analyzes TypeScript declaration files, so implementation-only changes won't trigger version bumps. Use conventional commits to specify the version bump in these cases.\n\n### Q: Can I customize what counts as a breaking change?\n\n**A:** Not directly. The plugin uses the underlying `@api-extractor-tools/change-detector` library which follows strict semantic versioning rules. However, you can:\n\n- Use `advisory` mode to receive warnings without blocking releases\n- Manually override version bumps in your commit messages\n- Use `override` mode with post-processing\n\n### Q: Does this replace conventional commits?\n\n**A:** No, it complements them:\n\n- In `validate` mode: Conventional commits determine the version, and the plugin validates it\n- In `override` mode: The plugin determines the version based on API changes, ignoring commits\n- In `advisory` mode: Conventional commits determine the version, and the plugin provides warnings\n\n### Q: What about monorepos?\n\n**A:** The plugin works in monorepos. Each package is analyzed independently. Ensure:\n\n- Each package has its own `declarationPath` configuration\n- semantic-release is configured per-package (or using a tool like `semantic-release-monorepo`)\n\n### Q: Can I use this without semantic-release?\n\n**A:** Yes! The plugin exports utility functions for programmatic use:\n\n```typescript\nimport { analyzeAPIChanges } from '@api-extractor-tools/change-detector-semantic-release-plugin'\n\nconst analysis = analyzeAPIChanges(process.cwd(), config, lastRelease)\n```\n\n### Q: How do I migrate from conventional commits to API-based versioning?\n\n**A:** Gradual migration path:\n\n1. Start with `advisory` mode to see warnings without breaking your release process\n2. Review and adjust your commit message practices based on warnings\n3. Switch to `validate` mode once comfortable\n4. Optionally move to `override` mode for full API-driven versioning\n\n### Q: Does the plugin support pre-release versions?\n\n**A:** The plugin focuses on detecting the release type (`major`, `minor`, `patch`). Pre-release tags are handled by semantic-release's normal flow.\n\n### Q: What if my API changes are in multiple files?\n\n**A:** Currently, the plugin analyzes a single declaration file (typically a bundled/rolled-up `.d.ts`). For best results:\n\n- Use API Extractor or a bundler to create a single entry point\n- Configure the `declarationPath` to point to this bundled file\n\n## Related\n\n- [@api-extractor-tools/change-detector](../change-detector) - The underlying API change detection library\n- [@api-extractor-tools/changeset-change-detector](../changeset-change-detector) - Similar plugin for Changesets\n\n## License\n\nMIT\n","readmeFilename":"README.md"}