feat: support esm project to parse documentation

.github/workflows/build.yml

@@ -13,16 +13,13 @@ jobs:
   test:
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        node-version: [ 14.x ]
-
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 20.x
+          cache: yarn
       - name: Install dependencies
         run: yarn install --frozen-lockfile
       - name: Run test
@@ -33,16 +30,13 @@ jobs:
     needs: [test]
     if: ${{ github.event_name != 'pull_request' && (contains(github.ref, 'master') || contains(github.ref, 'alpha')  || contains(github.ref, 'beta') || contains(github.ref, 'rc')) }}
 
-    strategy:
-      matrix:
-        node-version: [ 14.x ]
-
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 20.x
+          cache: yarn
       - name: Install dependencies
         run: yarn install --frozen-lockfile
       - name: Release packages
@@ -51,7 +45,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: yarn release
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: packages
           path: |

.mocharc.js

@@ -3,7 +3,5 @@ process.env.NODE_ENV = "test";
 module.exports = {
   recursive: true,
   reporter: "dot",
-  spec: [
-    "packages/**/*.spec.js"
-  ]
+  spec: ["packages/**/*.spec.js"]
 };

eslint.config.mjs

@@ -0,0 +1,62 @@
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import typescriptParser from "@typescript-eslint/parser";
+import pluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+import globals from "globals";
+import {join} from "node:path";
+
+export default [
+  {
+    ignores: [
+      "**/coverage",
+      "**/lib",
+      "**/dist",
+      "processes.config.js",
+      "**/snapshots",
+      "**/templates",
+      "**/docs/**",
+      "**/docs-references/**"
+    ]
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module"
+      },
+      globals: {
+        ...globals.node
+      }
+    },
+    plugins: {
+      "@typescript-eslint": typescriptEslint
+    },
+    rules: {
+      "@typescript-eslint/ban-ts-comment": 0,
+      "@typescript-eslint/camelcase": 0,
+      "@typescript-eslint/no-inferrable-types": 0,
+      "@typescript-eslint/explicit-function-return-type": 0,
+      "@typescript-eslint/explicit-module-boundary-types": 0,
+      "@typescript-eslint/no-unused-vars": 0,
+      "@typescript-eslint/no-explicit-any": 0,
+      "@typescript-eslint/no-non-null-assertion": 0
+    }
+  },
+  // {
+  //   files: ["**/*.spec.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}"], // or any other pattern
+  //   ignores: ["docs/**", "docs-references/**"],
+  //   plugins: {
+  //     vitest
+  //   },
+  //   rules: {
+  //     ...vitest.configs.recommended.rules, // you can also use vitest.configs.all.rules to enable all rules
+  //     "vitest/consistent-test-it": ["error", {fn: "it", withinDescribe: "it"}],
+  //     "vitest/no-alias-methods": "error",
+  //     "vitest/expect-expect": "off"
+  //   }
+  // },
+  pluginPrettierRecommended
+];

package.json

@@ -10,8 +10,8 @@
     "test": "yarn test:lint && yarn test:coverage",
     "test:unit": "cross-env NODE_ENV=test mocha",
     "test:coverage": "cross-env NODE_ENV=test nyc mocha",
-    "test:lint": "eslint packages --ext .js",
-    "test:lint:fix": "eslint packages --ext .js --fix",
+    "test:lint": "eslint",
+    "test:lint:fix": "eslint --fix",
     "build": "monorepo build",
     "sync:packages": "monorepo sync packages",
     "release": "semantic-release",
@@ -43,23 +43,27 @@
     "lerna": "3.22.0"
   },
   "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "8.8.0",
+    "@typescript-eslint/parser": "8.8.0",
     "@tsed/monorepo-utils": "1.11.0",
     "chai": "4.2.0",
     "chai-as-promised": "7.1.1",
     "cross-env": "7.0.2",
-    "eslint": "^7.10.0",
-    "eslint-config-prettier": "6.12.0",
-    "eslint-plugin-prettier": "3.1.4",
-    "eslint-plugin-mocha": "8.0.0",
+    "eslint": "9.13.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-prettier": "5.2.1",
+    "eslint-plugin-simple-import-sort": "12.1.1",
+    "eslint-plugin-vitest": "0.5.4",
     "proxyquire": "2.1.3",
     "husky": "4.3.0",
     "lint-staged": "10.4.0",
     "mocha": "8.1.3",
     "nyc": "15.1.0",
-    "prettier": "2.1.2",
+    "prettier": "3.3.3",
     "semantic-release": "17.2.3",
     "sinon": "9.0.3",
-    "sinon-chai": "3.5.0"
+    "sinon-chai": "3.5.0",
+    "typescript": "5.6.3"
   },
   "workspaces": {
     "packages": [

packages/ts-doc/src/highlight/index.js

@@ -1,7 +1,8 @@
 "use strict";
 
 const {context} = require("../context");
-const KEYWORDS = /(\benum\b|\bstatic\b|\bclass\b|\binterface\b|\bprivate\b|\bpublic\b|\bconst\b|\blet\b|\bprotected\b|\bimplements\b|\bconstructor\b|\breadonly\b|\babstract\b|\bimport\b|\bexport\b|\bas\b|\bfrom\b|\bextends\b)/g;
+const KEYWORDS =
+  /(\benum\b|\bstatic\b|\bclass\b|\binterface\b|\bprivate\b|\bpublic\b|\bconst\b|\blet\b|\bprotected\b|\bimplements\b|\bconstructor\b|\breadonly\b|\babstract\b|\bimport\b|\bexport\b|\bas\b|\bfrom\b|\bextends\b)/g;
 const TYPES = /(\bany\b|\bstring\b|\bboolean\b|\bnumber\b|\bDate\b|\bvoid\b)/g;
 const SEPARATOR = /(:|;|,|\(|\)|{|}|\[|\]| = )/g;
 

packages/ts-doc/src/models/DocFile.js

@@ -1,8 +1,10 @@
 const {context} = require("../context");
 const path = require("path");
-const fs = require("fs");
+const fs = require("fs/promises");
+const fsSync = require("fs");
 const normalizePath = require("normalize-path");
 const readPkgUp = require("read-pkg-up");
+const {logger} = require("../context/context");
 const mapExported = new Map();
 
 class DocFile {
@@ -13,7 +15,7 @@ class DocFile {
   constructor(file) {
     this.file = normalizePath(file);
     this.symbols = new Map();
-    this.contents = fs.readFileSync(file).toString();
+    this.contents = fsSync.readFileSync(file).toString();
   }
 
   get path() {
@@ -50,24 +52,26 @@ class DocFile {
     };
   }
 
-  requireModule() {
+  async importModule() {
     const {modulePath} = this.module;
     let file = path.join(modulePath, "index.js");
+    try {
+      if (fsSync.existsSync(path.join(modulePath, "package.json"))) {
+        const pkg = JSON.parse(await fs.readFile(path.join(modulePath, "package.json"), {encoding: "utf-8"}));
+        file = path.join(modulePath, pkg.main);
+      }
 
-    if (fs.existsSync(path.join(modulePath, "package.json"))) {
-      const pkg = require(path.join(modulePath, "package.json"));
-      file = path.join(modulePath, pkg.main);
-    }
-
-    if (mapExported.has(file)) {
-      return mapExported.get(file);
-    }
+      if (mapExported.has(file)) {
+        return mapExported.get(file);
+      }
 
-    if (fs.existsSync(file)) {
-      mapExported.set(file, require(file));
-      return mapExported.get(file);
+      if (fsSync.existsSync(file)) {
+        mapExported.set(file, await import(file));
+        return mapExported.get(file);
+      }
+    } catch (er) {
+      logger.error("Fail to import module", {file, modulePath});
     }
-
     return undefined;
   }
 }

packages/ts-doc/src/models/DocSymbol.js

@@ -159,7 +159,7 @@ class DocSymbol {
     });
   }
 
-  setDocFile(docFile) {
+  async setDocFile(docFile) {
     this.docFile = docFile;
 
     if (this.relativePath.match("decorators") && this.symbolType === "function") {
@@ -178,7 +178,7 @@ class DocSymbol {
       if (this.symbolType !== "interface") {
         this.private = true;
 
-        const exported = this.docFile.requireModule();
+        const exported = await this.docFile.importModule();
 
         if (exported) {
           const symbolPrivate = exported[this.symbolName.trim()];

packages/ts-doc/src/models/DocSymbol.spec.js

@@ -4,7 +4,7 @@ const context = require("../context/context");
 const {expect} = require("../test/tools");
 
 describe("DocSymbol", () => {
-  before(() => {
+  before(async () => {
     context.github = "https://github.com/repo";
     context.version = "1.0.0";
 
@@ -26,7 +26,7 @@ describe("DocSymbol", () => {
 
     this.docSymbol = new DocSymbol();
     this.docSymbol.symbolName = "SymbolName";
-    this.docSymbol.setDocFile({
+    await this.docSymbol.setDocFile({
       file: path.join(process.cwd(), "/packages/common/di/lib/file.d.ts"),
       path: path.join(process.cwd(), "/packages/common/di/lib/file.ts"),
       srcPath: path.join(process.cwd(), "/packages/common/di/src/file.ts"),
@@ -39,7 +39,7 @@ describe("DocSymbol", () => {
         pkgName: "common",
         subPkgName: "di"
       },
-      requireModule() {
+      importModule() {
         return {};
       }
     });

packages/ts-doc/src/parsers/DocParser.js

@@ -4,6 +4,7 @@ const {DocSymbolParser} = require("./DocSymbolParser");
 const {sumBracket} = require("./sum-bracket");
 
 const {stripsTags} = require("../utils/strips");
+const {logger} = require("../context/context");
 
 const EXPORT_PATTERN = /^export /;
 
@@ -33,14 +34,18 @@ class DocParser {
     this.contents = contents;
   }
 
-  static parse(docFile) {
+  static async parse(docFile) {
     const {symbols} = new DocParser(docFile.contents).parse();
 
-    symbols.forEach((symbol) => {
-      symbol.setDocFile(docFile);
-      symbol = context.symbols.push(symbol);
-      docFile.symbols.set(symbol.symbolName, symbol);
-    });
+    for (const [, symbol] of symbols) {
+      try {
+        await symbol.setDocFile(docFile);
+        const newSymbol = context.symbols.push(symbol);
+        docFile.symbols.set(newSymbol.symbolName, newSymbol);
+      } catch (er) {
+        logger.error("Fail to process symbol", {symbol, error: er});
+      }
+    }
 
     return docFile.symbols;
   }

packages/ts-doc/src/scan/scan.js

@@ -49,21 +49,24 @@ module.exports = {
    *
    * @param patterns
    */
-  scanFiles(patterns) {
+  async scanFiles(patterns) {
     context.logger("Scan folders '" + chalk.cyan(JSON.stringify(patterns)) + "'");
 
     let symbolsSize = 0;
+    const files = await globby(patterns);
 
-    globby.sync(patterns).forEach((file) => {
+    for (const file of files) {
       try {
-        DocParser.parse(new DocFile(file)).forEach((symbol) => {
+        const symbols = await DocParser.parse(new DocFile(file));
+
+        symbols.forEach((symbol) => {
           context.logger(`Scanned symbol '${chalk.cyan(symbol.symbolName)}'`);
           symbolsSize++;
         });
       } catch (er) {
         context.logger.error(chalk.red(er), er.stack);
       }
-    });
+    }
 
     context.logger(`${chalk.green(symbolsSize)} scanned symbols`);
   }