--entrypointStrategy Packages problem with project references

[akphi]

Search terms

project reference, entrypointStrategy, monorepo, packages

Expected Behavior

If I use --entrypointStrategy Packages and if my sub-project has a slightly complicated setup (see how in pkg1, the tsconfig file refers to tsconfig.package.json, typedoc won't be able to handle it. Strangely, with the same TS setup, if I use Resolve mode, things went fine.

Actual Behavior

Typescript fails with the following log

Using TypeScript 4.7.4 from ./node_modules/typescript/lib
Converting with 2 programs 2 entry points
packages/pkg1/src/index.ts:1:25 - error TS6059: File '/Users/sample/Developer/js/issue-repo/packages/pkg1/package.json' is not under 'rootDir' '/Users/sample/Developer/js/issue-repo/packages/pkg1/src'. 'rootDir' is expected to contain all source files.

1 import packageJson from "../package.json";
                          ~~~~~~~~~~~~~~~~~

packages/pkg1/src/index.ts:1:25 - error TS6307: File '/Users/sample/Developer/js/issue-repo/packages/pkg1/package.json' is not listed within the file list of project '/Users/sample/Developer/js/issue-repo/packages/pkg1/tsconfig.json'. Projects must list all files or use an 'include' pattern.

1 import packageJson from "../package.json";
                          ~~~~~~~~~~~~~~~~~

Steps to reproduce the bug

Please checkout

https://github.com/akphi/issue-repo/tree/typedoc

To reproduce:

yarn && yarn repro

Additional Context

However, I could totally be okay with using --entrypointStrategy Resolve strategy, but I don't like the way modules are being shown as folders, I wonder if we could do something about that (like being able to specify module name), otherwise if it's intended, I would like to use --entrypointStrategy Packages instead

yarn && yarn repro:resolve

Environment

• Typedoc version: 0.23.3
• TypeScript version: 4.7.4
• Node.js version: 16.15.0
• OS: Mac 12.4

[akphi]

@Gerrit0 the strange thing I don't get is this works fine with Resolve strategy but fail with Packages

Also, thank you for your great work, really admire the amount of time and effort you put into this project 🙏

[Gerrit0]

Wow, that's... very weird. If I point TypeDoc at just one of the packages, it's able to handle it, so this truly is specific to Packages mode...

like being able to specify module name

So, like the @module tag? ;)

diff --git a/packages/pkg2/src/index.ts b/packages/pkg2/src/index.ts
index 093ace5..127cd92 100644
--- a/packages/pkg2/src/index.ts
+++ b/packages/pkg2/src/index.ts
@@ -1,3 +1,7 @@
+/**
+ * @module pkg2
+ */
+
 /**
  * Another version
  */

Thanks for the awesome repro! Very helpful when tracking down issues

[akphi]

Yeah, I'm trying to debug the issue myself, I bumped into a problem when locally trying to build typedoc

❯ npm run build:tsc

> typedoc@0.23.3 build:tsc
> tsc --project .

src/test/packages.test.ts:10:32 - error TS2307: Cannot find module '@typestrong/fs-fixture-builder' or its corresponding type declarations.

10 import { tempdirProject } from "@typestrong/fs-fixture-builder";
                                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/test/slow/entry-point.test.ts:1:32 - error TS2307: Cannot find module '@typestrong/fs-fixture-builder' or its corresponding type declarations.

1 import { tempdirProject } from "@typestrong/fs-fixture-builder";
                                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/test/utils/options/readers/tsconfig.test.ts:7:41 - error TS2307: Cannot find module '@typestrong/fs-fixture-builder' or its corresponding type declarations.

7 import { tempdirProject, Project } from "@typestrong/fs-fixture-builder";
                                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/test/utils/options/readers/typedoc.test.ts:2:38 - error TS2307: Cannot find module '@typestrong/fs-fixture-builder' or its corresponding type declarations.

2 import { project as fsProject } from "@typestrong/fs-fixture-builder";
                                       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Found 4 errors in 4 files.

Errors  Files
     1  src/test/packages.test.ts:10
     1  src/test/slow/entry-point.test.ts:1
     1  src/test/utils/options/readers/tsconfig.test.ts:7
     1  src/test/utils/options/readers/typedoc.test.ts:2

Followed the contributing guide but no luck 😢

[Gerrit0]

Have you run a npm install? That's a pretty new dev dependency, might not be installed if you installed a while ago.

I bet this is the fix:

diff --git a/src/lib/utils/entry-point.ts b/src/lib/utils/entry-point.ts
index e5bbb300..3e331a8c 100644
--- a/src/lib/utils/entry-point.ts
+++ b/src/lib/utils/entry-point.ts
@@ -367,6 +367,7 @@ function getEntryPointsForPackages(
         const program = ts.createProgram({
             rootNames: parsedCommandLine.fileNames,
             options: options.fixCompilerOptions(parsedCommandLine.options),
+            projectReferences: parsedCommandLine.projectReferences,
         });
         const sourceFile = program.getSourceFile(packageEntryPoint);
         if (sourceFile === undefined) {

[Gerrit0]

That dependency also requires pre-install scripts in order to work, so if you have the ignore-scripts option set, that'll cause issues

[akphi]

@Gerrit0 what's your npm version? mine is 8.5.5 and ignore-scripts=false by default. It's alright for now, I can just try to remove those tests, I'll try now

[Gerrit0]

I'm on 8.11.0, though I think even some 6.x version ought to work...

[akphi]

Have you run a npm install? That's a pretty new dev dependency, might not be installed if you installed a while ago.

I bet this is the fix:

diff --git a/src/lib/utils/entry-point.ts b/src/lib/utils/entry-point.ts
index e5bbb300..3e331a8c 100644
--- a/src/lib/utils/entry-point.ts
+++ b/src/lib/utils/entry-point.ts
@@ -367,6 +367,7 @@ function getEntryPointsForPackages(
         const program = ts.createProgram({
             rootNames: parsedCommandLine.fileNames,
             options: options.fixCompilerOptions(parsedCommandLine.options),
+            projectReferences: parsedCommandLine.projectReferences,
         });
         const sourceFile = program.getSourceFile(packageEntryPoint);
         if (sourceFile === undefined) {

I think you caught the issue!

[akphi]

I'll find time to try it with my main project https://github.com/finos/legend-studio later. Due to #1959 I need to put a dummy typedocMain in all of my packages 😆

Thanks for such a quick turnaround!