0.25.1 broke "expand" entry points when using project references

[milesj]

NOTE: This is using https://github.com/milesj/docusaurus-plugin-typedoc-api and not TypeDoc's documentation, but the generator is still the same. It uses the JSON output.

Search terms

Expected Behavior

When using project references (a monorepo setup), and a project is using a folder as an entry point (src/), and the "expand" entryPointStrategy is being used, it should correctly find all files in the project.

This works in v0.25.0 but has broken in v0.25.1.

Actual Behavior

During build, the following warnings are logged. These do not show up in v0.25.0.

[warning] The entry point /Users/miles/Projects/docusaurus-plugin-typedoc-api/fixtures/monorepo/deep-imports/src/classes/Bar.ts is not included in the program for your provided tsconfig.
[warning] The entry point /Users/miles/Projects/docusaurus-plugin-typedoc-api/fixtures/monorepo/deep-imports/src/functions/foo.ts is not included in the program for your provided tsconfig.
[warning] The entry point /Users/miles/Projects/docusaurus-plugin-typedoc-api/fixtures/monorepo/deep-imports/src/index.ts is not included in the program for your provided tsconfig.

When viewing the docs, the project with the warnings does not show up at all, while all the other projects do.

For example, when using this fixture (https://github.com/milesj/docusaurus-plugin-typedoc-api/tree/master/fixtures/monorepo), the deep-imports project is missing after build, but multi-imports and standard are present.

Steps to reproduce the bug

1. Clone https://github.com/milesj/docusaurus-plugin-typedoc-api
2. Bump typedoc to 0.25.1`
3. Install deps: yarn install
4. Build docs: DOCS_REPO_TYPE=monorepo yarn docs

Environment

• Typedoc version: 0.25.1
• TypeScript version: 5.2
• Node.js version: 20
• OS: macos

[Gerrit0]

Well, that's annoying, caused by 0985616f55e234747099cf14efac06c85294183c

[lll000111]

Has this been fixed? I just installed typedoc 0.25.7, and with no strategy or with "expand", same result (finds more files, in the sub folders, with "expand"), same result:

[warning] The entry point ./src/[DIR]/FILE].ts is not included in the program for your provided tsconfig.

for every single file it finds. No output is created.

I have no idea what "not included in the program" is even supposed to mean??? What part of the tsconfig does that refer to?

Suggested additional TODO/ENHANCEMENT: Make error messages like this one correspond to known features of the tsconfig, so that it is clear what it refers to.

The project is a library and it's a collection of mostly independent modules, so there is no single entry point. Thus far I used jsdoc3 but that is ancient and almost unmaintained, so I want to switch.

[Gerrit0]

If there's a commit referencing an issue that's closed -- yes. It's fixed.

"not included in the program" is rather obtuse wording, sorry about that, if familiar with the compiler API it makes sense, but most people aren't... It means that the file is not referenced by the files or include tsconfig option, or referenced by one of the files included by one of those options. I'll add improving that wording to my todo list for today

[lll000111]

@Gerrit0 I read that "Project References" are supported without me having to do anything. The files are not included in the top level tsconfig, but in one of the sub projects and its tsconfig- I use a different config for src/ and for test/ and the top level tsconfig uses Project References to point to both.

The error is wrong if Project References are supposed to work?

[Gerrit0]

Please open a new issue, typedoc has tests that show that it does work, so I suspect there's something special about your setup.

[lll000111]

@Gerrit0

FYI, and for the record.

The issue was that my top level tsconfig is responsible for the build scripts too, so it has an "include" and an "exclude" section that is only for those scripts. Sources in src/ and tests in test/ are handled by the "references" and the tsconfig files in the two referenced sub directories have their own in- and excludes.

That never was a problem with tsc and type checks and builds, but typedoc saw those top level tsconfig file in- and exclude sections and then seems to ignore the "references". When I remove those two entries from the top level tsconfig it proceeds to look at the "references" paths and produces the output.

If it is feasible and/or desirable - probably not the highest of priorities for you guys since it's definitely more niche - to do I'd propose to make the behavior more equal to tsc, I think having "include" and "exclude" in the top level tsconfig should be fine and not lead to typedoc not even bothering with the references. But I want to ask first before adding a "TODO" issue.

 

EDIT: Oh and it also conflicts with eslint-plugin-typescript when I remove those entries from the top level. Now I get eslint errors about stuff not being defined. So I would prefer to be able to keep them...

EDIT: I'm also doing it wrong, conceptionally at least. I think I should just give the scripts their own directory and tsconfig and entry in "references and then see what happens with that more logical structure.*

[Gerrit0]

TypeDoc, for I believe two patch releases, used to recurse over references and created programs for them as well if the base config included references.

Unfortunately, in the vast majority of use cases, this meant that running TypeDoc was 2-30x slower for no benefit, and in large monorepos would sometimes run out of memory due to attempting to compile everything at once.

EDIT: I'm also doing it wrong, conceptionally at least. I think I should just give the scripts their own directory and tsconfig and entry in "references and then see what happens with that more logical structure.

This is one of two options I'd recommend; TypeDoc could theoretically have an option to make it handle your current setup, but it's certainly not something I'd want to have on by default due to the massive performance issues... and due to the other option, I'm not sure it's actually useful.

An alternative which is probably better, however, is to point TypeDoc at the tsconfig for your src project. TypeDoc doesn't need to type check your tests, since they won't be included in documentation, so there's no point in including them in the tsconfig used by it.