typedoc 0.9.0 no longer processes files in tsconfig.json "files" order

[beevik]

In typedoc 0.8.0, the following command:

typedoc --mode file --out foo .

processes files in the order they appear in the "files" array of tsconfig.json.

In typedoc 0.9.0, the same command processes files in the order they appear in the directory, regardless of what's in the "files" array of tsconfig.json. This can lead to compile errors, because order of compile matters.

Expected behavior: Files are processed in the order they appear in tsconfig.json's files list.

I isolated the issue to 482821c . Before that commit, everything still works the way 0.8.0 did. The associated PR is #587

[thecjharries]

Interesting. My guess is that the TypedocReader or ArgumentsReader is (or both are) overwriting(/riding) the order from the TSConfigReader. With the original shared priorities, it's, quite frankly, dumb luck that this worked as intended in 0.8. I'll look around when I get a chance this week to see if the files option is actually getting passed to TypeDoc. It might not be (e.g. #588).

[beevik]

After some further testing, I suspect that the "files" array in tsconfig.json is being ignored completely. Typedoc appears to be processing all *.ts files in the specified directory, in the order they appear.

[thecjharries]

I was having trouble with that with #587 and CLI-specified files. I think I have a pretty good idea where to fix this if you don't beat me to it.

…

On Oct 10, 2017 7:19 PM, "Brett Vickers" ***@***.***> wrote: After some further testing, I suspect that the "files" array in tsconfig.json is being ignored completely. It appears to be processing all *.ts files in the specified directory, in the order they appear. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#617 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AF9gku9wSDFWDpJduiOx2cxj5kfCINyWks5srAmigaJpZM4P0fdr> .

[rklfss]

#610 should fix that

[pat841]

I added more detail about the issue on #610 for those interested.

[beevik]

I haven't had a chance to test it yet, but did release 0.10.0 include a fix for this issue? If so, feel free to close it.

[aciccarello]

Should be fixed by #610 which was released in v0.11.0

[beevik]

I just tried 0.11.0 and this bug still seems to be there. Apparently, #610 did not fix it. When running typedoc, I still see many errors like the following:

Class 'Component' used before its declaration.

This is happening because files are still being processed in the order they appear in the directory (alphabetically). If files were processed in the order they show up in the files array of tsconfig.json, this error should not happen.

@pat841 @aciccarello

[pat841]

@beevik The #610 PR was to change the read order of the option readers (arguments/tsconfig/typedoc) and NOT the individual loaded file order.

Looking at the source for the typedoc reader, its using the Typescript config reader which handles its own load order:

const { config } = ts.readConfigFile(fileName, ts.sys.readFile);

...

const { fileNames, options, raw: { typedocOptions }} = ts.parseJsonConfigFileContent(
            config,
            ts.sys,
            Path.resolve(Path.dirname(fileName)),
            {},
            Path.resolve(fileName));

One option would be to specify the files array in the typedoc.js config file, since that reader reads the files array as-is.

Example typedoc.js:

const path = require('path');
const tsconfig = require(path.resolve(__dirname, './tsconfig.json'));
tsconfig.out = path.resolve(__dirname, './docs');
tsconfig.name = 'Source Documentation';
tsconfig.mode = 'modules';
tsconfig.files = [
  ...
];
module.exports = tsconfig;

Im not entirely sure if there is any sorting later on down the typedoc pipeline, but I would suggest starting there.

[beevik]

So after debugging this a bit, I've discovered a few things.

The first thing I've noticed is that typedoc doesn't seem to be reading the tsconfig.json to get its input file list. Instead, it uses expandInputFiles to get the list by scanning the source directory for all *.ts files. The order in which readdirSync discovers these files is the order they get added to the inputFiles array.

EDIT: It seems my best option is to follow a similar idea to the one presented by @pat841. I now have an options.js file containing this:

const path = require('path');
module.exports = require(path.resolve(__dirname, 'path/to/tsconfig.json'));

Then, instead of providing the source path on the command line, I do this:

typedoc --options options.js --out path/to/output

This causes typedoc to process my files in the tsconfig.json "files" order, but it still feels like there should be some way to get typedoc to read its input file list from tsconfig.json without jumping through these extra hoops.

EDIT 2: Woops, just discovered that typedoc will load the current directory's tsconfig.json by default if you don't provide a path/to/source/files. (You can also point typedoc at a specific tsconfig.json file with the --tsconfig option.) So it appears the proper solution to my problem is to simply stop providing the source path. Then everything works. The options.js file is not needed.