pkg: Implement jsdoc import alias resolving.

pkg: Add plugin to remove typedef imports that are not valid jsdocs as
failover.

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.
-```
+```

plugins/import-aliases.js

@@ -0,0 +1,302 @@
+/*!
+ * 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();
+  }
+
+  setLocalAlias(alias, fromFile, exported) {
+    this.localImportAliases.set(alias, [fromFile, exported]);
+  }
+
+  getLocalAlias(alias) {
+    return this.localImportAliases.get(alias);
+  }
+
+  setLongNameAlias(name, longname) {
+    this.longnamesByDeclaration.set(name, longname);
+  }
+
+  hasLongNameAlias(name) {
+    return this.longnamesByDeclaration.has(name);
+  }
+
+  getLongNameAlias(name) {
+    return this.longnamesByDeclaration.get(name);
+  }
+
+  setMapping(name, value) {
+    this.mappings.set(name, value);
+  }
+
+  hasMapping(name) {
+    return this.mappings.has(name);
+  }
+
+  getMapping(name) {
+    return this.mappings.get(name);
+  }
+
+  setExportMapping(exportName, longname) {
+    this.exports.set(exportName, longname);
+  }
+
+  getExportMapping(exportName) {
+    return this.exports.get(exportName);
+  }
+}
+
+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.setLocalAlias(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.setLongNameAlias(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.setMapping(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.hasMapping('module.exports')) {
+    moduleExports = fileinfo.getMapping('module.exports');
+    exportsAlias = moduleExports;
+    const longname = fileinfo.getLongNameAlias(exportsAlias);
+    if (longname)
+      fileinfo.setExportMapping('*', 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.getLongNameAlias(value);
+
+      if (longname)
+        fileinfo.setExportMapping(exportKey, longname);
+    }
+  }
+}
+
+/**
+ * Find and replace all the imports.
+ * @param {FileInfo} fileinfo
+ */
+
+function indexImports(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.getExportMapping(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())
+    indexImports(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
+};

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, '')
+  }
+}