Merge branch 'watch-docs-and-css' into dev

Author: Gerrit0

bin/typedoc

@@ -1,5 +1,16 @@
 #!/usr/bin/env node
 //@ts-check
 
-/* eslint-disable @typescript-eslint/no-var-requires */
-import("../dist/lib/cli.js");
+const { fork } = require("child_process");
+
+function main() {
+    fork(__dirname + "/../dist/lib/cli.js", process.argv.slice(2), {
+        stdio: "inherit",
+    }).on("exit", (code) => {
+        // Watch restart required? Fork a new child
+        if (code === 7) main();
+        else process.exit(code || 0);
+    });
+}
+
+main();

site/options/other.md

@@ -13,9 +13,10 @@ $ typedoc --watch
 Use TypeScript's incremental compiler to watch source files for changes and
 build the docs on change. May be combined with `--emit`.
 
-> [!note] This mode will only detect changes to files watched by the TypeScript
-> compiler. Changes to other files (`README.md`, imported files with `@include` or
-> `@includeCode`) will not cause a rebuild.
+This mode detects changes to project documents, readme, custom JS/CSS,
+configuration files, files imported by `@include`/`@includeCode`, and any
+files explicitly registered by plugins as needing to be watched, as well
+as all your TypeScript source files.
 
 ## preserveWatchOutput
 

src/lib/application.ts

@@ -231,7 +231,9 @@ export class Application extends AbstractComponent<
         readers.forEach((r) => app.options.addReader(r));
         app.options.reset();
         app.setOptions(options, /* reportErrors */ false);
-        await app.options.read(new Logger());
+        await app.options.read(new Logger(), undefined, (path) =>
+            app.watchConfigFile(path),
+        );
         app.logger.level = app.options.getValue("logLevel");
 
         await loadPlugins(app, app.options.getValue("plugin"));
@@ -265,7 +267,9 @@ export class Application extends AbstractComponent<
     private async _bootstrap(options: Partial<TypeDocOptions>) {
         this.options.reset();
         this.setOptions(options, /* reportErrors */ false);
-        await this.options.read(this.logger);
+        await this.options.read(this.logger, undefined, (path) =>
+            this.watchConfigFile(path),
+        );
         this.setOptions(options);
         this.logger.level = this.options.getValue("logLevel");
         for (const [lang, locales] of Object.entries(
@@ -425,9 +429,49 @@ export class Application extends AbstractComponent<
         return project;
     }
 
-    public convertAndWatch(
+    private watchers = new Map<string, ts.FileWatcher>();
+    private _watchFile?: (path: string, shouldRestart?: boolean) => void;
+    private criticalFiles = new Set<string>();
+
+    private clearWatches() {
+        this.watchers.forEach((w) => w.close());
+        this.watchers.clear();
+    }
+
+    private watchConfigFile(path: string) {
+        this.criticalFiles.add(path);
+    }
+
+    /**
+     * Register that the current build depends on a file, so that in watch mode
+     * the build will be repeated.  Has no effect if a watch build is not
+     * running, or if the file has already been registered.
+     *
+     * @param path The file to watch.  It does not need to exist, and you should
+     * in fact register files you look for, but which do not exist, so that if
+     * they are created the build will re-run.  (e.g. if you look through a list
+     * of 5 possibilities and find the third, you should register the first 3.)
+     *
+     * @param shouldRestart Should the build be completely restarted?  (This is
+     * normally only used for configuration files -- i.e. files whose contents
+     * determine how conversion, rendering, or compiling will be done, as
+     * opposed to files that are only read *during* the conversion or
+     * rendering.)
+     */
+    public watchFile(path: string, shouldRestart = false) {
+        this._watchFile?.(path, shouldRestart);
+    }
+
+    /**
+     * Run a convert / watch process.
+     *
+     * @param success Callback to run after each convert, receiving the project
+     * @returns True if the watch process should be restarted due to a
+     * configuration change, false for an options error
+     */
+    public async convertAndWatch(
         success: (project: ProjectReflection) => Promise<void>,
-    ): void {
+    ): Promise<boolean> {
         if (
             !this.options.getValue("preserveWatchOutput") &&
             this.logger instanceof ConsoleLogger
@@ -459,7 +503,7 @@ export class Application extends AbstractComponent<
         // have reported in the first time... just error out for now. I'm not convinced anyone will actually notice.
         if (this.options.getFileNames().length === 0) {
             this.logger.error(this.i18n.solution_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         // Support for packages mode is currently unimplemented
@@ -468,7 +512,7 @@ export class Application extends AbstractComponent<
             this.entryPointStrategy !== EntryPointStrategy.Expand
         ) {
             this.logger.error(this.i18n.strategy_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         const tsconfigFile =
@@ -506,16 +550,69 @@ export class Application extends AbstractComponent<
 
         let successFinished = true;
         let currentProgram: ts.Program | undefined;
+        let lastProgram = currentProgram;
+        let restarting = false;
+
+        this._watchFile = (path: string, shouldRestart = false) => {
+            this.logger.verbose(
+                `Watching ${nicePath(path)}, shouldRestart=${shouldRestart}`,
+            );
+            if (this.watchers.has(path)) return;
+            this.watchers.set(
+                path,
+                host.watchFile(
+                    path,
+                    (file) => {
+                        if (shouldRestart) {
+                            restartMain(file);
+                        } else if (!currentProgram) {
+                            currentProgram = lastProgram;
+                            this.logger.info(
+                                this.i18n.file_0_changed_rebuilding(
+                                    nicePath(file),
+                                ),
+                            );
+                        }
+                        if (successFinished) runSuccess();
+                    },
+                    2000,
+                ),
+            );
+        };
+
+        /** resolver for the returned promise  */
+        let exitWatch: (restart: boolean) => unknown;
+        const restartMain = (file: string) => {
+            if (restarting) return;
+            this.logger.info(
+                this.i18n.file_0_changed_restarting(nicePath(file)),
+            );
+            restarting = true;
+            currentProgram = undefined;
+            this.clearWatches();
+            tsWatcher.close();
+        };
 
         const runSuccess = () => {
+            if (restarting && successFinished) {
+                successFinished = false;
+                exitWatch(true);
+                return;
+            }
+
             if (!currentProgram) {
                 return;
             }
 
             if (successFinished) {
-                if (this.options.getValue("emit") === "both") {
+                if (
+                    this.options.getValue("emit") === "both" &&
+                    currentProgram !== lastProgram
+                ) {
                     currentProgram.emit();
                 }
+                // Save for possible re-run due to non-.ts file change
+                lastProgram = currentProgram;
 
                 this.logger.resetErrors();
                 this.logger.resetWarnings();
@@ -527,6 +624,10 @@ export class Application extends AbstractComponent<
                 if (!entryPoints) {
                     return;
                 }
+                this.clearWatches();
+                this.criticalFiles.forEach((path) =>
+                    this.watchFile(path, true),
+                );
                 const project = this.converter.convert(entryPoints);
                 currentProgram = undefined;
                 successFinished = false;
@@ -563,14 +664,22 @@ export class Application extends AbstractComponent<
 
         const origAfterProgramCreate = host.afterProgramCreate;
         host.afterProgramCreate = (program) => {
-            if (ts.getPreEmitDiagnostics(program.getProgram()).length === 0) {
+            if (
+                !restarting &&
+                ts.getPreEmitDiagnostics(program.getProgram()).length === 0
+            ) {
                 currentProgram = program.getProgram();
                 runSuccess();
             }
             origAfterProgramCreate?.(program);
         };
 
-        ts.createWatchProgram(host);
+        const tsWatcher = ts.createWatchProgram(host);
+
+        // Don't return to caller until the watch needs to restart
+        return await new Promise((res) => {
+            exitWatch = res;
+        });
     }
 
     validate(project: ProjectReflection) {

src/lib/cli.ts

@@ -32,8 +32,8 @@ async function main() {
         if (exitCode !== ExitCodes.Watching) {
             app.logger.verbose(`Full run took ${Date.now() - start}ms`);
             logRunSummary(app.logger);
-            process.exit(exitCode);
         }
+        process.exit(exitCode);
     } catch (error) {
         console.error("TypeDoc exiting with unexpected error:");
         console.error(error);
@@ -73,11 +73,12 @@ async function run(app: td.Application) {
     }
 
     if (app.options.getValue("watch")) {
-        app.convertAndWatch(async (project) => {
+        return (await app.convertAndWatch(async (project) => {
             app.validate(project);
             await app.generateOutputs(project);
-        });
-        return ExitCodes.Watching;
+        }))
+            ? ExitCodes.Watching
+            : ExitCodes.OptionError;
     }
 
     const project = await app.convert();

src/lib/converter/converter.ts

@@ -688,6 +688,7 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
             frontmatter,
         );
 
+        this.application.watchFile(file.fileName);
         parent.addChild(docRefl);
         parent.project.registerReflection(docRefl, undefined, file.fileName);
         this.trigger(ConverterEvents.CREATE_DOCUMENT, undefined, docRefl);

src/lib/converter/plugins/IncludePlugin.ts

@@ -67,6 +67,7 @@ export class IncludePlugin extends ConverterComponent {
                 parseIncludeCodeTextPart(part.text);
 
             const file = path.resolve(relative, filename);
+            this.application.watchFile(file);
             if (included.includes(file) && part.tag === "@include") {
                 this.logger.error(
                     this.logger.i18n.include_0_in_1_specified_2_circular_include_3(

src/lib/converter/plugins/PackagePlugin.ts

@@ -98,6 +98,7 @@ export class PackagePlugin extends ConverterComponent {
 
         if (this.readme) {
             // Readme path provided, read only that file.
+            this.application.watchFile(this.readme);
             try {
                 this.readmeContents = readFile(this.readme);
                 this.readmeFile = this.readme;
@@ -119,6 +120,7 @@ export class PackagePlugin extends ConverterComponent {
             if (result) {
                 this.readmeFile = result.file;
                 this.readmeContents = result.content;
+                this.application.watchFile(this.readmeFile);
             }
         }
     }

src/lib/internationalization/locales/en.cts

@@ -15,6 +15,9 @@ export = {
         "The provided tsconfig file looks like a solution style tsconfig, which is not supported in watch mode",
     strategy_not_supported_in_watch_mode:
         "entryPointStrategy must be set to either resolve or expand for watch mode",
+    file_0_changed_restarting:
+        "Configuration file {0} changed: full restart required...",
+    file_0_changed_rebuilding: "File {0} changed: rebuilding output...",
     found_0_errors_and_1_warnings: "Found {0} errors and {1} warnings",
 
     output_0_could_not_be_generated:

src/lib/output/plugins/AssetsPlugin.ts

@@ -51,6 +51,7 @@ export class AssetsPlugin extends RendererComponent {
         }
 
         if (this.customCss) {
+            this.application.watchFile(this.customCss);
             if (existsSync(this.customCss)) {
                 copySync(this.customCss, join(dest, "custom.css"));
             } else {
@@ -63,6 +64,7 @@ export class AssetsPlugin extends RendererComponent {
         }
 
         if (this.customJs) {
+            this.application.watchFile(this.customJs);
             if (existsSync(this.customJs)) {
                 copySync(this.customJs, join(dest, "custom.js"));
             } else {

src/lib/utils/fs.ts

@@ -341,13 +341,15 @@ export function discoverInParentDirExactMatch<T extends {}>(
     name: string,
     dir: string,
     read: (content: string) => T | undefined,
+    usedFile?: (path: string) => void,
 ): { file: string; content: T } | undefined {
     if (!isDir(dir)) return;
 
     const reachedTopDirectory = (dirName: string) =>
         dirName === resolve(join(dirName, ".."));
 
     while (!reachedTopDirectory(dir)) {
+        usedFile?.(join(dir, name));
         try {
             const content = read(readFile(join(dir, name)));
             if (content != null) {
@@ -360,13 +362,21 @@ export function discoverInParentDirExactMatch<T extends {}>(
     }
 }
 
-export function discoverPackageJson(dir: string) {
-    return discoverInParentDirExactMatch("package.json", dir, (content) => {
-        const pkg: unknown = JSON.parse(content);
-        if (validate({ name: String, version: optional(String) }, pkg)) {
-            return pkg;
-        }
-    });
+export function discoverPackageJson(
+    dir: string,
+    usedFile?: (path: string) => void,
+) {
+    return discoverInParentDirExactMatch(
+        "package.json",
+        dir,
+        (content) => {
+            const pkg: unknown = JSON.parse(content);
+            if (validate({ name: String, version: optional(String) }, pkg)) {
+                return pkg;
+            }
+        },
+        usedFile,
+    );
 }
 
 // dir -> package name according to package.json in this or some parent dir

src/lib/utils/options/options.ts

@@ -56,8 +56,14 @@ export interface OptionsReader {
      * @param container the options container that provides declarations
      * @param logger logger to be used to report errors
      * @param cwd the directory which should be treated as the current working directory for option file discovery
+     * @param usedFile a callback to track files that were read or whose existence was checked, for purposes of restarting a build when watching files
      */
-    read(container: Options, logger: Logger, cwd: string): void | Promise<void>;
+    read(
+        container: Options,
+        logger: Logger,
+        cwd: string,
+        usedFile: (file: string) => void,
+    ): void | Promise<void>;
 }
 
 const optionSnapshots = new WeakMap<
@@ -194,9 +200,13 @@ export class Options {
         insertOrderSorted(this._readers, reader);
     }
 
-    async read(logger: Logger, cwd = process.cwd()) {
+    async read(
+        logger: Logger,
+        cwd = process.cwd(),
+        usedFile: (path: string) => void = () => {},
+    ) {
         for (const reader of this._readers) {
-            await reader.read(this, logger, cwd);
+            await reader.read(this, logger, cwd, usedFile);
         }
     }