From 23dd9753224d4965a7613d8ea4353f14cef65e92 Mon Sep 17 00:00:00 2001 From: Jeff Williams Date: Sun, 22 Jan 2023 20:38:17 -0800 Subject: [PATCH] refactor: move parser handlers to new `@jsdoc/parse` package Replacing the former `@jsdoc/parse` package, which is now `@jsdoc/ast`. --- packages/jsdoc-parse/.npmignore | 13 + packages/jsdoc-parse/LICENSE | 202 ++++++++ packages/jsdoc-parse/README.md | 3 + packages/jsdoc-parse/index.js | 20 + .../jsdoc/src => jsdoc-parse/lib}/handlers.js | 3 - packages/jsdoc-parse/package-lock.json | 448 ++++++++++++++++++ packages/jsdoc-parse/package.json | 32 ++ packages/jsdoc-parse/test/specs/index.js | 30 ++ .../test/specs/lib}/handlers.js | 24 +- packages/jsdoc/cli.js | 2 +- packages/jsdoc/package.json | 1 + .../jsdoc/plugins/test/specs/railsTemplate.js | 6 +- packages/jsdoc/test/helpers/jsdoc.js | 2 +- .../jsdoc/test/specs/documentation/modules.js | 3 +- packages/jsdoc/test/specs/jsdoc/src/parser.js | 2 +- packages/jsdoc/test/specs/tags/overviewtag.js | 3 +- 16 files changed, 772 insertions(+), 22 deletions(-) create mode 100644 packages/jsdoc-parse/.npmignore create mode 100644 packages/jsdoc-parse/LICENSE create mode 100644 packages/jsdoc-parse/README.md create mode 100644 packages/jsdoc-parse/index.js rename packages/{jsdoc/lib/jsdoc/src => jsdoc-parse/lib}/handlers.js (99%) create mode 100644 packages/jsdoc-parse/package-lock.json create mode 100644 packages/jsdoc-parse/package.json create mode 100644 packages/jsdoc-parse/test/specs/index.js rename packages/{jsdoc/test/specs/jsdoc/src => jsdoc-parse/test/specs/lib}/handlers.js (70%) diff --git a/packages/jsdoc-parse/.npmignore b/packages/jsdoc-parse/.npmignore new file mode 100644 index 00000000..9acb2b54 --- /dev/null +++ b/packages/jsdoc-parse/.npmignore @@ -0,0 +1,13 @@ +.editorconfig +.eslintignore +.eslintrc.js +.gitignore +.github/ +.renovaterc.json +.travis.yml +CHANGES.md +CODE_OF_CONDUCT.md +CONTRIBUTING.md +lerna.json +packages/ +test/ diff --git a/packages/jsdoc-parse/LICENSE b/packages/jsdoc-parse/LICENSE new file mode 100644 index 00000000..d6456956 --- /dev/null +++ b/packages/jsdoc-parse/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/packages/jsdoc-parse/README.md b/packages/jsdoc-parse/README.md new file mode 100644 index 00000000..e0cc0d42 --- /dev/null +++ b/packages/jsdoc-parse/README.md @@ -0,0 +1,3 @@ +# `@jsdoc/parse` + +Parses, and extracts information from, source code. diff --git a/packages/jsdoc-parse/index.js b/packages/jsdoc-parse/index.js new file mode 100644 index 00000000..3a9f8a72 --- /dev/null +++ b/packages/jsdoc-parse/index.js @@ -0,0 +1,20 @@ +/* + Copyright 2023 the JSDoc Authors. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ +const handlers = require('./lib/handlers'); + +module.exports = { + handlers, +}; diff --git a/packages/jsdoc/lib/jsdoc/src/handlers.js b/packages/jsdoc-parse/lib/handlers.js similarity index 99% rename from packages/jsdoc/lib/jsdoc/src/handlers.js rename to packages/jsdoc-parse/lib/handlers.js index dbded308..e376f7ff 100644 --- a/packages/jsdoc/lib/jsdoc/src/handlers.js +++ b/packages/jsdoc-parse/lib/handlers.js @@ -13,9 +13,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -/** - * @module jsdoc/src/handlers - */ const { Doclet } = require('@jsdoc/doclet'); const escape = require('escape-string-regexp'); const { log } = require('@jsdoc/util'); diff --git a/packages/jsdoc-parse/package-lock.json b/packages/jsdoc-parse/package-lock.json new file mode 100644 index 00000000..9c8e3b54 --- /dev/null +++ b/packages/jsdoc-parse/package-lock.json @@ -0,0 +1,448 @@ +{ + "name": "@jsdoc/parse", + "version": "0.1.99", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@jsdoc/parse", + "version": "0.1.99", + "license": "Apache-2.0", + "dependencies": { + "@jsdoc/ast": "^0.1.0", + "@jsdoc/core": "^0.4.5", + "@jsdoc/doclet": "^0.1.1", + "@jsdoc/util": "^0.2.8", + "escape-string-regexp": "^4.0.0" + } + }, + "node_modules/@babel/code-frame": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.18.6.tgz", + "integrity": "sha512-TDCmlK5eOvH+eH7cdAFlNXeVJqWIQ7gW9tY1GJIpUtFb6CmjVyq2VM3u71bOyR8CRihcCgMUYoDNyLXao3+70Q==", + "dependencies": { + "@babel/highlight": "^7.18.6" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.19.1", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.19.1.tgz", + "integrity": "sha512-awrNfaMtnHUr653GgGEs++LlAvW6w+DcPrOliSMXWCKo597CwL5Acf/wWdNkf/tfEQE3mjkeD1YOVZOUV/od1w==", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/highlight": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.18.6.tgz", + "integrity": "sha512-u7stbOuYjaPezCuLj29hNW1v64M2Md2qupEKP1fHc7WdOA3DgLh37suiSrZYY7haUB7iBeQZ9P1uiRF359do3g==", + "dependencies": { + "@babel/helper-validator-identifier": "^7.18.6", + "chalk": "^2.0.0", + "js-tokens": "^4.0.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.20.13", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.20.13.tgz", + "integrity": "sha512-gFDLKMfpiXCsjt4za2JA9oTMn70CeseCehb11kRZgvd7+F67Hih3OHOK24cRrWECJ/ljfPGac6ygXAs/C8kIvw==", + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jsdoc/ast": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/@jsdoc/ast/-/ast-0.1.0.tgz", + "integrity": "sha512-p0ZNl+D0BjR7NiTlcTYSYjSykzSofWm7AHsEHjhZBpMNwNZLqra5NJn3jKXk1Z9aYbnnTsH4TRX+BqFYmjvSYA==", + "dependencies": { + "@babel/parser": "^7.20.5", + "@jsdoc/core": "^0.4.5", + "@jsdoc/util": "^0.2.8", + "lodash": "^4.17.21" + }, + "engines": { + "node": ">=v18.12.0" + } + }, + "node_modules/@jsdoc/core": { + "version": "0.4.5", + "resolved": "https://registry.npmjs.org/@jsdoc/core/-/core-0.4.5.tgz", + "integrity": "sha512-KjdlFg0PCbbpI5RBjWV2Qv1mTswjrNoysAgHXSbG3f49qo/wfB3WMX5iTr0ljMClTBH6xQsc2ODp4Tmokg1DUA==", + "dependencies": { + "bottlejs": "^2.0.1", + "cosmiconfig": "^7.1.0", + "escape-string-regexp": "^4.0.0", + "lodash": "^4.17.21", + "strip-bom": "^4.0.0", + "strip-json-comments": "^3.1.1" + }, + "engines": { + "node": ">=v18.12.0" + } + }, + "node_modules/@jsdoc/doclet": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@jsdoc/doclet/-/doclet-0.1.1.tgz", + "integrity": "sha512-/EZIMqlmSJpT0bXukgSN9WmPMLbmfOo4YACHRf6kyLQIx0KNzqcP9j0m314HW9reyTIFztEcNh1jWllKd14Wpw==", + "dependencies": { + "@jsdoc/ast": "^0.1.0", + "@jsdoc/core": "^0.4.5", + "@jsdoc/tag": "^0.1.5", + "@jsdoc/util": "^0.2.8", + "lodash": "^4.17.21", + "strip-bom": "^4.0.0" + } + }, + "node_modules/@jsdoc/tag": { + "version": "0.1.5", + "resolved": "https://registry.npmjs.org/@jsdoc/tag/-/tag-0.1.5.tgz", + "integrity": "sha512-epvBtr+yYMnMfhcfvU8iyNiDrYxRR1+SGUnY/sY1JIGJfRNHi3PLWG72Le2pol/c86KwJZXYU7R6vM5deBWPsQ==", + "dependencies": { + "@jsdoc/core": "^0.4.5", + "@jsdoc/util": "^0.2.8", + "catharsis": "^0.9.0", + "lodash": "^4.17.21" + }, + "engines": { + "node": ">=v18.12.0" + } + }, + "node_modules/@jsdoc/util": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/@jsdoc/util/-/util-0.2.8.tgz", + "integrity": "sha512-Uqerf+cakeAbFC5JRA087v9ul+7Tu4xzTaSO9vW6i7b0+b8z6qT1rVmX/xrAfco9uyiQDSm68xm9ovR3C0HviA==", + "dependencies": { + "klaw-sync": "^6.0.0", + "lodash": "^4.17.21", + "ow": "^0.28.2" + }, + "engines": { + "node": ">=v18.12.0" + } + }, + "node_modules/@sindresorhus/is": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-4.6.0.tgz", + "integrity": "sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "node_modules/@types/parse-json": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.0.tgz", + "integrity": "sha512-//oorEZjL6sbPcKUaCdIGlIUeH26mgzimjBB77G6XRgnDl/L5wOnpyBGRe/Mmf5CVW3PwEBE1NjiMZ/ssFh4wA==" + }, + "node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/bottlejs": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/bottlejs/-/bottlejs-2.0.1.tgz", + "integrity": "sha512-50T0bzqeAqZ+//kgjdDxNu7UP8Je04isNPyHPwwOOPoeZmtVESkuF9nwkWEqSEd9Sw1yJ1oaoHBAMxe/wG4Zzg==" + }, + "node_modules/callsites": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz", + "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==", + "engines": { + "node": ">=6" + } + }, + "node_modules/catharsis": { + "version": "0.9.0", + "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.9.0.tgz", + "integrity": "sha512-prMTQVpcns/tzFgFVkVp6ak6RykZyWb3gu8ckUpd6YkTlacOd3DXGJjIpD4Q6zJirizvaiAjSSHlOsA+6sNh2A==", + "dependencies": { + "lodash": "^4.17.15" + }, + "engines": { + "node": ">= 10" + } + }, + "node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/chalk/node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==" + }, + "node_modules/cosmiconfig": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.1.0.tgz", + "integrity": "sha512-AdmX6xUzdNASswsFtmwSt7Vj8po9IuqXm0UXz7QKPuEUmPB4XyjGfaAr2PSuELMwkRMVH1EpIkX5bTZGRB3eCA==", + "dependencies": { + "@types/parse-json": "^4.0.0", + "import-fresh": "^3.2.1", + "parse-json": "^5.0.0", + "path-type": "^4.0.0", + "yaml": "^1.10.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/dot-prop": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/dot-prop/-/dot-prop-6.0.1.tgz", + "integrity": "sha512-tE7ztYzXHIeyvc7N+hR3oi7FIbf/NIjVP9hmAt3yMXzrQ072/fpjGLx2GxNxGxUl5V73MEqYzioOMoVhGMJ5cA==", + "dependencies": { + "is-obj": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/error-ex": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", + "integrity": "sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==", + "dependencies": { + "is-arrayish": "^0.2.1" + } + }, + "node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.10", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.10.tgz", + "integrity": "sha512-9ByhssR2fPVsNZj478qUUbKfmL0+t5BDVyjShtyZZLiK7ZDAArFFfopyOTj0M05wE2tJPisA4iTnnXl2YoPvOA==" + }, + "node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "engines": { + "node": ">=4" + } + }, + "node_modules/import-fresh": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", + "integrity": "sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==", + "dependencies": { + "parent-module": "^1.0.0", + "resolve-from": "^4.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-arrayish": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", + "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==" + }, + "node_modules/is-obj": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-obj/-/is-obj-2.0.0.tgz", + "integrity": "sha512-drqDG3cbczxxEJRoOXcOjtdp1J/lyp1mNn0xaznRs8+muBhgQcrnbspox5X5fOw0HnMnbfDzvnEMEtqDEJEo8w==", + "engines": { + "node": ">=8" + } + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==" + }, + "node_modules/json-parse-even-better-errors": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", + "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==" + }, + "node_modules/klaw-sync": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/klaw-sync/-/klaw-sync-6.0.0.tgz", + "integrity": "sha512-nIeuVSzdCCs6TDPTqI8w1Yre34sSq7AkZ4B3sfOBbI2CgVSB4Du4aLQijFU2+lhAFCwt9+42Hel6lQNIv6AntQ==", + "dependencies": { + "graceful-fs": "^4.1.11" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==" + }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" + }, + "node_modules/lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==" + }, + "node_modules/ow": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/ow/-/ow-0.28.2.tgz", + "integrity": "sha512-dD4UpyBh/9m4X2NVjA+73/ZPBRF+uF4zIMFvvQsabMiEK8x41L3rQ8EENOi35kyyoaJwNxEeJcP6Fj1H4U409Q==", + "dependencies": { + "@sindresorhus/is": "^4.2.0", + "callsites": "^3.1.0", + "dot-prop": "^6.0.1", + "lodash.isequal": "^4.5.0", + "vali-date": "^1.0.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/parent-module": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", + "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==", + "dependencies": { + "callsites": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/parse-json": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz", + "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==", + "dependencies": { + "@babel/code-frame": "^7.0.0", + "error-ex": "^1.3.1", + "json-parse-even-better-errors": "^2.3.0", + "lines-and-columns": "^1.1.6" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "engines": { + "node": ">=8" + } + }, + "node_modules/resolve-from": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", + "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==", + "engines": { + "node": ">=4" + } + }, + "node_modules/strip-bom": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-4.0.0.tgz", + "integrity": "sha512-3xurFv5tEgii33Zi8Jtp55wEIILR9eh34FAW00PZf+JnSsTmV/ioewSgQl97JHvgjoRGwPShsWm+IdrxB35d0w==", + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-json-comments": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/vali-date": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/vali-date/-/vali-date-1.0.0.tgz", + "integrity": "sha512-sgECfZthyaCKW10N0fm27cg8HYTFK5qMWgypqkXMQ4Wbl/zZKx7xZICgcoxIIE+WFAP/MBL2EFwC/YvLxw3Zeg==", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", + "engines": { + "node": ">= 6" + } + } + } +} diff --git a/packages/jsdoc-parse/package.json b/packages/jsdoc-parse/package.json new file mode 100644 index 00000000..91d1357a --- /dev/null +++ b/packages/jsdoc-parse/package.json @@ -0,0 +1,32 @@ +{ + "name": "@jsdoc/parse", + "version": "0.1.99", + "description": "Parses, and extracts information from, source code.", + "keywords": [ + "jsdoc" + ], + "author": "Jeff Williams ", + "homepage": "https://github.com/jsdoc/jsdoc", + "license": "Apache-2.0", + "main": "index.js", + "publishConfig": { + "access": "public" + }, + "dependencies": { + "@jsdoc/ast": "^0.1.0", + "@jsdoc/core": "^0.4.5", + "@jsdoc/doclet": "^0.1.1", + "@jsdoc/util": "^0.2.8", + "escape-string-regexp": "^4.0.0" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/jsdoc/jsdoc.git" + }, + "scripts": { + "test": "echo \"Error: run tests from root\" && exit 1" + }, + "bugs": { + "url": "https://github.com/jsdoc/jsdoc/issues" + } +} diff --git a/packages/jsdoc-parse/test/specs/index.js b/packages/jsdoc-parse/test/specs/index.js new file mode 100644 index 00000000..b28609c5 --- /dev/null +++ b/packages/jsdoc-parse/test/specs/index.js @@ -0,0 +1,30 @@ +/* + Copyright 2023 the JSDoc Authors. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ +const parse = require('../../index'); + +describe('@jsdoc/parse', () => { + it('is an object', () => { + expect(parse).toBeObject(); + }); + + describe('handlers', () => { + it('is lib/handlers', () => { + const handlers = require('../../lib/handlers'); + + expect(parse.handlers).toBe(handlers); + }); + }); +}); diff --git a/packages/jsdoc/test/specs/jsdoc/src/handlers.js b/packages/jsdoc-parse/test/specs/lib/handlers.js similarity index 70% rename from packages/jsdoc/test/specs/jsdoc/src/handlers.js rename to packages/jsdoc-parse/test/specs/lib/handlers.js index 972bcad7..b534a01c 100644 --- a/packages/jsdoc/test/specs/jsdoc/src/handlers.js +++ b/packages/jsdoc-parse/test/specs/lib/handlers.js @@ -13,37 +13,38 @@ See the License for the specific language governing permissions and limitations under the License. */ -describe('jsdoc/src/handlers', () => { - const handlers = require('jsdoc/src/handlers'); +/* global jsdoc */ +describe('@jsdoc/parse/lib/handlers', () => { + const handlers = require('../../../lib/handlers'); const testParser = jsdoc.createParser(); handlers.attachTo(testParser); - it('should exist', () => { + it('is an object', () => { expect(handlers).toBeObject(); }); - it('should export an "attachTo" function', () => { + it('exports an `attachTo` method', () => { expect(handlers.attachTo).toBeFunction(); }); describe('attachTo', () => { - it('should attach a "jsdocCommentFound" handler to the parser', () => { + it('attaches a `jsdocCommentFound` handler to the parser', () => { const callbacks = testParser.listeners('jsdocCommentFound'); expect(callbacks).toBeArrayOfSize(1); expect(callbacks[0]).toBeFunction(); }); - it('should attach a "symbolFound" handler to the parser', () => { + it('attaches a `symbolFound` handler to the parser', () => { const callbacks = testParser.listeners('symbolFound'); expect(callbacks).toBeArrayOfSize(1); expect(callbacks[0]).toBeFunction(); }); - it('should attach a "fileComplete" handler to the parser', () => { + it('attaches a `fileComplete` handler to the parser', () => { const callbacks = testParser.listeners('fileComplete'); expect(callbacks).toBeArrayOfSize(1); @@ -51,19 +52,18 @@ describe('jsdoc/src/handlers', () => { }); }); - describe('jsdocCommentFound handler', () => { - /* eslint-disable no-script-url */ + describe('`jsdocCommentFound` handler', () => { + // eslint-disable-next-line no-script-url const sourceCode = 'javascript:/** @name bar */'; - /* eslint-enable no-script-url */ const result = testParser.parse(sourceCode); - it('should create a doclet for comments with "@name" tags', () => { + it('creates a doclet for comments with `@name` tags', () => { expect(result).toBeArrayOfSize(1); expect(result[0].name).toBe('bar'); }); }); - xdescribe('symbolFound handler', () => { + xdescribe('`symbolFound` handler', () => { // TODO }); }); diff --git a/packages/jsdoc/cli.js b/packages/jsdoc/cli.js index c8f2f3b2..9fd9efe3 100644 --- a/packages/jsdoc/cli.js +++ b/packages/jsdoc/cli.js @@ -291,7 +291,7 @@ module.exports = (() => { cli.createParser = () => { // Must be imported after the config is loaded. - const handlers = require('jsdoc/src/handlers'); + const { handlers } = require('@jsdoc/parse'); const parser = require('jsdoc/src/parser'); const plugins = require('jsdoc/plugins'); diff --git a/packages/jsdoc/package.json b/packages/jsdoc/package.json index 586984b7..f60126cf 100644 --- a/packages/jsdoc/package.json +++ b/packages/jsdoc/package.json @@ -19,6 +19,7 @@ "@jsdoc/cli": "^0.2.10", "@jsdoc/core": "^0.4.5", "@jsdoc/doclet": "^0.1.1", + "@jsdoc/parse": "^0.1.99", "@jsdoc/salty": "^0.2.3", "@jsdoc/tag": "^0.1.5", "@jsdoc/util": "^0.2.8", diff --git a/packages/jsdoc/plugins/test/specs/railsTemplate.js b/packages/jsdoc/plugins/test/specs/railsTemplate.js index 704b6378..7d272882 100644 --- a/packages/jsdoc/plugins/test/specs/railsTemplate.js +++ b/packages/jsdoc/plugins/test/specs/railsTemplate.js @@ -15,13 +15,15 @@ */ /* global jsdoc */ describe('railsTemplate plugin', () => { + const { handlers } = require('@jsdoc/parse'); + const { installPlugins } = require('jsdoc/plugins'); const path = require('path'); const parser = jsdoc.createParser(); const pluginPath = path.join(__dirname, '../../railsTemplate'); - require('jsdoc/plugins').installPlugins([pluginPath], parser, jsdoc.deps); - require('jsdoc/src/handlers').attachTo(parser); + installPlugins([pluginPath], parser, jsdoc.deps); + handlers.attachTo(parser); it('should remove <% %> rails template tags from the source of *.erb files', () => { const docSet = parser.parse([path.join(__dirname, '../fixtures/railsTemplate.js.erb')]); diff --git a/packages/jsdoc/test/helpers/jsdoc.js b/packages/jsdoc/test/helpers/jsdoc.js index 90e8e6f4..5dce1054 100644 --- a/packages/jsdoc/test/helpers/jsdoc.js +++ b/packages/jsdoc/test/helpers/jsdoc.js @@ -17,7 +17,7 @@ const { augmentAll } = require('@jsdoc/doclet').augment; const { createParser } = require('jsdoc/src/parser'); const { EventBus } = require('@jsdoc/util'); const fs = require('fs'); -const handlers = require('jsdoc/src/handlers'); +const { handlers } = require('@jsdoc/parse'); const path = require('path'); const bus = new EventBus('jsdoc'); diff --git a/packages/jsdoc/test/specs/documentation/modules.js b/packages/jsdoc/test/specs/documentation/modules.js index 662ee080..2e2d3110 100644 --- a/packages/jsdoc/test/specs/documentation/modules.js +++ b/packages/jsdoc/test/specs/documentation/modules.js @@ -14,6 +14,7 @@ limitations under the License. */ describe('module names', () => { + const { handlers } = require('@jsdoc/parse'); const path = require('path'); let doclets; @@ -24,7 +25,7 @@ describe('module names', () => { env.opts._ = [path.normalize(`${__dirname}/../../fixtures/modules/data`)]; env.sourceFiles = []; srcParser = jsdoc.createParser(); - require('jsdoc/src/handlers').attachTo(srcParser); + handlers.attachTo(srcParser); }); it('should create a name from the file path when no documented module name exists', () => { diff --git a/packages/jsdoc/test/specs/jsdoc/src/parser.js b/packages/jsdoc/test/specs/jsdoc/src/parser.js index 0c5b39a8..f3efa6b0 100644 --- a/packages/jsdoc/test/specs/jsdoc/src/parser.js +++ b/packages/jsdoc/test/specs/jsdoc/src/parser.js @@ -16,7 +16,7 @@ /* eslint-disable no-script-url */ describe('jsdoc/src/parser', () => { const _ = require('lodash'); - const { attachTo } = require('jsdoc/src/handlers'); + const { attachTo } = require('@jsdoc/parse').handlers; const fs = require('fs'); const jsdocParser = require('jsdoc/src/parser'); const path = require('path'); diff --git a/packages/jsdoc/test/specs/tags/overviewtag.js b/packages/jsdoc/test/specs/tags/overviewtag.js index f12ea5fc..3c3d17b7 100644 --- a/packages/jsdoc/test/specs/tags/overviewtag.js +++ b/packages/jsdoc/test/specs/tags/overviewtag.js @@ -14,6 +14,7 @@ limitations under the License. */ describe('@overview tag', () => { + const { handlers } = require('@jsdoc/parse'); const path = require('path'); let doclets; @@ -27,7 +28,7 @@ describe('@overview tag', () => { env.opts._ = [path.normalize(`${__dirname}/../../fixtures`)]; env.sourceFiles = []; srcParser = jsdoc.createParser(); - require('jsdoc/src/handlers').attachTo(srcParser); + handlers.attachTo(srcParser); }); afterEach(() => {