feat: Support for monorepos

Based on npm / Yarn workspaces, introducing the --packages option

Co-Authored-By: efokschaner <eddyaod@gmail.com>

Author: Gerrit0

README.md

@@ -34,6 +34,39 @@ will treat each file contained within it as an entry point.
 typedoc package1/index.ts package2/index.ts
 ```
 
+### Monorepos / Workspaces
+
+If your codebase is comprised of one or more npm packages, you can pass the paths to these
+packages and TypeDoc will attempt to determine entry points from your `package.json`'s `main`
+property (or its default value `index.js`).
+If any of the packages given are the root of an [npm Workspace](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
+or a [Yarn Workspace](https://classic.yarnpkg.com/en/docs/workspaces/) TypeDoc will find all
+the `workpsaces` defined in the `package.json`.
+This mode requires sourcemaps in your JS entry points, in order to find the TS entry points.
+Supports wildcard paths in the same fashion as those found in npm or Yarn workspaces.
+
+#### Single npm module
+
+```text
+typedoc --packages .
+```
+
+#### Monorepo with npm/Yarn workspace at the root
+
+```text
+typedoc --packages .
+```
+
+#### Monorepo with manually specified sub-packages to document
+
+This can be useful if you do not want all your workspaces to be processed.
+Accepts the same paths as would go in the `package.json`'s workspaces
+
+```text
+# Note the single quotes prevent shell widcard expansion, allowing typedoc to do the expansion
+typedoc --packages a-package --packages 'some-more-packages/*' --packages 'some-other-packages/*'
+```
+
 ### Arguments
 
 For a complete list of the command line arguments run `typedoc --help` or visit
@@ -47,6 +80,9 @@ For a complete list of the command line arguments run `typedoc --help` or visit
 -   `--options`<br>
     Specify a json option file that should be loaded. If not specified TypeDoc
     will look for 'typedoc.json' in the current directory.
+-   `--packages <path/to/package/>`<br>
+    Specify one or more sub packages, or the root of a monorepo with workspaces.
+    Supports wildcard paths in the same fashion as those found in npm or Yarn workspaces.
 -   `--tsconfig <path/to/tsconfig.json>`<br>
     Specify a typescript config file that should be loaded. If not
     specified TypeDoc will look for 'tsconfig.json' in the current directory.

bin/typedoc

@@ -59,8 +59,11 @@ async function run(app) {
         return ExitCodes.OptionError;
     }
 
-    if (app.options.getValue("entryPoints").length === 0) {
-        app.logger.error("No entry points provided");
+    if (
+        app.options.getValue("entryPoints").length === 0 &&
+        app.options.getValue("packages").length === 0
+    ) {
+        app.logger.error("No entry points or packages provided");
         return ExitCodes.NoEntryPoints;
     }
 

examples/basic/.gitignore

@@ -0,0 +1 @@
+docs

package-lock.json

@@ -20,6 +20,7 @@
     "node": ">= 12.20.0"
   },
   "dependencies": {
+    "glob": "^7.1.6",
     "handlebars": "^4.7.7",
     "lodash": "^4.17.21",
     "lunr": "^2.3.9",
@@ -33,6 +34,7 @@
     "typescript": "4.0.x || 4.1.x || 4.2.x || 4.3.x"
   },
   "devDependencies": {
+    "@types/glob": "^7.1.3",
     "@types/lodash": "^4.14.170",
     "@types/lunr": "^2.3.3",
     "@types/marked": "^2.0.3",
@@ -57,7 +59,7 @@
   ],
   "scripts": {
     "pretest": "node scripts/copy_test_files.js",
-    "test": "nyc --reporter=html --reporter=text-summary mocha --timeout=10000 'dist/test/**/*.test.js'",
+    "test": "nyc --reporter=html --reporter=text-summary mocha --timeout=10000 'dist/test/**/*.test.js' --exclude 'dist/test/packages/**'",
     "prerebuild_specs": "npm run pretest",
     "rebuild_specs": "node scripts/rebuild_specs.js",
     "build": "tsc --project .",

package.json

@@ -2,12 +2,128 @@
 
 const { remove, copy } = require("../dist/lib/utils/fs");
 const { join } = require("path");
+const { spawn } = require("child_process");
+
+function promiseFromChildProcess(childProcess) {
+    return new Promise(function (resolve, reject) {
+        childProcess.on("error", function (error) {
+            reject(
+                new Error(
+                    childProcess.spawnargs.join(" ") + " : " + error.message
+                )
+            );
+        });
+        childProcess.on("exit", function (code) {
+            if (code !== 0) {
+                reject(
+                    new Error(
+                        childProcess.spawnargs.join(" ") +
+                            " : exited with code " +
+                            code
+                    )
+                );
+            } else {
+                resolve();
+            }
+        });
+    });
+}
+
+const isWindows = process.platform === "win32";
+const npmCommand = isWindows ? "npm.cmd" : "npm";
+
+function ensureNpmVersion() {
+    return Promise.resolve().then(() => {
+        const npmProc = spawn(npmCommand, ["--version"], {
+            stdio: ["ignore", "pipe", "inherit"],
+        });
+        let npmVersion = "";
+        npmProc.stdout.on("data", (data) => {
+            npmVersion += data;
+        });
+        return promiseFromChildProcess(npmProc).then(() => {
+            npmVersion = npmVersion.trim();
+            let firstDot = npmVersion.indexOf(".");
+            const npmMajorVer = parseInt(
+                npmVersion.slice(0, npmVersion.indexOf("."))
+            );
+            if (npmMajorVer < 7) {
+                throw new Error(
+                    "npm version must be at least 7, version installed is " +
+                        npmVersion
+                );
+            }
+        });
+    });
+}
+
+function prepareMonorepoFolder() {
+    return Promise.resolve()
+        .then(() => {
+            return promiseFromChildProcess(
+                spawn(
+                    "git",
+                    ["clone", "https://github.com/efokschaner/ts-monorepo.git"],
+                    {
+                        cwd: join(__dirname, "../dist/test/packages"),
+                        stdio: "inherit",
+                    }
+                )
+            );
+        })
+        .then(() => {
+            return promiseFromChildProcess(
+                spawn(
+                    "git",
+                    ["checkout", "73bdd4c6458ad4cc3de35498e65d55a1a44a8499"],
+                    {
+                        cwd: join(
+                            __dirname,
+                            "../dist/test/packages/ts-monorepo"
+                        ),
+                        stdio: "inherit",
+                    }
+                )
+            );
+        })
+        .then(() => {
+            return promiseFromChildProcess(
+                spawn(npmCommand, ["install"], {
+                    cwd: join(__dirname, "../dist/test/packages/ts-monorepo"),
+                    stdio: "inherit",
+                })
+            );
+        })
+        .then(() => {
+            return promiseFromChildProcess(
+                spawn(npmCommand, ["run", "build"], {
+                    cwd: join(__dirname, "../dist/test/packages/ts-monorepo"),
+                    stdio: "inherit",
+                })
+            );
+        });
+}
+
+function prepareSinglePackageExample() {
+    return Promise.resolve().then(() => {
+        return promiseFromChildProcess(
+            spawn(npmCommand, ["run", "build"], {
+                cwd: join(
+                    __dirname,
+                    "../dist/test/packages/typedoc-single-package-example"
+                ),
+                stdio: "inherit",
+            })
+        );
+    });
+}
 
 const toCopy = [
     "test/converter",
     "test/converter2",
     "test/renderer",
     "test/module",
+    "test/packages",
     "test/utils/options/readers/data",
 ];
 
@@ -18,7 +134,12 @@ const copies = toCopy.map(async (dir) => {
     await copy(source, target);
 });
 
-Promise.all(copies).catch((reason) => {
-    console.error(reason);
-    process.exit(1);
-});
+Promise.all(copies)
+    .then(ensureNpmVersion)
+    .then(() =>
+        Promise.all([prepareMonorepoFolder(), prepareSinglePackageExample()])
+    )
+    .catch((reason) => {
+        console.error(reason);
+        process.exit(1);
+    });

scripts/copy_test_files.js

@@ -69,14 +69,14 @@ function rebuildConverterTests(dirs) {
 
     for (const fullPath of dirs) {
         console.log(fullPath);
-        const src = app.expandInputFiles([fullPath]);
-
         for (const [file, before, after] of conversions) {
             const out = path.join(fullPath, `${file}.json`);
             if (fs.existsSync(out)) {
                 TypeDoc.resetReflectionID();
                 before();
-                const result = app.converter.convert(src, program);
+                const result = app.converter.convert(
+                    app.getEntrypointsForPaths([fullPath])
+                );
                 const serialized = app.serializer.toObject(result);
 
                 const data = JSON.stringify(serialized, null, "  ")
@@ -105,7 +105,7 @@ async function rebuildRendererTest() {
         externalPattern: ["**/node_modules/**"],
     });
 
-    app.options.setValue("entryPoints", app.expandInputFiles([src]));
+    app.options.setValue("entryPoints", [src]);
     const project = app.convert();
     await app.generateDocs(project, out);
     await app.generateJson(project, path.join(out, "specs.json"));