@visulima/jsdoc-open-api 3.0.0-alpha.3 → 3.0.0-alpha.31

package/CHANGELOG.md

@@ -1,3 +1,321 @@
+## @visulima/jsdoc-open-api [3.0.0-alpha.31](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.30...@visulima/jsdoc-open-api@3.0.0-alpha.31) (2026-06-19)
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.30](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.29...@visulima/jsdoc-open-api@3.0.0-alpha.30) (2026-06-13)
+
+### Features
+
+* **jsdoc-open-api:** harden merge, fix error paths, add yaml/stdout/watch output ([abd6a1a](https://github.com/visulima/visulima/commit/abd6a1ae6be8060515f8a61a1469b8ae652bf58a))
+
+### Bug Fixes
+
+* **jsdoc-open-api:** use String.raw for mime-type backslash literal ([e55977d](https://github.com/visulima/visulima/commit/e55977d804ec2cb26b077f51bd2ce9cc6677d5ac))
+
+### Tests
+
+* **jsdoc-open-api:** assert each file is parsed once ([b285496](https://github.com/visulima/visulima/commit/b28549623e984cc65a8c645a149406c546461e93))
+
+### Build System
+
+* regenerate bundled-license manifests and types ordering ([af26588](https://github.com/visulima/visulima/commit/af26588d75aaa937fd4862800560bd4070a4878c))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.32
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.29](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.28...@visulima/jsdoc-open-api@3.0.0-alpha.29) (2026-06-04)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.31
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.28](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.27...@visulima/jsdoc-open-api@3.0.0-alpha.28) (2026-06-04)
+
+### Bug Fixes
+
+* **jsdoc-open-api:** 3 bug fixes ([1336b87](https://github.com/visulima/visulima/commit/1336b870964f2645505efbf2720218ddb5aaa18d))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.30
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.27](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.26...@visulima/jsdoc-open-api@3.0.0-alpha.27) (2026-06-02)
+
+### Miscellaneous Chores
+
+* apply eslint + prettier autofixes across packages ([c1bb784](https://github.com/visulima/visulima/commit/c1bb7848a0d93d0dfe2960c77e3cda22239c79a0))
+
+### Tests
+
+* improve coverage across packages ([91bd6d3](https://github.com/visulima/visulima/commit/91bd6d3b61736e3c8bd1fc59b0b5955f76a5d323))
+* **jsdoc-open-api:** cover cli commands, webpack plugin errors, loaders, and swagger merge paths ([22cff56](https://github.com/visulima/visulima/commit/22cff56740cc473cad3ad45ab3749cfff8ff36d8))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.29
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.26](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.25...@visulima/jsdoc-open-api@3.0.0-alpha.26) (2026-05-27)
+
+### Bug Fixes
+
+* **storage-client:** percent-encode user fields in defaultFingerprint ([7c78a0f](https://github.com/visulima/visulima/commit/7c78a0f9512e2a673b941d80839e9f1e86b7b5d0))
+
+### Miscellaneous Chores
+
+* sorted package.json ([b47c545](https://github.com/visulima/visulima/commit/b47c545591600fdab17d5cd3a3fbc68b61e199da))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.28
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.25](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.24...@visulima/jsdoc-open-api@3.0.0-alpha.25) (2026-05-26)
+
+### Miscellaneous Chores
+
+* **ci-stability:** green CI across vis, native, lint, tests, attw ([#651](https://github.com/visulima/visulima/issues/651)) ([d4eb684](https://github.com/visulima/visulima/commit/d4eb684b5f75c818c9251048c605a0ed54a268e3))
+* **repo:** apply eslint --fix and prettier --fix across packages ([#650](https://github.com/visulima/visulima/issues/650)) ([2e26a84](https://github.com/visulima/visulima/commit/2e26a84774f218f21345e9a8ecd68236b6542743)), closes [#620](https://github.com/visulima/visulima/issues/620)
+* **repo:** sort package.json keys across all packages ([e1fd9ab](https://github.com/visulima/visulima/commit/e1fd9ab467ef96a98c777da1572ff6a50fcf7e71))
+
+### Tests
+
+* **repo:** add dist runtime + types integration tests ([32ee300](https://github.com/visulima/visulima/commit/32ee300b7184117a0ddf9f9d390f75f8932d5ed9))
+* **repo:** cover bin entry points in dist integration suite ([7479ef1](https://github.com/visulima/visulima/commit/7479ef113cf5ccef25692619082afb1b6a0eecab))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.26
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.24](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.23...@visulima/jsdoc-open-api@3.0.0-alpha.24) (2026-05-20)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.25
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.23](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.22...@visulima/jsdoc-open-api@3.0.0-alpha.23) (2026-05-19)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.24
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.22](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.21...@visulima/jsdoc-open-api@3.0.0-alpha.22) (2026-05-16)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.23
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.21](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.20...@visulima/jsdoc-open-api@3.0.0-alpha.21) (2026-05-14)
+
+### Miscellaneous Chores
+
+* **jsdoc-open-api:** apply formatter sweep ([6852218](https://github.com/visulima/visulima/commit/6852218fe4d8099771d12499cba090d73034b3c3))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.22
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.20](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.19...@visulima/jsdoc-open-api@3.0.0-alpha.20) (2026-05-11)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.21
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.19](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.18...@visulima/jsdoc-open-api@3.0.0-alpha.19) (2026-05-11)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.20
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.18](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.17...@visulima/jsdoc-open-api@3.0.0-alpha.18) (2026-05-10)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.19
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.17](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.16...@visulima/jsdoc-open-api@3.0.0-alpha.17) (2026-05-10)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.18
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.16](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.15...@visulima/jsdoc-open-api@3.0.0-alpha.16) (2026-05-07)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.17
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.15](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.14...@visulima/jsdoc-open-api@3.0.0-alpha.15) (2026-05-07)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.16
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.14](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.13...@visulima/jsdoc-open-api@3.0.0-alpha.14) (2026-05-06)
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.15
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.13](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.12...@visulima/jsdoc-open-api@3.0.0-alpha.13) (2026-05-06)
+
+### Miscellaneous Chores
+
+* **jsdoc-open-api:** apply prettier and eslint quote-style auto-fix ([2e9b8d0](https://github.com/visulima/visulima/commit/2e9b8d0cdccaa94f22627e5e5f11153c71b689bd))
+* **jsdoc-open-api:** housekeeping cleanup ([de52abe](https://github.com/visulima/visulima/commit/de52abea6d81abc06a8afc14c70ea2a5aabcd30e))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.14
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.12](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.11...@visulima/jsdoc-open-api@3.0.0-alpha.12) (2026-05-04)
+
+### Miscellaneous Chores
+
+* **jsdoc-open-api:** upgrade packem to 2.0.0-alpha.76 ([a3b3549](https://github.com/visulima/visulima/commit/a3b3549a68e22970a39904d2d654b65c6047d7cf))
+* re-sort workspace package.json files via vis sort-package-json ([f625696](https://github.com/visulima/visulima/commit/f625696cfac974325774b3243e1a83c3d23acbd7))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.13
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.11](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.10...@visulima/jsdoc-open-api@3.0.0-alpha.11) (2026-04-22)
+
+### Bug Fixes
+
+* Remove JSR configuration generation script and generated jsr.json files ([#616](https://github.com/visulima/visulima/issues/616)) ([533744b](https://github.com/visulima/visulima/commit/533744b103b74896941db5b727173e617a27a63b))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.12
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.10](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.9...@visulima/jsdoc-open-api@3.0.0-alpha.10) (2026-04-21)
+
+### Miscellaneous Chores
+
+* jsr.json update and lock file ([73fce38](https://github.com/visulima/visulima/commit/73fce38c7cb4603f3fffb88609b1b18e2feb4937))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.11
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.9](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.8...@visulima/jsdoc-open-api@3.0.0-alpha.9) (2026-04-21)
+
+### Miscellaneous Chores
+
+* update the jsr.json ([864ab7e](https://github.com/visulima/visulima/commit/864ab7e71c4b5ae82f64792d1ae8debfea2c539b))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.10
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.8](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.7...@visulima/jsdoc-open-api@3.0.0-alpha.8) (2026-04-21)
+
+### Bug Fixes
+
+* **api:** resolve eslint and type-safety issues across api packages ([3601491](https://github.com/visulima/visulima/commit/3601491261de56b5cfad87c97daafd458e4ee3b6))
+* **jsdoc-open-api:** drop redundant String() conversion in init-command ([1b2384e](https://github.com/visulima/visulima/commit/1b2384e917687beaf464e18e24595c7d4214c94e))
+* **jsdoc-open-api:** relax type overrides for parser code, preserve JSON roundtrip for undefined stripping ([be896e2](https://github.com/visulima/visulima/commit/be896e2e724396bcb74fbbd3161d29213a9984d6))
+
+### Miscellaneous Chores
+
+* bump engines.node to ^22.14.0 || >=24.10.0 ([c3d0931](https://github.com/visulima/visulima/commit/c3d0931d1504e4f21ebf50ea680cfa7ce4ba15ce))
+* fixed jsr.json ([5d85e51](https://github.com/visulima/visulima/commit/5d85e5179de38e284ec433b14d77c71a1619c8d6))
+* **jsdoc-open-api:** apply formatter updates ([57231bd](https://github.com/visulima/visulima/commit/57231bd235fa16768802306aa6e906a4558c579c))
+* **jsdoc-open-api:** apply pending lint and source updates ([0669fd3](https://github.com/visulima/visulima/commit/0669fd3d46ad0787ef6709cc8cad67b7ff7495f7))
+* **jsdoc-open-api:** enforce curly braces and apply lint fixes ([606641f](https://github.com/visulima/visulima/commit/606641f7a29eaa5707ae27c57ed02a91adf950b5))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.9
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.7](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.6...@visulima/jsdoc-open-api@3.0.0-alpha.7) (2026-04-08)
+
+### Miscellaneous Chores
+
+* **jsdoc-open-api:** add tsconfig.eslint.json for type-aware linting ([dd9a888](https://github.com/visulima/visulima/commit/dd9a88810a864e5ef8ee9a1cdf3cf742a4549cb3))
+* **jsdoc-open-api:** apply prettier formatting ([25dae1b](https://github.com/visulima/visulima/commit/25dae1bd4d911921c1926c0212751cf4179087aa))
+* **jsdoc-open-api:** migrate .prettierrc.cjs to prettier.config.js ([cbe2931](https://github.com/visulima/visulima/commit/cbe2931b52a65fcb2e86960acdc31c8ebc3c9c74))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.7
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.6](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.5...@visulima/jsdoc-open-api@3.0.0-alpha.6) (2026-03-26)
+
+### Features
+
+* **web:** auto-generate packages page from workspace metadata ([623e520](https://github.com/visulima/visulima/commit/623e5207693a7fe720f5f2f179593a3654c880e3))
+
+### Miscellaneous Chores
+
+* update homepage URLs to visulima.com/packages/ format ([be42968](https://github.com/visulima/visulima/commit/be42968129df85fb074224435e33135ff44cab91))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.6
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.5](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.4...@visulima/jsdoc-open-api@3.0.0-alpha.5) (2026-03-26)
+
+### Bug Fixes
+
+* **jsdoc-open-api:** use workspace:* for internal [@visulima](https://github.com/visulima) deps ([4f97e12](https://github.com/visulima/visulima/commit/4f97e125a8f84a5e8b9691b72e2f9c56c5d3a69b))
+* **web:** improve build setup with incremental stats caching and prod install ([fe33e75](https://github.com/visulima/visulima/commit/fe33e75827586779b4b3a0c6d57b39f889ee6207))
+
+### Documentation
+
+* **cerebro,prisma-dmmf-transformer,jsdoc-open-api:** add comprehensive Fumadocs documentation ([891b308](https://github.com/visulima/visulima/commit/891b308a34bca2765a4a97ea450648d20d90e0cf))
+
+### Miscellaneous Chores
+
+* **api:** remove empty peerDependencies and optionalDependencies ([85142fa](https://github.com/visulima/visulima/commit/85142fa76729c238a59ac48265b5e33e31183abb))
+* **api:** update dependencies ([f3b6f7c](https://github.com/visulima/visulima/commit/f3b6f7c956e8ae2c0da67773b3790f159c07de29))
+* **jsdoc-open-api:** migrate deps to pnpm catalogs ([9a673ca](https://github.com/visulima/visulima/commit/9a673ca0d8235d0ff28a6fe9b150cf2ee37e78a4))
+* **jsdoc-open-api:** update dependencies ([5a1248f](https://github.com/visulima/visulima/commit/5a1248f8fa408fc81bb07a5bf9ce8430b89c1f57))
+* **jsdoc-open-api:** update dependencies ([f5d2a31](https://github.com/visulima/visulima/commit/f5d2a31a8fd163c321915a779c661b758b3e6f73))
+* **jsdoc-open-api:** update tests, docs, and source formatting ([9526ec8](https://github.com/visulima/visulima/commit/9526ec8ebb3e0e506d50b2f6035faf0cbcaca205))
+* sorting package.json ([430ed68](https://github.com/visulima/visulima/commit/430ed683d3e38e4c5c5530f787ca832f083b17e4))
+* update lock file maintenance ([d83e716](https://github.com/visulima/visulima/commit/d83e71697b75d24704185b66bb521a934d2db02d))
+* visulima website ([#591](https://github.com/visulima/visulima/issues/591)) ([59ab2e2](https://github.com/visulima/visulima/commit/59ab2e2befb03e51cd2088956f83d9b87de6d033))
+* year update ([47f4105](https://github.com/visulima/visulima/commit/47f410596ce7190cfea36a073db32e0cec50bbcd))
+
+### Code Refactoring
+
+* **jsdoc-open-api:** replace read-pkg-up with @visulima/fs and migrate to packem ([be668e4](https://github.com/visulima/visulima/commit/be668e4dc21a3394bcdb22aecf416f9c27e08e0d))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.5
+
+## @visulima/jsdoc-open-api [3.0.0-alpha.4](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.3...@visulima/jsdoc-open-api@3.0.0-alpha.4) (2026-01-17)
+
+### Bug Fixes
+
+* **jsdoc-open-api:** combine name and description for path-based YAML parsing ([68e7d23](https://github.com/visulima/visulima/commit/68e7d2395ab97de3221892afe03da27688df7569))
+
 ## @visulima/jsdoc-open-api [3.0.0-alpha.3](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@3.0.0-alpha.2...@visulima/jsdoc-open-api@3.0.0-alpha.3) (2025-12-27)
 
 ### Bug Fixes

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 visulima
+Copyright (c) 2026 visulima
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -24,4 +24,38 @@ SOFTWARE.
 <!-- /DEPENDENCIES -->
 
 <!-- TYPE_DEPENDENCIES -->
+
+# Licenses of bundled types
+The published @visulima/jsdoc-open-api artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled types:
+## commander
+License: MIT
+By: TJ Holowaychuk
+Repository: git+https://github.com/tj/commander.js.git
+
+> (The MIT License)
+>
+> Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> 'Software'), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 <!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -134,11 +134,23 @@ jsdoc-open-api generate src/routes/**/*.js src/controllers/
 # Specify output file
 jsdoc-open-api generate -o ./public/swagger.json src/
 
+# Emit YAML instead of JSON (format is inferred from the extension)
+jsdoc-open-api generate -o ./openapi.yaml src/
+
+# Write the spec to stdout (useful for piping into other tools)
+jsdoc-open-api generate -o - src/
+
+# Seed info/servers/components from a standalone base-definition file
+jsdoc-open-api generate -d ./definition.yaml src/
+
+# Re-generate automatically whenever a watched path changes
+jsdoc-open-api generate --watch src/
+
 # Use verbose output
 jsdoc-open-api generate -v src/
 
 # Use very verbose output for debugging
-jsdoc-open-api generate -d src/
+jsdoc-open-api generate --very-verbose src/
 ```
 
 ### `generate` Command Options:
@@ -149,54 +161,53 @@ jsdoc-open-api generate [options] [path ...]
 
 - `[path ...]` : Paths to files or directories to parse (optional, uses configuration if not provided).
 - `-c, --config [.openapirc.js]` : Specify the configuration file path. Defaults to `.openapirc.js`.
-- `-o, --output [swaggerSpec.json]` : Specify the output file for the OpenAPI specification. Defaults to `swaggerSpec.json`.
+- `-d, --definition [definition.yaml]` : Base OpenAPI definition file (YAML or JSON) used to seed `info`/`servers`/`components`. The config's `swaggerDefinition` takes precedence over the file.
+- `-o, --output [swaggerSpec.json]` : Specify the output file for the OpenAPI specification. Defaults to `swagger.json`. Use a `.yaml`/`.yml` extension to emit YAML, or `-` to write to stdout.
+- `-w, --watch` : Re-generate the specification whenever one of the watched paths changes (press Ctrl+C to exit).
 - `-v, --verbose` : Enable verbose output during generation.
-- `-d, --very-verbose` : Enable _very_ verbose output for detailed debugging.
+- `--very-verbose` : Enable _very_ verbose output for detailed debugging.
 
 ---
 
 ## Programmatic Usage
 
-You can integrate the generation process directly into your Node.js scripts.
+You can assemble a specification directly in your Node.js scripts. The package
+exposes the building blocks rather than a single all-in-one function:
+
+- `SpecBuilder` — merges per-file results into a single OpenAPI document.
+- `parseFile` / `parseFileMulti` — read a file and run one (or several) comment translators over it. `parseFileMulti` reads + parses the comments only once when you need both dialects.
+- `jsDocumentCommentsToOpenApi` / `swaggerJsDocumentCommentsToOpenApi` — the two JSDoc dialect translators.
+- `validate` — validate the assembled document with `@apidevtools/swagger-parser` (the same check the CLI runs).
+- `loadDefinition` — load a standalone base-definition file (YAML or JSON).
 
 ```javascript
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import jsdocOpenApi from "@visulima/jsdoc-open-api"; // Adjust import based on your module system (require vs import)
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+import { SpecBuilder, parseFileMulti, jsDocumentCommentsToOpenApi, swaggerJsDocumentCommentsToOpenApi, validate } from "@visulima/jsdoc-open-api";
 
-const options = {
-    definition: {
-        openapi: "3.0.0",
-        info: {
-            title: "My Programmatic API",
-            version: "1.0.0",
-            description: "API documentation generated programmatically",
-        },
-        // Add other base OpenAPI definition properties here
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const spec = new SpecBuilder({
+    openapi: "3.0.0",
+    info: {
+        title: "My Programmatic API",
+        version: "1.0.0",
+        description: "API documentation generated programmatically",
     },
-    // Glob patterns pointing to your source files with JSDoc comments
-    sources: [path.join(__dirname, "src/routes/**/*.js")],
-    // Optional: Specify output path (defaults to 'swaggerSpec.json' in current dir)
-    // output: path.join(__dirname, 'public/api-docs.json'),
-    // Optional: Enable verbose logging
-    // verbose: true,
-};
+});
+
+const translators = [jsDocumentCommentsToOpenApi, swaggerJsDocumentCommentsToOpenApi];
 
-async function generateDocs() {
-    try {
-        const specification = await jsdocOpenApi(options);
-        console.log("OpenAPI specification generated successfully:");
-        // The specification object is returned, and also written to the output file if specified.
-        // console.log(JSON.stringify(specification, null, 2));
-    } catch (error) {
-        console.error("Error generating OpenAPI specification:", error);
-    }
+// Feed each source file through both dialects (single read + single comment parse).
+for (const file of [path.join(__dirname, "src/routes/users.js")]) {
+    spec.addData(parseFileMulti(file, translators).map((entry) => entry.spec));
 }
 
-generateDocs();
+// Re-use the exact validation the CLI performs.
+await validate(structuredClone(spec));
+
+console.log(JSON.stringify(spec, null, 2));
 ```
 
 ---

package/bin/index.js

@@ -4,7 +4,7 @@ const { exit } = require("node:process");
 // eslint-disable-next-line import/no-extraneous-dependencies
 const { Command } = require("commander");
 
-const { generateCommand, initCommand } = require("../dist/cli/commander");
+const { generateCommand, initCommand } = require("../dist/cli/commander/index.cjs");
 
 // eslint-disable-next-line no-underscore-dangle
 const package_ = require("../package.json");

package/dist/cli/commander/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../../packem_shared/generateCommand-CmoN8jyY.cjs"),t=require("../../packem_shared/initCommand-C8s0kkim.cjs");exports.generateCommand=e;exports.initCommand=t;