{"_id":"@api-extractor-tools/module-declaration-merger","_rev":"4-184190d8d26a142a622d6e3ff3d1e9bd","name":"@api-extractor-tools/module-declaration-merger","dist-tags":{"latest":"0.1.0","alpha":"0.0.2-alpha.1"},"versions":{"0.0.1":{"name":"@api-extractor-tools/module-declaration-merger","version":"0.0.1","keywords":[],"author":"","license":"MIT","_id":"@api-extractor-tools/module-declaration-merger@0.0.1","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"module-declaration-merger":"dist/cli.js"},"dist":{"shasum":"f644ec2a5d02e0c31a3371faa3ccf92b8b7324a1","tarball":"https://registry.npmjs.org/@api-extractor-tools/module-declaration-merger/-/module-declaration-merger-0.0.1.tgz","fileCount":61,"integrity":"sha512-IrV3YsesfK3S9K/PCe9euC4WsrnjUOIpOvpSjH5cOehJh9uaStkU4V7ng2XBqIL3sdnZMfd9MxfnYH/HFY5l7A==","signatures":[{"sig":"MEYCIQCDFc0IB5rK77fnhhbhpCiKS1WnW2aIAtGA5S5+p6f/PwIhANXypt38Smg1/mSRIQI6jnhIg80XuuSig25icYWT7G6d","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":306017},"main":"dist/index.js","_from":"file:api-extractor-tools-module-declaration-merger-0.0.1.tgz","types":"dist/index.d.ts","scripts":{"test":"vitest run","build":"tsc","check":"pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report","check:eslint":"eslint src","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/a6ec81900433ee2dbfc64c739375b232/api-extractor-tools-module-declaration-merger-0.0.1.tgz","_integrity":"sha512-IrV3YsesfK3S9K/PCe9euC4WsrnjUOIpOvpSjH5cOehJh9uaStkU4V7ng2XBqIL3sdnZMfd9MxfnYH/HFY5l7A==","_npmVersion":"10.8.2","description":"Merges ambient module declarations into api-extractor rollup files","directories":{},"_nodeVersion":"20.19.6","dependencies":{"fast-glob":"^3.3.2","@microsoft/tsdoc":"^0.16.0","@microsoft/api-extractor":"^7.52.8","@microsoft/api-extractor-model":"^7.30.6"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.15","typescript":"^5.9.3","@types/node":"^22.10.2","fixturify-project":"^7.1.3"},"_npmOperationalInternal":{"tmp":"tmp/module-declaration-merger_0.0.1_1765046411168_0.6490944886898953","host":"s3://npm-registry-packages-npm-production"}},"0.0.2-alpha.0":{"name":"@api-extractor-tools/module-declaration-merger","version":"0.0.2-alpha.0","keywords":[],"author":"","license":"MIT","_id":"@api-extractor-tools/module-declaration-merger@0.0.2-alpha.0","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"module-declaration-merger":"dist/cli.js"},"dist":{"shasum":"24af5a71e2ebf251b1c1a2aeeb3dd4003c790ff6","tarball":"https://registry.npmjs.org/@api-extractor-tools/module-declaration-merger/-/module-declaration-merger-0.0.2-alpha.0.tgz","fileCount":63,"integrity":"sha512-5K41kDL0oQjTf1HU7ZnS7/GVmwkSGx6spHx59G5LqIklTeHnpcszq+02wYUi0YEw2357mZ7gLZOnGdZ885MXag==","signatures":[{"sig":"MEUCIQC1yGzKHoGnMQJAynnjT7txdknjIjoLrx8cup5LAFjI6wIgbnXKiSiSEmGwQwafdI+jp9ZXh9X/dPsQPdg+zKBib9A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":303355},"main":"dist/index.js","_from":"file:api-extractor-tools-module-declaration-merger-0.0.2-alpha.0.tgz","types":"dist/module-declaration-merger-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/c67f34fdb2087d52154aacbc97edd0e2/api-extractor-tools-module-declaration-merger-0.0.2-alpha.0.tgz","_integrity":"sha512-5K41kDL0oQjTf1HU7ZnS7/GVmwkSGx6spHx59G5LqIklTeHnpcszq+02wYUi0YEw2357mZ7gLZOnGdZ885MXag==","_npmVersion":"10.8.2","description":"Merges ambient module declarations into api-extractor rollup files","directories":{},"_nodeVersion":"20.19.6","dependencies":{"fast-glob":"^3.3.2","@microsoft/tsdoc":"^0.16.0","@microsoft/api-extractor":"^7.52.8","@microsoft/api-extractor-model":"^7.30.6"},"_hasShrinkwrap":false,"readmeFilename":"README.md","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"},"_npmOperationalInternal":{"tmp":"tmp/module-declaration-merger_0.0.2-alpha.0_1765153641838_0.8447771523089151","host":"s3://npm-registry-packages-npm-production"}},"0.0.2-alpha.1":{"name":"@api-extractor-tools/module-declaration-merger","version":"0.0.2-alpha.1","keywords":[],"author":"","license":"MIT","_id":"@api-extractor-tools/module-declaration-merger@0.0.2-alpha.1","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"bin":{"module-declaration-merger":"dist/cli.js"},"dist":{"shasum":"463980c3ad1403bbb2abc5a843af783175d5c0e5","tarball":"https://registry.npmjs.org/@api-extractor-tools/module-declaration-merger/-/module-declaration-merger-0.0.2-alpha.1.tgz","fileCount":64,"integrity":"sha512-da0c9VFtB0TFhcirLh7v3DphJqgpUz5NLSOTBLxAwni0BzapM+TEcuHOCjoMB1Cn4+5e2fULQqR0Je1S9FOSDw==","signatures":[{"sig":"MEUCIQDTdB035PeMi/XG0nbP3dlLw6pxXhs0Ngm0Uqug3E38pQIgZogcklOlUcaABe6dNcg+bxXUkj66dUw0dY8FEIQZbHE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":305866},"main":"dist/index.js","_from":"file:api-extractor-tools-module-declaration-merger-0.0.2-alpha.1.tgz","types":"dist/module-declaration-merger-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/47a57cb3c4e182f66da03d7cc5acf288/api-extractor-tools-module-declaration-merger-0.0.2-alpha.1.tgz","_integrity":"sha512-da0c9VFtB0TFhcirLh7v3DphJqgpUz5NLSOTBLxAwni0BzapM+TEcuHOCjoMB1Cn4+5e2fULQqR0Je1S9FOSDw==","_npmVersion":"10.8.2","description":"Merges ambient module declarations into api-extractor rollup files","directories":{},"_nodeVersion":"20.19.6","dependencies":{"fast-glob":"^3.3.2","@microsoft/tsdoc":"^0.16.0","@microsoft/api-extractor":"^7.52.8","@microsoft/api-extractor-model":"^7.30.6"},"_hasShrinkwrap":false,"readmeFilename":"README.md","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","@api-extractor-tools/declaration-file-normalizer":"0.0.1-alpha.2"},"_npmOperationalInternal":{"tmp":"tmp/module-declaration-merger_0.0.2-alpha.1_1767304041569_0.021189547437738376","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@api-extractor-tools/module-declaration-merger","version":"0.1.0","description":"Merges ambient module declarations into api-extractor rollup files","main":"dist/index.js","types":"dist/module-declaration-merger-public.d.ts","bin":{"module-declaration-merger":"dist/cli.js"},"keywords":[],"author":"","license":"MIT","dependencies":{"@microsoft/api-extractor":"^7.52.8","@microsoft/api-extractor-model":"^7.30.6","@microsoft/tsdoc":"^0.16.0","fast-glob":"^3.3.2"},"devDependencies":{"@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/module-declaration-merger@0.1.0","_integrity":"sha512-+676mdgJ/wYPr4gyBZeXHaFw/qUyXTaw5HmEA+1PEGd1uQEJS4dkX/OTxsNlCBztu49K9WiCAaasCZ5aZ6Klxg==","_resolved":"/tmp/7e5702bfaa52c1c7634b772864e96ad2/api-extractor-tools-module-declaration-merger-0.1.0.tgz","_from":"file:api-extractor-tools-module-declaration-merger-0.1.0.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+676mdgJ/wYPr4gyBZeXHaFw/qUyXTaw5HmEA+1PEGd1uQEJS4dkX/OTxsNlCBztu49K9WiCAaasCZ5aZ6Klxg==","shasum":"003df808cd0affa004c00cb2747715abaabfb3c2","tarball":"https://registry.npmjs.org/@api-extractor-tools/module-declaration-merger/-/module-declaration-merger-0.1.0.tgz","fileCount":64,"unpackedSize":307800,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8Ob4vNSrmuZE/DOikflmXUx8E9fVd6P8prjBbjo3o0wIhAMHxfT3g7WWbTC61hI0eArHWdq7jO6SflfaWPRCDF4AL"}]},"_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/module-declaration-merger_0.1.0_1771015666708_0.21683887723282536"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-06T18:40:11.055Z","modified":"2026-02-13T20:47:47.003Z","0.0.1":"2025-12-06T18:40:11.324Z","0.0.2-alpha.0":"2025-12-08T00:27:22.020Z","0.0.2-alpha.1":"2026-01-01T21:47:21.722Z","0.1.0":"2026-02-13T20:47:46.860Z"},"license":"MIT","keywords":[],"description":"Merges ambient module declarations into api-extractor rollup files","maintainers":[{"name":"northm","email":"michael.l.north@gmail.com"}],"readme":"# Module Declaration Merger\n\n[![npm version](https://img.shields.io/npm/v/%40api-extractor-tools%2Fmodule-declaration-merger)](https://www.npmjs.com/package/@api-extractor-tools/module-declaration-merger)\n\nWhen [@microsoft/api-extractor](https://api-extractor.com/) creates declaration file rollups, it omits ambient module declarations. This package provides a CLI and library that adds the appropriate module declarations to `.d.ts` rollup files _after_ `api-extractor` has generated them.\n\n## Installation\n\n```bash\nnpm install @api-extractor-tools/module-declaration-merger\n```\n\n## Usage\n\n### CLI\n\n```bash\n# Use default api-extractor.json in current directory\nmodule-declaration-merger\n\n# Specify config path\nmodule-declaration-merger --config ./api-extractor.json\n\n# Preview changes without writing\nmodule-declaration-merger --dry-run\n\n# Show detailed output\nmodule-declaration-merger --verbose\n```\n\n### Library\n\n```typescript\nimport { mergeModuleDeclarations } from '@api-extractor-tools/module-declaration-merger'\n\nconst result = await mergeModuleDeclarations({\n  configPath: './api-extractor.json',\n  dryRun: false,\n})\n\nif (!result.success) {\n  console.error('Merge failed with errors:', result.errors)\n  process.exit(1)\n}\n\nconsole.log(`Augmented ${result.augmentedFiles.length} rollup files`)\nconsole.log(`Found ${result.augmentationCount} module augmentations`)\nconsole.log(`Processed ${result.declarationCount} declarations`)\n\nif (result.warnings.length > 0) {\n  console.warn('Warnings:', result.warnings)\n}\n```\n\n## How It Works\n\n1. **Parses** your `api-extractor.json` to find rollup output paths and doc model settings\n2. **Extracts** `declare module` blocks from your TypeScript source files\n3. **Detects maturity levels** (`@public`, `@beta`, `@alpha`, `@internal`) using proper TSDoc parsing\n4. **Appends** declarations to the appropriate rollup files with source attribution\n5. **Augments** the `.api.json` doc model if enabled (for documentation generation)\n\n### Maturity-Based Routing\n\nDeclarations are routed to rollups based on their TSDoc release tags:\n\n| Tag         | Rollups                        |\n| ----------- | ------------------------------ |\n| `@internal` | untrimmed only                 |\n| `@alpha`    | untrimmed, alpha               |\n| `@beta`     | untrimmed, alpha, beta         |\n| `@public`   | untrimmed, alpha, beta, public |\n\nDeclarations without a release tag default to `@public`.\n\n### Handling Missing Release Tags\n\nThis tool respects the `ae-missing-release-tag` configuration in your `api-extractor.json`:\n\n```json\n{\n  \"messages\": {\n    \"extractorMessageReporting\": {\n      \"ae-missing-release-tag\": {\n        \"logLevel\": \"warning\",\n        \"addToApiReportFile\": true\n      }\n    }\n  }\n}\n```\n\n| `logLevel`         | `addToApiReportFile` | Behavior                                                           |\n| ------------------ | -------------------- | ------------------------------------------------------------------ |\n| `\"error\"`          | `true`               | Add warning comment in rollup, continue processing (non-zero exit) |\n| `\"error\"`          | `false`              | Print error to console, **stop processing** (non-zero exit)        |\n| `\"warning\"`        | `true`               | Add warning comment in rollup, continue (zero exit)                |\n| `\"warning\"`        | `false`              | Print warning to console, continue (zero exit)                     |\n| `\"none\"` or absent | any                  | Silently treat as `@public` (zero exit)                            |\n\nWhen `addToApiReportFile: true`, warnings are added as comments in the rollup:\n\n```typescript\n// ============================================\n// Missing Release Tag Warnings (ae-missing-release-tag)\n// ============================================\n//\n// WARNING: ae-missing-release-tag: \"MyInterface\" (interface) in src/file.ts is missing a release tag\n//\n```\n\n### Doc Model (.api.json) Support\n\nThis tool also augments the `.api.json` files used by [@microsoft/api-documenter](https://api-extractor.com/pages/setup/generating_docs/) to generate documentation.\n\nWhen `docModel.enabled` is `true` in your `api-extractor.json`, the tool will:\n\n- Load the existing `.api.json` file\n- Add information about module augmentations\n- Save the updated model\n\nThe default path is `temp/<unscopedPackageName>.api.json` (matching api-extractor's default), but you can customize it:\n\n```json\n{\n  \"docModel\": {\n    \"enabled\": true,\n    \"apiJsonFilePath\": \"<projectFolder>/docs/my-package.api.json\"\n  }\n}\n```\n\n### Output Format\n\nThe tool appends declarations to rollups with clear attribution:\n\n```typescript\n/* existing api-extractor rollup content */\n\n// ============================================\n// Module Declarations (merged by module-declaration-merger)\n// ============================================\n\n// #region Module augmentation from src/things/first.ts\ndeclare module './registry' {\n  /**\n   * Register FirstThing in the registry\n   * @public\n   */\n  interface Registry {\n    first: FirstThing\n  }\n}\n// #endregion\n```\n\n## The Registry Pattern - A Use Case\n\nThis tool is particularly useful with the [registry pattern](https://www.typescript-training.com/course/fundamentals-v4/09-type-queries/#use-case-the-type-registry-pattern) that uses open interfaces:\n\n```typescript\n// src/registry.ts\nexport interface Registry {}\n\nexport type NamesOfThingsInRegistry = keyof Registry\nexport type AllPossibleRegistryThings = Registry[keyof Registry]\n```\n\nWith module augmentations in separate files:\n\n```typescript\n// src/things/first.ts\nexport interface FirstThing {\n  type: 'first'\n}\n\ndeclare module '../registry' {\n  /** @public */\n  interface Registry {\n    first: FirstThing\n  }\n}\n```\n\n```typescript\n// src/things/second.ts\nexport interface SecondThing {\n  type: 'second'\n}\n\ndeclare module '../registry' {\n  /** @public */\n  interface Registry {\n    second: SecondThing\n  }\n}\n```\n\nWhen api-extractor creates the rollup, it omits these `declare module` blocks. This tool adds them back, ensuring the `Registry` type is properly augmented in the published `.d.ts` files.\n\n## API Reference\n\n### `mergeModuleDeclarations(options)`\n\nMain function to merge module declarations into rollups.\n\n```typescript\ninterface MergeOptions {\n  configPath: string // Path to api-extractor.json\n  dryRun?: boolean // Preview without writing (default: false)\n  include?: string[] // Glob patterns for source files\n  exclude?: string[] // Glob patterns to exclude\n}\n\ninterface MergeResult {\n  success: boolean // Whether merge completed successfully\n  augmentedFiles: string[] // Rollup files that were modified\n  skippedFiles: string[] // Rollup files that didn't exist\n  augmentationCount: number // Number of declare module blocks found\n  declarationCount: number // Number of individual declarations\n  untaggedDeclarationCount: number // Declarations missing release tags\n  docModelAugmented: boolean // Whether .api.json was augmented\n  errors: string[] // Errors encountered\n  warnings: string[] // Warnings encountered\n}\n```\n\n### `parseConfig(configPath)`\n\nParse an api-extractor.json and extract rollup paths.\n\n### `extractModuleAugmentations(options)`\n\nExtract `declare module` blocks from source files.\n\n### `createResolver(options)`\n\nCreate a resolver for transforming module specifiers.\n\n### `augmentRollups(options)`\n\nAppend declarations to rollup files.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}