Hangs indefinitely

[claytonneal]

Search terms

typedoc hangs and no documentation produced

Expected Behavior

Documentation gets produced

Actual Behavior

No documentation produced

Steps to reproduce the bug

yarn typedoc --options typedoc.json --logLevel Verbose

The last line of the logs is:
[debug] Begin readme.md/package.json search at ./packages/core

after which nothing happens (left it running for > 4 hrs)

The repository is a mono repo, the config is:

typedoc.json

{
    "$schema": "https://typedoc.org/schema.json",
    "entryPoints": ["./packages/core/"],
    "entryPointStrategy": "packages",
    "out": "./api-docs",
    "readme": "none"
}

typedoc.base.json

{
    "$schema": "https://typedoc.org/schema.json",
    "compilerOptions":{
      "strictNullChecks": false
    },
    "skipErrorChecking": true,
    "excludeExternals": true,
    "exclude": [ "**/*+(index|.spec|.e2e|test).ts" ],
    "externalPattern": [
      "**/node_modules/**"
    ],
    "readme": "none",
    "excludeReferences": true
}

and the config file inside the package:

{
    "extends": ["../../typedoc.base.json"],
    "entryPoints": ["src/core.ts"]
  }

Environment

• Typedoc version: 0.25.3
• TypeScript version: 5.2.2
• Node.js version: 18.12.1
• OS: macos

[claytonneal]

Full logs:

[debug] Reading tsconfig at ./tsconfig.json
[debug] Using TypeScript 5.2.2 from ./node_modules/typescript/lib
[debug] Expanded ./packages/core to:
        ./packages/core/package.json
[debug] Reading project at ./packages/core
[debug] Reading tsconfig at ./packages/core/tsconfig.json
[info] Converting project at ./packages/core
[debug] Using TypeScript 5.2.2 from ./node_modules/typescript/lib
[debug] Expanded ./packages/core/src/core.ts to:
        ./packages/core/src/core.ts
[debug] Converting with 1 programs 1 entry points
[debug] Finished getting entry points in 423ms
[debug] Begin readme.md/package.json search at ./packages/core

[Gerrit0]

Can't do anything for this without a reproduction

[claytonneal]

I found the issue, the export interface caused the hang
removing that export fixes the issue

export interface Certificate {
    purpose: string;
    payload: {
        type: string;
        content: string;
    };
    domain: string;
    timestamp: number;
    signer: string;
    signature?: string;
}

export type { Certificate };

[claytonneal]

i know have a different scenario that im investigating where its hanging indefinetly
it would be good to output logs when this happens and abort after a certain time
hanging indefinetly makes me nervous about having this in CICD

[Gerrit0]

Declaration files are the root of all evil. TypeDoc got stuck because I made the assumption that if a symbol has ts.SymbolFlags.Alias, and I ask TS for what the alias is pointing to, eventually I'll get to the end of a chain.

In normal TS code this is totally fine. (.ts is where all your code ought to be anyways! Declaration files should only be written to describe external JS)

In declaration files, this is also an error, unless the worst compiler option, skipLibCheck is turned on, which tells TS to not check code in declaration files for type errors in many cases, including this one. Detecting and fixing this specific issue isn't difficult, but in general, if code has type errors, TypeDoc's behavior is not guaranteed.

Aborting after some time is something that can't be reasonably implemented in TypeDoc without re-implementing every loop anywhere to introduce a yield, which is not something I'm going to do. Your CI system is already equipped to deal with this, there is a timeout-minute property for GitHub actions, and other CI systems have similar options.