{"_id":"@api-extractor-tools/changeset-change-detector","_rev":"4-778502fb8dd7d6fbe1be041a59d3bd50","name":"@api-extractor-tools/changeset-change-detector","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0"},"versions":{"0.1.0-alpha.0":{"name":"@api-extractor-tools/changeset-change-detector","version":"0.1.0-alpha.0","keywords":["changesets","semantic-versioning","api-extractor"],"author":"","license":"MIT","_id":"@api-extractor-tools/changeset-change-detector@0.1.0-alpha.0","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"changeset-change-detector":"dist/cli.js"},"dist":{"shasum":"57207ce7691bf147c304a3ad64d8a08977c61e4f","tarball":"https://registry.npmjs.org/@api-extractor-tools/changeset-change-detector/-/changeset-change-detector-0.1.0-alpha.0.tgz","fileCount":45,"integrity":"sha512-Fl+eXRXOwqEyLZfy+0SBOzNUq1bklnaDcHu5G82h+yEP09NgRQnUSZMpu4FitjAzTP9AgEQt8HHyCYbYfXgnng==","signatures":[{"sig":"MEYCIQD7ZJXa5UiUbBqGrg80vG/7f/MGkdTaBCMO8yfTih1+gwIhAJm2JoUPnzlOPF8CBt2j5kltKL4LZnqmI6r5XyCcJ5Ks","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":166147},"main":"dist/index.js","_from":"file:api-extractor-tools-changeset-change-detector-0.1.0-alpha.0.tgz","types":"dist/changeset-change-detector-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/d02b3882c0ffbe7ced472bb437ae5686/api-extractor-tools-changeset-change-detector-0.1.0-alpha.0.tgz","_integrity":"sha512-Fl+eXRXOwqEyLZfy+0SBOzNUq1bklnaDcHu5G82h+yEP09NgRQnUSZMpu4FitjAzTP9AgEQt8HHyCYbYfXgnng==","_npmVersion":"10.8.2","description":"Changesets plugin that uses change-detector to automate version bump determination","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@changesets/read":"^0.6.5","@changesets/types":"^6.1.0","@changesets/write":"^0.4.0","@api-extractor-tools/change-detector":"0.1.0-alpha.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"5.8.3","@types/node":"^22.10.2","fixturify-project":"^7.1.3","@vitest/coverage-v8":"^4.0.15","@microsoft/api-extractor":"^7.55.1"},"_npmOperationalInternal":{"tmp":"tmp/changeset-change-detector_0.1.0-alpha.0_1765153641473_0.28356806104151056","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"@api-extractor-tools/changeset-change-detector","version":"0.1.0-alpha.1","keywords":["changesets","semantic-versioning","api-extractor"],"author":"","license":"MIT","_id":"@api-extractor-tools/changeset-change-detector@0.1.0-alpha.1","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"changeset-change-detector":"dist/cli.js"},"dist":{"shasum":"319059d3cf458e9d20a9e1265d4cdcbf4eea7035","tarball":"https://registry.npmjs.org/@api-extractor-tools/changeset-change-detector/-/changeset-change-detector-0.1.0-alpha.1.tgz","fileCount":45,"integrity":"sha512-TdRRQrsiTWPA/9YdWHZ1JWvASPRSd3sqSgVPRfJN4AxdwKJwbyc9WTPkvI0Hz5/DcqPdgZ6cdtw0SVwHzt+4wg==","signatures":[{"sig":"MEQCIBwQG6k0M0qa7Y4pVhTaAVdDlTNPcfRw2RbkZZDYNcwiAiA+rM5z2tgEChFlJOfbC3jdYFboNunrsfD9GPnRfggDRw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":164463},"main":"dist/index.js","_from":"file:api-extractor-tools-changeset-change-detector-0.1.0-alpha.1.tgz","types":"dist/changeset-change-detector-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/b4efb495a773d561b169c54f8cbe923a/api-extractor-tools-changeset-change-detector-0.1.0-alpha.1.tgz","_integrity":"sha512-TdRRQrsiTWPA/9YdWHZ1JWvASPRSd3sqSgVPRfJN4AxdwKJwbyc9WTPkvI0Hz5/DcqPdgZ6cdtw0SVwHzt+4wg==","_npmVersion":"10.8.2","description":"Changesets plugin that uses change-detector to automate version bump determination","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@changesets/read":"^0.6.5","@changesets/types":"^6.1.0","@changesets/write":"^0.4.0","@api-extractor-tools/change-detector":"0.1.0-alpha.1"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"5.8.3","@types/node":"^22.10.2","fixturify-project":"^7.1.3","@vitest/coverage-v8":"^4.0.15","@microsoft/api-extractor":"^7.55.1"},"_npmOperationalInternal":{"tmp":"tmp/changeset-change-detector_0.1.0-alpha.1_1765481036307_0.8619000107914663","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@api-extractor-tools/changeset-change-detector","version":"0.1.0-alpha.2","keywords":["changesets","semantic-versioning","api-extractor"],"author":"","license":"MIT","_id":"@api-extractor-tools/changeset-change-detector@0.1.0-alpha.2","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"changeset-change-detector":"dist/cli.js"},"dist":{"shasum":"9b08c0ff402f545173a54e4c97d7ead2d33f729e","tarball":"https://registry.npmjs.org/@api-extractor-tools/changeset-change-detector/-/changeset-change-detector-0.1.0-alpha.2.tgz","fileCount":46,"integrity":"sha512-N0ISokglK8F3Qk062x8uXMClGMwv4jttA1bZgXVnXdocTVW3dqHjcXZZJ6ltoNY7+WJXC71e3f3q0NT2dLvXEQ==","signatures":[{"sig":"MEQCIDUD6MqIB21AOsxmjHLABQZysReL1zyoC6eIQ1GBkGOSAiAQIADNUjG8y8KLJP4+GLfdO/Q2nv297NN8vmuTh4lNqA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":171015},"main":"dist/index.js","_from":"file:api-extractor-tools-changeset-change-detector-0.1.0-alpha.2.tgz","types":"dist/changeset-change-detector-public.d.ts","scripts":{"test":"vitest run && pnpm test:types","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","test:types":"tsd --files 'test/**/*.test-d.ts' --typings src/index.ts","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/4f4e850de34028940d49bd97799fc6a6/api-extractor-tools-changeset-change-detector-0.1.0-alpha.2.tgz","_integrity":"sha512-N0ISokglK8F3Qk062x8uXMClGMwv4jttA1bZgXVnXdocTVW3dqHjcXZZJ6ltoNY7+WJXC71e3f3q0NT2dLvXEQ==","_npmVersion":"10.8.2","description":"Changesets plugin that uses change-detector to automate version bump determination","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@changesets/read":"^0.6.5","@changesets/types":"^6.1.0","@changesets/write":"^0.4.0","@api-extractor-tools/change-detector":"0.1.0-alpha.2"},"_hasShrinkwrap":false,"devDependencies":{"tsd":"^0.33.0","vitest":"^4.0.15","typescript":"5.8.3","@types/node":"^22.10.2","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"},"_npmOperationalInternal":{"tmp":"tmp/changeset-change-detector_0.1.0-alpha.2_1767304041340_0.4201898097352592","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@api-extractor-tools/changeset-change-detector","version":"0.1.0","description":"Changesets plugin that uses change-detector to automate version bump determination","main":"dist/index.js","types":"dist/changeset-change-detector-public.d.ts","bin":{"changeset-change-detector":"dist/cli.js"},"keywords":["changesets","semantic-versioning","api-extractor"],"author":"","license":"MIT","dependencies":{"@changesets/read":"^0.6.5","@changesets/types":"^6.1.0","@changesets/write":"^0.4.0","@api-extractor-tools/change-detector":"0.1.0"},"devDependencies":{"@microsoft/api-extractor":"^7.55.1","@types/node":"^22.10.2","@vitest/coverage-v8":"^4.0.15","fixturify-project":"^7.1.3","tsd":"^0.33.0","typescript":"5.8.3","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 && pnpm test:types","test:types":"tsd --files 'test/**/*.test-d.ts' --typings src/index.ts","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/changeset-change-detector@0.1.0","_integrity":"sha512-hB+6Jp0j1Ut1IdlCZzc+tQURs0zA2AdEPbupaiZoiQ+UZKY9DQ+QNw26ogH+7KfEZ8wZYUU9cz4U0SfcXExlaQ==","_resolved":"/tmp/69bb6d970363a924cd8687d226ececf7/api-extractor-tools-changeset-change-detector-0.1.0.tgz","_from":"file:api-extractor-tools-changeset-change-detector-0.1.0.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-hB+6Jp0j1Ut1IdlCZzc+tQURs0zA2AdEPbupaiZoiQ+UZKY9DQ+QNw26ogH+7KfEZ8wZYUU9cz4U0SfcXExlaQ==","shasum":"f7429ed664ca4ab53150f63f9b4a10c28c815505","tarball":"https://registry.npmjs.org/@api-extractor-tools/changeset-change-detector/-/changeset-change-detector-0.1.0.tgz","fileCount":46,"unpackedSize":174179,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEdSryHqrNgRarwv264BxdcPxSsowQI46uV0/iRfuBHmAiEA8WEyWh2J4ocYv5zqYaQ/8DwyPcIBuzmpzuyZRT5FxbQ="}]},"_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/changeset-change-detector_0.1.0_1771015666365_0.4128910023890229"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-08T00:27:21.397Z","modified":"2026-02-13T20:47:46.957Z","0.1.0-alpha.0":"2025-12-08T00:27:21.623Z","0.1.0-alpha.1":"2025-12-11T19:23:56.479Z","0.1.0-alpha.2":"2026-01-01T21:47:21.496Z","0.1.0":"2026-02-13T20:47:46.540Z"},"license":"MIT","keywords":["changesets","semantic-versioning","api-extractor"],"description":"Changesets plugin that uses change-detector to automate version bump determination","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"readme":"# @api-extractor-tools/changeset-change-detector\n\n[![npm version](https://img.shields.io/npm/v/%40api-extractor-tools%2Fchangeset-change-detector)](https://www.npmjs.com/package/@api-extractor-tools/changeset-change-detector)\n\nAutomate semantic version bump decisions in your [Changesets](https://github.com/changesets/changesets) workflow by analyzing actual API changes in TypeScript declaration files.\n\n## The Problem\n\nWhen using Changesets, developers must manually determine whether a change is major, minor, or patch:\n\n```text\n🦋  Which packages should have a major bump?\n🦋  Which packages should have a minor bump?\n◉ @my-org/my-package  <-- How do I know which to pick?\n```\n\nThis is error-prone and inconsistent. A developer might accidentally mark a breaking change as `minor`, leading to broken consumers.\n\n## The Solution\n\nThis package integrates with [@api-extractor-tools/change-detector](../change-detector/) to **automatically analyze your TypeScript declaration files** and determine the correct semantic version bump based on actual API changes.\n\n| Change Type                | Examples                            | Version Bump |\n| -------------------------- | ----------------------------------- | ------------ |\n| Removing exports           | Deleted function, removed interface | **major**    |\n| Adding required parameters | `fn(a)` → `fn(a, b)`                | **major**    |\n| Narrowing types            | `string \\| number` → `string`       | **major**    |\n| Changing return types      | `(): string` → `(): number`         | **major**    |\n| Adding exports             | New function, new interface         | minor        |\n| Adding optional parameters | `fn(a)` → `fn(a, b?)`               | minor        |\n| Widening types             | `string` → `string \\| number`       | minor        |\n| Internal changes only      | Implementation details              | patch        |\n\n## Features\n\n- **Auto-generate changesets** — Analyzes API changes and creates changeset files with the correct version bump\n- **Validate changesets** — Verifies existing changesets match detected API changes (great for CI)\n- **Smart baseline detection** — Compares against published versions, main branch, or custom git refs\n- **Monorepo support** — Works with pnpm workspaces, analyzing all packages automatically\n- **Detailed summaries** — Auto-generates changeset descriptions from detected changes\n\n## Installation\n\n```bash\n# In a pnpm workspace\npnpm add -D @api-extractor-tools/changeset-change-detector\n\n# Or with npm\nnpm install --save-dev @api-extractor-tools/changeset-change-detector\n```\n\n### Prerequisites\n\n- Your packages must have TypeScript declaration files (`.d.ts`)\n- Changesets must be configured in your workspace (`.changeset/config.json`)\n- For best results, use [@microsoft/api-extractor](https://api-extractor.com/) to generate rolled-up declaration files\n\n## CLI Usage\n\n### Generate a Changeset\n\nAnalyze API changes and create a changeset file automatically:\n\n```bash\n# Interactive mode — shows preview and prompts for confirmation\nchangeset-change-detector generate\n\n# Non-interactive mode — auto-approve (useful for CI)\nchangeset-change-detector generate --yes\n\n# Compare against a specific git ref\nchangeset-change-detector generate --base main\n\n# Provide a custom summary\nchangeset-change-detector generate --summary \"Refactored authentication module\"\n```\n\n**Example output:**\n\n```text\n🔍 Analyzing API changes...\n\n📦 Changeset Preview\n══════════════════════════════════════════════════\n\nPackages:\n  🔴 @my-org/auth (major)\n  🟡 @my-org/utils (minor)\n\nSummary:\n──────────────────────────────────────────────────\n  **Breaking Changes:**\n  - Function `validateToken` was removed\n  - Required parameter added to `createSession`\n\n  **New Features/Additions:**\n  - Function `refreshToken` was added\n──────────────────────────────────────────────────\n\nCreate this changeset? (y/N):\n```\n\n### Validate Changesets\n\nVerify that existing changesets have appropriate version bumps (ideal for CI):\n\n```bash\n# Validate changesets against detected API changes\nchangeset-change-detector validate\n\n# Compare against a specific git ref\nchangeset-change-detector validate --base main\n\n# Strict mode — fail on warnings too\nchangeset-change-detector validate --strict\n```\n\n**Example output:**\n\n```text\n🔍 Validating changesets...\n\n❌ Changeset validation failed!\n\nErrors:\n  ❌ @my-org/auth: Changeset declares \"minor\" but detected changes require \"major\"\n  ❌ @my-org/utils: Package has API changes (minor) but no changeset\n\nWarnings:\n  ⚠️  @my-org/core: Breaking changes should have detailed descriptions\n\nSummary:\n  Packages with changesets: 1\n  Packages missing changesets: 1\n    - @my-org/utils\n```\n\n### CLI Reference\n\n```text\nchangeset-change-detector <command> [options]\n\nCommands:\n  generate    Analyze API changes and create a changeset file\n  validate    Validate existing changesets against detected API changes\n\nOptions:\n  --base, -b <ref>      Git ref to compare against (default: auto-detect)\n  --yes, -y             Skip confirmation prompts (for CI)\n  --strict              Fail validation on warnings (not just errors)\n  --summary, -s <text>  Custom summary for generated changeset\n  --help, -h            Show help\n  --version, -V         Show version\n```\n\n## Programmatic API\n\nYou can also use this package programmatically:\n\n```typescript\nimport {\n  analyzeWorkspace,\n  generateChangeset,\n  validateChangesets,\n} from '@api-extractor-tools/changeset-change-detector'\n\n// Analyze API changes in the workspace\nconst analysis = analyzeWorkspace({ baseRef: 'main' })\n\nconsole.log(\n  `Found ${analysis.packagesWithChanges.length} packages with changes`,\n)\n\nfor (const pkg of analysis.packagesWithChanges) {\n  console.log(`${pkg.package.name}: ${pkg.recommendedBump}`)\n}\n\n// Generate a changeset automatically\nconst result = await generateChangeset({\n  yes: true,\n  baseRef: 'main',\n})\n\nif (result.success && result.changesetPath) {\n  console.log(`Created: ${result.changesetPath}`)\n}\n\n// Validate existing changesets\nconst validation = await validateChangesets({ baseRef: 'main' })\n\nif (!validation.valid) {\n  console.error('Validation failed!')\n  process.exit(1)\n}\n```\n\n## CI Integration\n\n### GitHub Actions\n\nAdd changeset validation to your PR workflow:\n\n```yaml\nname: PR Checks\n\non:\n  pull_request:\n    branches: [main]\n\njobs:\n  validate-changesets:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0 # Needed for git history comparison\n\n      - uses: pnpm/action-setup@v2\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 20\n          cache: 'pnpm'\n\n      - run: pnpm install\n      - run: pnpm build\n\n      - name: Validate changesets\n        run: pnpm changeset-change-detector validate --base origin/main\n```\n\n### Workspace Integration\n\nAdd these scripts to your root `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"changeset:auto\": \"changeset-change-detector generate\",\n    \"changeset:validate\": \"changeset-change-detector validate\"\n  }\n}\n```\n\n## Baseline Strategy\n\nThe plugin determines what to compare against using this priority:\n\n1. **Explicit `--base <ref>`** — Use when you know exactly what to compare against\n2. **Published version tags** — Looks for tags like `@scope/package@1.0.0`\n3. **Main branch** — Falls back to comparing against `main`\n\nFor most workflows, the automatic detection works well. Use `--base` when you need precise control, such as comparing against a release branch.\n\n## How It Works\n\n```mermaid\nflowchart TB\n    subgraph workspace[\"Your Workspace\"]\n        pkgA[\"Package A<br/>dist/*.d.ts\"]\n        pkgB[\"Package B<br/>dist/*.d.ts\"]\n        pkgC[\"Package C<br/>dist/*.d.ts\"]\n\n        pkgA --> detector\n        pkgB --> detector\n        pkgC --> detector\n\n        detector[\"change-detector<br/>Compare .d.ts files<br/>against baseline\"]\n\n        detector --> classify[\"Classify Changes<br/>major/minor/patch\"]\n\n        classify --> generate[\"generate<br/>Create .md in<br/>.changeset/\"]\n        classify --> validate[\"validate<br/>Check existing<br/>changesets\"]\n    end\n```\n\n## Troubleshooting\n\n### \"No declaration file found\"\n\nEnsure your packages have:\n\n- A `types` field in `package.json` pointing to the `.d.ts` file\n- Or a `main` field with a corresponding `.d.ts` file next to it\n\n```json\n{\n  \"main\": \"dist/index.js\",\n  \"types\": \"dist/index.d.ts\"\n}\n```\n\n### \"Could not determine baseline\"\n\nThe tool couldn't find a git ref to compare against. Either:\n\n- Ensure you have git tags for published versions\n- Use `--base main` or another explicit ref\n\n### Changes not detected\n\nIf API changes aren't being detected:\n\n- Ensure declaration files are built (`pnpm build`)\n- Check that the baseline ref has the old declaration files\n- Verify your tsconfig produces declaration files\n\n## Related Packages\n\n- [@api-extractor-tools/change-detector](../change-detector/) — Core API change detection\n- [@changesets/cli](https://github.com/changesets/changesets) — Version management and changelogs\n\n## License\n\nMIT\n","readmeFilename":"README.md"}