From 10764ec96b34611db2d816f159a50ab62bf4868b Mon Sep 17 00:00:00 2001 From: Nodari Chkuaselidze Date: Thu, 29 Dec 2022 14:14:41 +0400 Subject: [PATCH 1/2] pkg: Implement jsdoc import alias resolving. pkg: Add plugin to remove typedef imports that are not valid jsdocs as fallback. --- README.md | 2 +- package-lock.json | 16 +++ plugins/import-aliases.js | 263 ++++++++++++++++++++++++++++++++++++++ plugins/rm-imports.js | 29 +++++ 4 files changed, 309 insertions(+), 1 deletion(-) create mode 100644 package-lock.json create mode 100644 plugins/import-aliases.js create mode 100644 plugins/rm-imports.js diff --git a/README.md b/README.md index 77f2c4a..9f212ff 100644 --- a/README.md +++ b/README.md @@ -239,4 +239,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of 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. -``` \ No newline at end of file +``` diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..b04c1a2 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,16 @@ +{ + "name": "@hns-dev/bsdoc", + "version": "1.0.0", + "lockfileVersion": 2, + "requires": true, + "packages": { + "": { + "name": "@hns-dev/bsdoc", + "version": "1.0.0", + "license": "MIT", + "bin": { + "jsdoc": "jsdoc" + } + } + } +} diff --git a/plugins/import-aliases.js b/plugins/import-aliases.js new file mode 100644 index 0000000..24bfa59 --- /dev/null +++ b/plugins/import-aliases.js @@ -0,0 +1,263 @@ +/*! + * import-aliases.js - Map aliases for each file. + * Copyright (c) 2022, Nodari Chkuaselidze (MIT License) + */ + +'use strict'; + +const path = require('path'); + + +class FileInfo { + constructor(filename) { + this.filename = filename; + // we are looking to resolve these. + this.localImportAliases = new Map(); + + this.longnamesByDeclaration = new Map(); + this.mappings = new Map(); + this.exports = new Map(); + } +} + +const fileinfoByFile = new Map(); + +/** + * Regex for import typedefs + * Is not the best, but should be good enough. + */ + +const typedefRegex = /\/\*\*\s*?@typedef\s+\{import\(['"]([^'"]+)['"]\)*(?:\.(\w+))*\}\s+(\w+)\s*?\*\//g + +/** + * Collect all import requests from the files and clean up import requests. + * JSDOC Event handler. + */ + +function beforeParse(e) { + const filename = e.filename; + const matchAll = [...e.source.matchAll(typedefRegex)]; + + if (matchAll.length === 0) + return; + + const fileinfo = fileinfoByFile.get(filename) || new FileInfo(e.filename); + fileinfoByFile.set(filename, fileinfo); + + for (const matched of matchAll) { + const dir = path.dirname(filename); + const file = withExt(path.resolve(dir, matched[1])); + const exported = matched[2]; + const localAlias = matched[3]; + + // these will need resolving. + fileinfo.localImportAliases.set(localAlias, [file, exported]); + } + + e.source = e.source.replace(typedefRegex, ''); +} + + +function indexLongnames(fileinfo, doclet) { + const {kind, name, longname} = doclet; + + if (kind !== 'class' && kind !== 'function') + return; + + if (name !== longname) + fileinfo.longnamesByDeclaration.set(name, longname); +} + +/** + * Index every mapping that occured in the file. + * @param {FileInfo} fileinfo + * @param {Doclet} doclet + */ + +function indexMappings(fileinfo, doclet) { + const {kind, meta} = doclet; + + if (kind === 'class' || kind === 'function') + return; + + if (meta.code.type !== 'Identifier') + return; + + fileinfo.mappings.set(meta.code.name, meta.code.value); +} + +/** + * Finished generating new doclet, we can use the data from here to index + * mappings and longname mappings. + * JSDOC Event handler + */ + +function newDoclet(e) { + const {doclet} = e;; + const {meta, scope} = doclet; + const filename = path.resolve(meta.path, meta.filename); + + if (scope !== 'global' && scope !== 'static') + return; + + const fileinfo = fileinfoByFile.get(filename) || new FileInfo(filename); + fileinfoByFile.set(filename, fileinfo); + + indexLongnames(fileinfo, doclet); + indexMappings(fileinfo, doclet); +} + +/** + * Final index of the exports to prepare them for the imports. + * @param {FileInfo} fileinfo + */ + +function indexExports(fileinfo) { + let moduleExports = null; + let exportsAlias = 'exports'; + + if (fileinfo.mappings.has('module.exports')) { + moduleExports = fileinfo.mappings.get('module.exports'); + exportsAlias = moduleExports; + const longname = fileinfo.longnamesByDeclaration.get(exportsAlias); + + if (longname) + fileinfo.exports.set('*', longname); + } + + for (const [key, value] of fileinfo.mappings.entries()) { + if (value === 'exports') + exportsAlias = key; + } + + for (const [key, value] of fileinfo.mappings.entries()) { + if (typeof key !== 'string') + continue; + + if (key.startsWith(`${exportsAlias}.`)) { + const exportKey = key.slice(exportsAlias.length + 1); + const longname = fileinfo.longnamesByDeclaration.get(value); + + if (longname) + fileinfo.exports.set(exportKey, longname); + } + } +} + +/** + * Find and replace all the imports. + * @param {FileInfo} fileinfo + */ + +function resolveImports(fileinfo) { + const importAliases = fileinfo.localImportAliases; + + if (importAliases.size === 0) + return; + + for (const [name, request] of importAliases) { + const importFrom = fileinfoByFile.get(request[0]); + + if (!importFrom) { + importAliases.set(name, null); + continue; + } + + const importName = request[1] || '*'; + const longname = importFrom.exports.get(importName); + + if (!longname) { + importAliases.set(name, null); + continue; + } + + importAliases.set(name, longname); + } +} + +/** + * Now we can reinject the resolved types info the importers. + * @param {Doclet} doclet + */ + +function modifyDoclet(doclet) { + const {meta} = doclet; + + if (!meta) + return; + + const filename = path.resolve(meta.path, meta.filename); + const fileinfo = fileinfoByFile.get(filename); + + if (!fileinfo) + return; + + const aliases = fileinfo.localImportAliases; + const replaceType = (type) => { + if (!type) + return; + + for (const [index, name] of type.names.entries()) { + if (aliases.has(name)) + type.names[index] = aliases.get(name); + } + }; + + if (doclet.properties) { + for (const property of doclet.properties) + replaceType(property.type); + } + + if (doclet.params) { + for (const param of doclet.params) + replaceType(param.type); + } + + if (doclet.returns) { + for (const returns of doclet.returns) { + replaceType(returns.type) + } + } +} + +/** + * We have reached the end, we can finally index exports and + * resolve exports. + * JSDOC Event handler + */ + +function processingComplete(e) { + // finally try to reindex exports. + // before we try to inject them as the imported aliases. + for (const info of fileinfoByFile.values()) + indexExports(info); + + // Now resolve imports + for (const info of fileinfoByFile.values()) + resolveImports(info); + + const {doclets} = e; + + for (const doclet of e.doclets) + modifyDoclet(doclet); + + // disable generation for now. + // e.doclets.length = 0; +} + +/* + * Helpers + */ + +function withExt(file) { + if (file.endsWith('.js')) + return file; + + return file + '.js'; +} + +exports.handlers = { + beforeParse, + newDoclet, + processingComplete +}; diff --git a/plugins/rm-imports.js b/plugins/rm-imports.js new file mode 100644 index 0000000..bfcec08 --- /dev/null +++ b/plugins/rm-imports.js @@ -0,0 +1,29 @@ +/*! + * Copyright 2019 SoftwareBrothers.co + * 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, an /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. + */ + +'use strict'; + + +exports.handlers = { + beforeParse: function(e) { + e.source = e.source.replace(/\/\*\*\s*?@typedef\s*?{\s*?import.*\*\//g, '') + } +} From 63b19e4d7ab94a5fd7ccde4ca68fb912e8b11712 Mon Sep 17 00:00:00 2001 From: Nodari Chkuaselidze Date: Sun, 15 Jan 2023 22:28:32 +0400 Subject: [PATCH 2/2] import-aliases: add require resolution for the types. --- plugins/import-aliases.js | 213 +++++++++++++++++++++++++++++++------- 1 file changed, 176 insertions(+), 37 deletions(-) diff --git a/plugins/import-aliases.js b/plugins/import-aliases.js index 24bfa59..8502935 100644 --- a/plugins/import-aliases.js +++ b/plugins/import-aliases.js @@ -27,27 +27,45 @@ const fileinfoByFile = new Map(); * Is not the best, but should be good enough. */ -const typedefRegex = /\/\*\*\s*?@typedef\s+\{import\(['"]([^'"]+)['"]\)*(?:\.(\w+))*\}\s+(\w+)\s*?\*\//g + +function getFileInfo(filename, getNew = false) { + let fileinfo = fileinfoByFile.get(filename); + + if (!getNew) { + return fileinfo; + } + + if (fileinfo) { + return fileinfo; + } + + fileinfo = new FileInfo(filename); + fileinfoByFile.set(filename, fileinfo); + + return fileinfo; +} /** - * Collect all import requests from the files and clean up import requests. - * JSDOC Event handler. + * Collect all `typedef imports` for a file + * NOTE: It may modify e.source. + * @param {JSDOCEvent} e */ -function beforeParse(e) { +function typedefImportAliases(e) { const filename = e.filename; + const typedefRegex = /\/\*\*\s*?@typedef\s+\{import\(['"]([^'"]+)['"]\)*((?:\.\w+)*)\}\s+(\w+)\s*?\*\//g; const matchAll = [...e.source.matchAll(typedefRegex)]; - if (matchAll.length === 0) + if (matchAll.length === 0) { return; + } - const fileinfo = fileinfoByFile.get(filename) || new FileInfo(e.filename); - fileinfoByFile.set(filename, fileinfo); + const fileinfo = getFileInfo(filename, true); for (const matched of matchAll) { const dir = path.dirname(filename); const file = withExt(path.resolve(dir, matched[1])); - const exported = matched[2]; + const exported = matched[2].slice(1); const localAlias = matched[3]; // these will need resolving. @@ -57,15 +75,90 @@ function beforeParse(e) { e.source = e.source.replace(typedefRegex, ''); } +/** + * Parse and resolve const .. = require aliases. + */ + +function constSimpleRequireAliases(e) { + const filename = e.filename; + + const simpleRequire = /const\s+(\w+)\s*=\s*require\(['"]([^'"]+)['"]\)((?:\.\w+)*)\s*?;/g + const simpleRequireAll = [...e.source.matchAll(simpleRequire)] + + if (simpleRequireAll.length === 0) { + return; + } + + const fileinfo = getFileInfo(filename, true); + + for (const matched of simpleRequireAll) { + const dir = path.dirname(filename); + const file = withExt(path.resolve(dir, matched[2])); + const exported = matched[3].slice(1); + const localAlias = matched[1]; + + fileinfo.localImportAliases.set(localAlias, [file, exported]); + } +} + +/** + * Parse and resolve const { .. } = require aliases. + */ + +function constDestructRequireAliases(e) { + const filename = e.filename; + + const destructRequire = /const\s+\{([^{}]+)\}\s*=\s*require\(['"]([^'"]+)['"]\)((?:\.\w+)*)\s*?;/g + const matchedAll = e.source.matchAll(destructRequire); + const destructRequireAll = [...matchedAll] + + if (destructRequireAll.length === 0) { + return; + } + + const fileinfo = getFileInfo(filename, true); + + for (const matched of destructRequireAll) { + const dir = path.dirname(filename); + const file = withExt(path.resolve(dir, matched[2])); + const exported = matched[3].slice(1); + + const exportedNames = matched[1].split(',').map(name => name.trim()); + + for (const name of exportedNames) { + const fullexport = exported ? exported + '.' + name : name; + + const localAlias = name; + fileinfo.localImportAliases.set(localAlias, [file, fullexport]); + } + } +} + +/** + * Collect all import requests from the files and clean up import requests. + * JSDOC Event handler. + */ + +function beforeParse(e) { + typedefImportAliases(e); + constSimpleRequireAliases(e); + constDestructRequireAliases(e); +} + function indexLongnames(fileinfo, doclet) { - const {kind, name, longname} = doclet; + const {kind, name, longname, meta} = doclet; - if (kind !== 'class' && kind !== 'function') + if (kind !== 'class' && kind !== 'function') { return; + } + + const codename = meta.code.name; - if (name !== longname) + if (name !== longname) { + fileinfo.longnamesByDeclaration.set(codename, longname); fileinfo.longnamesByDeclaration.set(name, longname); + } } /** @@ -77,11 +170,13 @@ function indexLongnames(fileinfo, doclet) { function indexMappings(fileinfo, doclet) { const {kind, meta} = doclet; - if (kind === 'class' || kind === 'function') + if (kind === 'class' || kind === 'function') { return; + } - if (meta.code.type !== 'Identifier') + if (meta.code.type !== 'Identifier') { return; + } fileinfo.mappings.set(meta.code.name, meta.code.value); } @@ -97,11 +192,11 @@ function newDoclet(e) { const {meta, scope} = doclet; const filename = path.resolve(meta.path, meta.filename); - if (scope !== 'global' && scope !== 'static') + if (scope !== 'global' && scope !== 'static') { return; + } - const fileinfo = fileinfoByFile.get(filename) || new FileInfo(filename); - fileinfoByFile.set(filename, fileinfo); + const fileinfo = getFileInfo(filename, true); indexLongnames(fileinfo, doclet); indexMappings(fileinfo, doclet); @@ -121,25 +216,29 @@ function indexExports(fileinfo) { exportsAlias = moduleExports; const longname = fileinfo.longnamesByDeclaration.get(exportsAlias); - if (longname) + if (longname) { fileinfo.exports.set('*', longname); + } } for (const [key, value] of fileinfo.mappings.entries()) { - if (value === 'exports') + if (value === 'exports') { exportsAlias = key; + } } for (const [key, value] of fileinfo.mappings.entries()) { - if (typeof key !== 'string') + if (typeof key !== 'string') { continue; + } if (key.startsWith(`${exportsAlias}.`)) { const exportKey = key.slice(exportsAlias.length + 1); const longname = fileinfo.longnamesByDeclaration.get(value); - if (longname) + if (longname) { fileinfo.exports.set(exportKey, longname); + } } } } @@ -156,7 +255,7 @@ function resolveImports(fileinfo) { return; for (const [name, request] of importAliases) { - const importFrom = fileinfoByFile.get(request[0]); + const importFrom = getFileInfo(request[0]); if (!importFrom) { importAliases.set(name, null); @@ -183,39 +282,75 @@ function resolveImports(fileinfo) { function modifyDoclet(doclet) { const {meta} = doclet; - if (!meta) + if (!meta) { return; + } const filename = path.resolve(meta.path, meta.filename); - const fileinfo = fileinfoByFile.get(filename); + const fileinfo = getFileInfo(filename); - if (!fileinfo) + if (!fileinfo) { return; + } const aliases = fileinfo.localImportAliases; - const replaceType = (type) => { - if (!type) + const localNames = fileinfo.longnamesByDeclaration; + + const replaceTypes = (name) => { + const typeMatch = /([\w\s,]+)(?:.<(.*)>)?$/; + const match = name.match(typeMatch); + + if (!match) { + throw new Error('WHAT?', name); + } + + let actual = match[1].split(',').map(t => t.trim()); + const extra = match[2]; + + actual = actual.map((t) => { + if (localNames.has(t)) + return localNames.get(t); + + if (aliases.has(t)) + return aliases.get(t); + + return t; + }); + + actual = actual.join(', '); + + if (!extra) { + return actual; + } + + return `${actual}.<${replaceTypes(extra)}>`; + }; + + const replaceAllTypes = (type) => { + if (!type) { return; + } for (const [index, name] of type.names.entries()) { - if (aliases.has(name)) - type.names[index] = aliases.get(name); + type.names[index] = replaceTypes(name); } }; if (doclet.properties) { - for (const property of doclet.properties) - replaceType(property.type); + for (const property of doclet.properties) { + replaceAllTypes(property.type); + } } if (doclet.params) { - for (const param of doclet.params) - replaceType(param.type); + for (const param of doclet.params) { + replaceAllTypes(param.type); + } } if (doclet.returns) { for (const returns of doclet.returns) { - replaceType(returns.type) + replaceAllTypes(returns.type) } } } @@ -229,17 +364,20 @@ function modifyDoclet(doclet) { function processingComplete(e) { // finally try to reindex exports. // before we try to inject them as the imported aliases. - for (const info of fileinfoByFile.values()) + for (const info of fileinfoByFile.values()) { indexExports(info); + } // Now resolve imports - for (const info of fileinfoByFile.values()) + for (const info of fileinfoByFile.values()) { resolveImports(info); + } const {doclets} = e; - for (const doclet of e.doclets) + for (const doclet of doclets) { modifyDoclet(doclet); + } // disable generation for now. // e.doclets.length = 0; @@ -250,8 +388,9 @@ function processingComplete(e) { */ function withExt(file) { - if (file.endsWith('.js')) + if (file.endsWith('.js')) { return file; + } return file + '.js'; }