Unable to doc file located in a dir with `[]`

[xuhdev]

Search terms

file path

Expected Behavior

typedoc should be able to recognize file paths containing [abc]. This kind of odd path names (along with [...abc]) are required by a commonly used feature in next.js: https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes

Actual Behavior

If a file path contains [abc], typedoc generates an error.

Steps to reproduce the bug

1. mkdir \[abc\]
2. touch \[abc\]/a.ts
3. typedoc \[abc\]/a.ts

TypeDoc generates:

[warning] The glob ./[abc]/a.ts did not match any files
[error] Unable to find any entry points. See previous warnings

Also error out even if the current working directory is inside [abc]/.

Environment

• Typedoc version: 0.27.6
• TypeScript version: 5.7.2
• Node.js version: 22.12.0
• OS: Linux

[phoneticallySAARTHaK]

typedoc does not escape special characters in the file names huh.

Edit: Testing it on my own, it does work. but including that file from the CLI did not work.

$ typedoc --entryPoints ./\[abc\]/a.ts 
[debug] Reading tsconfig at ./tsconfig.json
[debug] Using TypeScript 5.7.2 from ./node_modules/typescript/lib
[warning] The glob ./[abc]/a.ts did not match any files
[error] Unable to find any entry points. See previous warnings

[Gerrit0]

This is working as expected. The paths provided to TypeDoc as entry points are sets of globs, not sets of paths.

typedoc ./[abc]/a.ts

The escaping here is for your shell, not TypeDoc, so TypeDoc receives ./[abc]/a.ts and [abc] is a special glob construct (like regex)

typedoc ./\[abc]/a.ts

This will work as TypeDoc will receive ./\[abc]/a.ts and [abc] won't be treated as a glob set

[xuhdev]

Thanks! Could you add some details to the document: https://typedoc.org/documents/Options.Input.html#entrypoints

It isn't clear that the entry point is a set of globs.

[phoneticallySAARTHaK]

The escaping here is for your shell, not TypeDoc, so TypeDoc receives ./[abc]/a.ts and [abc] is a special glob construct (like regex)

typedoc ./[abc]/a.ts

This will work as TypeDoc will receive ./\[abc]/a.ts and [abc] won't be treated as a glob set

Which shell are you using?

Using bash, The command isn't working for me

$ npx typedoc src/\[abc\]/a.ts 
[warning] The glob ./src/[abc]/a.ts did not match any files
[error] Unable to find any entry points. See previous warnings
[error] Found 1 errors and 1 warnings

I made a new project, with default tsconfig (from tsc --init), just changed the rootDir to "./src".

src
└── [abc]
    └── a.ts

2 directories, 1 file

Enclosing the entry point to prevent shell's intervention, it probably throws an uncaught error (with stack trace) ?

$ npx typedoc "src/\[abc\]/a.ts"
TypeDoc exiting with unexpected error:
Error: ENOENT: no such file or directory, scandir '/home/sarthak/git/test/src//[abc/]'

[xuhdev]

@phoneticallySAARTHaK In bash, you need to run: npx typedoc 'src/\[abc\]/a.ts'

Note the single quotes, which prevent bash from escaping the argument.

[phoneticallySAARTHaK]

I get the same error with single or double quotes. Weird. Using node v20.17.0 on linux kernel 6.12.4-arch1-1

Edit: Don't know why both node and python are doing this, while echo works as expected. I'm not sure if something is wrong with my bashrc

More info

For some reason, the \ is being escaped itself, repeatedly.

Tested with simple program that prints its args, both in python and node, the output was the same.

$ node cli.js 'src/\[abc\]/a.ts'
CLI Arguments: [ 'src/\\[abc\\]/a.ts' ]

$ node cli.js 'src/[abc]/a.ts'
CLI Arguments: [ 'src/[abc]/a.ts' ]

$ node cli.js "src/\[abc\]/a.ts"
CLI Arguments: [ 'src/\\[abc\\]/a.ts' ]

$ node cli.js 'src/\\[abc\\]/a.ts'
CLI Arguments: [ 'src/\\\\[abc\\\\]/a.ts' ]

This is the code I used.

const args = process.argv.slice(2);
console.log("CLI Arguments:", args);

[xuhdev]

Actually there might still be a typedoc bug here. If I replace the last step with typedoc '\[abc\]/a.ts', I got the following error:

$ typedoc '\[abc\]/a.ts'
TypeDoc exiting with unexpected error:
Error: ENOENT: no such file or directory, scandir '/home/hong/tmp//[abc/]'
    at Module.readdirSync (node:fs:1502:26)
    at discoverFiles (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/utils/fs.js:211:32)
    at glob (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/utils/fs.js:252:12)
    at file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/utils/entry-point.js:215:24
    at Array.flatMap (<anonymous>)
    at expandGlobs (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/utils/entry-point.js:214:31)
    at getEntryPoints (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/utils/entry-point.js:91:53)
    at Application.getDefinedEntryPoints (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/application.js:311:20)
    at Application.getEntryPoints (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/application.js:302:29)
    at Application.convert (file:///home/hong/.nvm/versions/node/v22.12.0/lib/node_modules/typedoc/dist/lib/application.js:330:38) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'scandir',
  path: '/home/hong/tmp//[abc/]'
}

Looks like TypeDoc somehow replaces backslashes with forward slashes.

---

Additional context, shell does not escape in this case:

$ echo '\[abc\]/a.ts'
\[abc\]/a.ts

[Gerrit0]

Oh how much easier life would be if Windows paths didn't exist... this is happening because of an attempt at handling backslash path separators in getCommonDirectory

[Gerrit0]

The naive fix keeps Linux happy, but Windows is very not, so this will have to wait for next weekend. https://github.com/TypeStrong/typedoc/actions/runs/12739814528/job/35504060660