@depup/typedoc 0.28.17-depup.0

package/dist/lib/utils/options/options.d.ts

@@ -0,0 +1,199 @@
+import ts from "typescript";
+import type { Application } from "../../../index.js";
+import { type DeclarationOption, type KeyToDeclaration, type TypeDocOptionMap, type TypeDocOptions, type TypeDocOptionValues } from "./declaration.js";
+import { type Logger, type NeverIfInternal } from "#utils";
+/**
+ * Describes an option reader that discovers user configuration and converts it to the
+ * TypeDoc format.
+ */
+export interface OptionsReader {
+    /**
+     * Readers will be processed according to their orders.
+     * A higher order indicates that the reader should be called *later*.
+     *
+     * Note that to preserve expected behavior, the argv reader must have both the lowest
+     * order so that it may set the location of config files used by other readers and
+     * the highest order so that it can override settings from lower order readers.
+     */
+    readonly order: number;
+    /**
+     * The name of this reader so that it may be removed by plugins without the plugin
+     * accessing the instance performing the read. Multiple readers may have the same
+     * name.
+     */
+    readonly name: string;
+    /**
+     * Flag to indicate that this reader should be included in sub-options objects created
+     * to read options for packages mode.
+     */
+    readonly supportsPackages: boolean;
+    /**
+     * Read options from the reader's source and place them in the options parameter.
+     * Options without a declared name may be treated as if they were declared with type
+     * {@link ParameterType.Mixed}. Options which have been declared must be converted to the
+     * correct type. As an alternative to doing this conversion in the reader,
+     * the reader may use {@link Options.setValue}, which will correctly convert values.
+     * @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, usedFile: (file: string) => void): void | Promise<void>;
+}
+/**
+ * Maintains a collection of option declarations split into TypeDoc options
+ * and TypeScript options. Ensures options are of the correct type for calling
+ * code.
+ *
+ * ### Option Discovery
+ *
+ * Since plugins commonly add custom options, and TypeDoc does not permit options which have
+ * not been declared to be set, options must be read twice. The first time options are read,
+ * a noop logger is passed so that any errors are ignored. Then, after loading plugins, options
+ * are read again, this time with the logger specified by the application.
+ *
+ * Options are read in a specific order.
+ * 1. argv (0) - Must be read first since it should change the files read when
+ *    passing --options or --tsconfig.
+ * 2. typedoc-json (100) - Read next so that it can specify the tsconfig.json file to read.
+ * 3. tsconfig-json (200) - Last config file reader, cannot specify the typedoc.json file to read.
+ * 4. argv (300) - Read argv again since any options set there should override those set in config
+ *    files.
+ *
+ * @group None
+ * @summary Contains all of TypeDoc's option declarations & values
+ */
+export declare class Options {
+    private _readers;
+    private _declarations;
+    private _values;
+    private _setOptions;
+    private _compilerOptions;
+    private _fileNames;
+    private _projectReferences;
+    /**
+     * In packages mode, the directory of the package being converted.
+     */
+    packageDir?: string;
+    constructor();
+    /**
+     * Clones the options, intended for use in packages mode.
+     */
+    copyForPackage(packageDir: string): Options;
+    /**
+     * Take a snapshot of option values now, used in tests only.
+     * @internal
+     */
+    snapshot(): {
+        __optionSnapshot: never;
+    };
+    /**
+     * Take a snapshot of option values now, used in tests only.
+     * @internal
+     */
+    restore(snapshot: {
+        __optionSnapshot: never;
+    }): void;
+    /**
+     * Resets the option bag to all default values.
+     * If a name is provided, will only reset that name.
+     */
+    reset(name?: keyof TypeDocOptions): void;
+    reset(name?: NeverIfInternal<string>): void;
+    /**
+     * Adds an option reader that will be used to read configuration values
+     * from the command line, configuration files, or other locations.
+     * @param reader
+     */
+    addReader(reader: OptionsReader): void;
+    read(logger: Logger, cwd?: string, usedFile?: (path: string) => void): Promise<void>;
+    /**
+     * Adds an option declaration to the container with extra type checking to ensure that
+     * the runtime type is consistent with the declared type.
+     * @param declaration The option declaration that should be added.
+     */
+    addDeclaration<K extends keyof TypeDocOptions>(declaration: {
+        name: K;
+    } & KeyToDeclaration<K>): void;
+    /**
+     * Adds an option declaration to the container.
+     * @param declaration The option declaration that should be added.
+     */
+    addDeclaration(declaration: NeverIfInternal<Readonly<DeclarationOption>>): void;
+    /**
+     * Gets a declaration by one of its names.
+     * @param name
+     */
+    getDeclaration(name: string): Readonly<DeclarationOption> | undefined;
+    /**
+     * Gets all declared options.
+     */
+    getDeclarations(): Readonly<DeclarationOption>[];
+    /**
+     * Checks if the given option's value is deeply strict equal to the default.
+     * @param name
+     */
+    isSet(name: keyof TypeDocOptions): boolean;
+    isSet(name: NeverIfInternal<string>): boolean;
+    /**
+     * Gets all of the TypeDoc option values defined in this option container.
+     */
+    getRawValues(): Readonly<Partial<TypeDocOptionValues>>;
+    /**
+     * Gets a value for the given option key, throwing if the option has not been declared.
+     * @param name
+     */
+    getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptionValues[K];
+    getValue(name: NeverIfInternal<string>): unknown;
+    /**
+     * Sets the given declared option. Throws if setting the option fails.
+     * @param name
+     * @param value
+     * @param configPath the directory to resolve Path type values against
+     */
+    setValue<K extends keyof TypeDocOptions>(name: K, value: Exclude<TypeDocOptions[K], undefined>, configPath?: string): void;
+    setValue(name: NeverIfInternal<string>, value: NeverIfInternal<unknown>, configPath?: NeverIfInternal<string>): void;
+    /**
+     * Gets the set compiler options.
+     */
+    getCompilerOptions(logger: Logger): ts.CompilerOptions;
+    /** @internal */
+    fixCompilerOptions(options: Readonly<ts.CompilerOptions>, logger: Logger): ts.CompilerOptions;
+    /**
+     * Gets the file names discovered through reading a tsconfig file.
+     */
+    getFileNames(): readonly string[];
+    /**
+     * Gets the project references - used in solution style tsconfig setups.
+     */
+    getProjectReferences(): readonly ts.ProjectReference[];
+    /**
+     * Sets the compiler options that will be used to get a TS program.
+     */
+    setCompilerOptions(fileNames: readonly string[], options: ts.CompilerOptions, projectReferences: readonly ts.ProjectReference[] | undefined): void;
+    /**
+     * Discover similar option names to the given name, for use in error reporting.
+     */
+    getSimilarOptions(missingName: string): string[];
+    /**
+     * Get the help message to be displayed to the user if `--help` is passed.
+     */
+    getHelp(): string;
+}
+/**
+ * Binds an option to an accessor. Does not register the option.
+ *
+ * Note: This is a standard ES decorator. It will not work with pre-TS 5.0 experimental decorators enabled.
+ */
+export declare function Option<K extends keyof TypeDocOptionMap>(name: K): (_: unknown, _context: ClassAccessorDecoratorContext<{
+    application: Application;
+} | {
+    options: Options;
+}, TypeDocOptionValues[K]>) => {
+    get(this: {
+        application: Application;
+    } | {
+        options: Options;
+    }): TypeDocOptionValues[K];
+    set(_value: never): never;
+};

package/dist/lib/utils/options/options.js

@@ -0,0 +1,273 @@
+import ts from "typescript";
+import { resolve } from "path";
+import { ParameterType } from "./declaration.js";
+import { normalizePath } from "../paths.js";
+import { convert, getDefaultValue, } from "./declaration.js";
+import { addTypeDocOptions } from "./sources/index.js";
+import { getOptionsHelp } from "./help.js";
+import { getSimilarValues, i18n, insertOrderSorted, unique } from "#utils";
+const optionSnapshots = new WeakMap();
+/**
+ * Maintains a collection of option declarations split into TypeDoc options
+ * and TypeScript options. Ensures options are of the correct type for calling
+ * code.
+ *
+ * ### Option Discovery
+ *
+ * Since plugins commonly add custom options, and TypeDoc does not permit options which have
+ * not been declared to be set, options must be read twice. The first time options are read,
+ * a noop logger is passed so that any errors are ignored. Then, after loading plugins, options
+ * are read again, this time with the logger specified by the application.
+ *
+ * Options are read in a specific order.
+ * 1. argv (0) - Must be read first since it should change the files read when
+ *    passing --options or --tsconfig.
+ * 2. typedoc-json (100) - Read next so that it can specify the tsconfig.json file to read.
+ * 3. tsconfig-json (200) - Last config file reader, cannot specify the typedoc.json file to read.
+ * 4. argv (300) - Read argv again since any options set there should override those set in config
+ *    files.
+ *
+ * @group None
+ * @summary Contains all of TypeDoc's option declarations & values
+ */
+export class Options {
+    _readers = [];
+    _declarations = new Map();
+    _values = {};
+    _setOptions = new Set();
+    _compilerOptions = {};
+    _fileNames = [];
+    _projectReferences = [];
+    /**
+     * In packages mode, the directory of the package being converted.
+     */
+    packageDir;
+    constructor() {
+        addTypeDocOptions(this);
+    }
+    /**
+     * Clones the options, intended for use in packages mode.
+     */
+    copyForPackage(packageDir) {
+        const options = new Options();
+        options.packageDir = packageDir;
+        options._readers = this._readers.filter((reader) => reader.supportsPackages);
+        options._declarations = new Map(this._declarations);
+        options.reset();
+        for (const [key, val] of Object.entries(this.getValue("packageOptions"))) {
+            options.setValue(key, val, packageDir);
+        }
+        return options;
+    }
+    /**
+     * Take a snapshot of option values now, used in tests only.
+     * @internal
+     */
+    snapshot() {
+        const key = {};
+        optionSnapshots.set(key, {
+            values: { ...this._values },
+            set: new Set(this._setOptions),
+        });
+        return key;
+    }
+    /**
+     * Take a snapshot of option values now, used in tests only.
+     * @internal
+     */
+    restore(snapshot) {
+        const data = optionSnapshots.get(snapshot);
+        this._values = { ...data.values };
+        this._setOptions = new Set(data.set);
+    }
+    reset(name) {
+        if (name != null) {
+            const declaration = this.getDeclaration(name);
+            if (!declaration) {
+                throw new Error(`Cannot reset an option (${name}) which has not been declared.`);
+            }
+            this._values[declaration.name] = getDefaultValue(declaration);
+            this._setOptions.delete(declaration.name);
+        }
+        else {
+            for (const declaration of this.getDeclarations()) {
+                this._values[declaration.name] = getDefaultValue(declaration);
+            }
+            this._setOptions.clear();
+            this._compilerOptions = {};
+            this._fileNames = [];
+        }
+    }
+    /**
+     * Adds an option reader that will be used to read configuration values
+     * from the command line, configuration files, or other locations.
+     * @param reader
+     */
+    addReader(reader) {
+        insertOrderSorted(this._readers, reader);
+    }
+    async read(logger, cwd = process.cwd(), usedFile = () => { }) {
+        for (const reader of this._readers) {
+            await reader.read(this, logger, cwd, usedFile);
+        }
+    }
+    addDeclaration(declaration) {
+        const decl = this.getDeclaration(declaration.name);
+        if (decl) {
+            throw new Error(`The option ${declaration.name} has already been registered`);
+        }
+        else {
+            this._declarations.set(declaration.name, declaration);
+        }
+        this._values[declaration.name] = getDefaultValue(declaration);
+    }
+    /**
+     * Gets a declaration by one of its names.
+     * @param name
+     */
+    getDeclaration(name) {
+        return this._declarations.get(name);
+    }
+    /**
+     * Gets all declared options.
+     */
+    getDeclarations() {
+        return unique(this._declarations.values());
+    }
+    isSet(name) {
+        if (!this._declarations.has(name)) {
+            throw new Error(`Tried to check if an undefined option (${name}) was set`);
+        }
+        return this._setOptions.has(name);
+    }
+    /**
+     * Gets all of the TypeDoc option values defined in this option container.
+     */
+    getRawValues() {
+        return this._values;
+    }
+    getValue(name) {
+        const declaration = this.getDeclaration(name);
+        if (!declaration) {
+            const nearNames = this.getSimilarOptions(name);
+            throw new Error(i18n.unknown_option_0_you_may_have_meant_1(name, nearNames.join("\n\t")));
+        }
+        return this._values[declaration.name];
+    }
+    setValue(name, value, configPath) {
+        const declaration = this.getDeclaration(name);
+        if (!declaration) {
+            const nearNames = this.getSimilarOptions(name);
+            throw new Error(i18n.unknown_option_0_you_may_have_meant_1(name, nearNames.join("\n\t")));
+        }
+        let oldValue = this._values[declaration.name];
+        if (typeof oldValue === "undefined") {
+            oldValue = getDefaultValue(declaration);
+        }
+        const converted = convert(value, declaration, configPath ?? process.cwd(), oldValue);
+        if (declaration.type === ParameterType.Flags) {
+            this._values[declaration.name] = Object.assign({}, this._values[declaration.name], converted);
+        }
+        else if (declaration.name === "outputs") {
+            // This is very unfortunate... there's probably some smarter way to define options
+            // so that this can be done intelligently via the convert function.
+            this._values[declaration.name] = converted.map((c) => {
+                return {
+                    ...c,
+                    path: normalizePath(resolve(configPath ?? process.cwd(), c.path)),
+                };
+            });
+        }
+        else {
+            this._values[declaration.name] = converted;
+        }
+        this._setOptions.add(name);
+    }
+    /**
+     * Gets the set compiler options.
+     */
+    getCompilerOptions(logger) {
+        return this.fixCompilerOptions(this._compilerOptions, logger);
+    }
+    /** @internal */
+    fixCompilerOptions(options, logger) {
+        const overrides = this.getValue("compilerOptions");
+        const result = { ...options };
+        if (overrides) {
+            const tsOptions = ts.convertCompilerOptionsFromJson(overrides, ".", "typedoc-overrides.json");
+            if (tsOptions.errors.length) {
+                for (const error of tsOptions.errors) {
+                    logger.error(i18n.failed_to_apply_compilerOptions_overrides_0(ts.flattenDiagnosticMessageText(error.messageText, "\n")));
+                }
+            }
+            else {
+                for (const key in overrides) {
+                    result[key] = tsOptions.options[key];
+                }
+            }
+        }
+        if (this.getValue("emit") !== "both") {
+            result.noEmit = true;
+            delete result.emitDeclarationOnly;
+        }
+        return result;
+    }
+    /**
+     * Gets the file names discovered through reading a tsconfig file.
+     */
+    getFileNames() {
+        return this._fileNames;
+    }
+    /**
+     * Gets the project references - used in solution style tsconfig setups.
+     */
+    getProjectReferences() {
+        return this._projectReferences;
+    }
+    /**
+     * Sets the compiler options that will be used to get a TS program.
+     */
+    setCompilerOptions(fileNames, options, projectReferences) {
+        // We do this here instead of in the tsconfig reader so that API consumers which
+        // supply a program to `Converter.convert` instead of letting TypeDoc create one
+        // can just set the compiler options, and not need to know about this mapping.
+        // It feels a bit like a hack... but it's better to have it here than to put it
+        // in Application or Converter.
+        if (options.stripInternal && !this.isSet("excludeInternal")) {
+            this.setValue("excludeInternal", true);
+        }
+        this._fileNames = fileNames;
+        this._compilerOptions = { ...options };
+        this._projectReferences = projectReferences ?? [];
+    }
+    /**
+     * Discover similar option names to the given name, for use in error reporting.
+     */
+    getSimilarOptions(missingName) {
+        return getSimilarValues(this._declarations.keys(), missingName);
+    }
+    /**
+     * Get the help message to be displayed to the user if `--help` is passed.
+     */
+    getHelp() {
+        return getOptionsHelp(this);
+    }
+}
+/**
+ * Binds an option to an accessor. Does not register the option.
+ *
+ * Note: This is a standard ES decorator. It will not work with pre-TS 5.0 experimental decorators enabled.
+ */
+export function Option(name) {
+    return (_, _context) => {
+        return {
+            get() {
+                const options = "options" in this ? this.options : this.application.options;
+                return options.getValue(name);
+            },
+            set(_value) {
+                throw new Error(`Options may not be set via the Option decorator when setting ${name}`);
+            },
+        };
+    };
+}

package/dist/lib/utils/options/readers/arguments.d.ts

@@ -0,0 +1,15 @@
+import type { Options, OptionsReader } from "../index.js";
+import { type Logger } from "#utils";
+/**
+ * Obtains option values from command-line arguments
+ */
+export declare class ArgumentsReader implements OptionsReader {
+    readonly name = "arguments";
+    readonly order: number;
+    readonly supportsPackages = false;
+    private args;
+    private skipErrorReporting;
+    constructor(priority: number, args?: string[]);
+    ignoreErrors(): this;
+    read(container: Options, logger: Logger): void;
+}

package/dist/lib/utils/options/readers/arguments.js

@@ -0,0 +1,109 @@
+import { ok } from "assert";
+import { ParameterType } from "../declaration.js";
+import { i18n } from "#utils";
+const ARRAY_OPTION_TYPES = new Set([
+    ParameterType.Array,
+    ParameterType.PathArray,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    ParameterType.ModuleArray,
+    ParameterType.PluginArray,
+    ParameterType.GlobArray,
+]);
+/**
+ * Obtains option values from command-line arguments
+ */
+export class ArgumentsReader {
+    name = "arguments";
+    order;
+    supportsPackages = false;
+    args;
+    skipErrorReporting = false;
+    constructor(priority, args = process.argv.slice(2)) {
+        this.order = priority;
+        this.args = args;
+    }
+    ignoreErrors() {
+        this.skipErrorReporting = true;
+        return this;
+    }
+    read(container, logger) {
+        // Make container's type more lax, we do the appropriate checks manually.
+        const options = container;
+        const seen = new Set();
+        let index = 0;
+        const trySet = (name, value) => {
+            try {
+                options.setValue(name, value);
+            }
+            catch (err) {
+                ok(err instanceof Error);
+                if (!this.skipErrorReporting) {
+                    logger.error(err.message);
+                }
+            }
+        };
+        while (index < this.args.length) {
+            const name = this.args[index];
+            const decl = name.startsWith("-")
+                ? (index++, options.getDeclaration(name.replace(/^--?/, "")))
+                : options.getDeclaration("entryPoints");
+            if (decl) {
+                if (decl.configFileOnly) {
+                    if (!this.skipErrorReporting) {
+                        logger.error(i18n.option_0_can_only_be_specified_by_config_file(decl.name));
+                    }
+                    continue;
+                }
+                if (seen.has(decl.name) && ARRAY_OPTION_TYPES.has(decl.type)) {
+                    trySet(decl.name, options.getValue(decl.name).concat(this.args[index]));
+                }
+                else if (decl.type === ParameterType.Boolean ||
+                    decl.type === ParameterType.Flags) {
+                    const value = String(this.args.at(index)).toLowerCase();
+                    if (value === "true" || value === "false") {
+                        trySet(decl.name, value === "true");
+                    }
+                    else {
+                        trySet(decl.name, true);
+                        // Bool option didn't consume the next argument as expected.
+                        index--;
+                    }
+                }
+                else {
+                    if (index === this.args.length) {
+                        // Only boolean values have optional values.
+                        if (!this.skipErrorReporting) {
+                            logger.warn(i18n.option_0_expected_a_value_but_none_provided(decl.name));
+                        }
+                    }
+                    trySet(decl.name, this.args[index]);
+                }
+                seen.add(decl.name);
+                index++;
+                continue;
+            }
+            if (name.includes(".")) {
+                const actualName = name.split(".")[0].replace(/^--?/, "");
+                const decl = options.getDeclaration(actualName);
+                if (decl && decl.type === ParameterType.Flags) {
+                    const flagName = name.split(".", 2)[1];
+                    const value = String(this.args.at(index)).toLowerCase();
+                    if (value === "true" || value === "false") {
+                        trySet(decl.name, { [flagName]: value === "true" });
+                    }
+                    else {
+                        trySet(decl.name, { [flagName]: true });
+                        // Bool option didn't consume the next argument as expected.
+                        index--;
+                    }
+                    index++;
+                    continue;
+                }
+            }
+            if (!this.skipErrorReporting) {
+                logger.error(i18n.unknown_option_0_may_have_meant_1(name, options.getSimilarOptions(name).join("\n\t")));
+            }
+            index++;
+        }
+    }
+}

package/dist/lib/utils/options/readers/index.d.ts

@@ -0,0 +1,4 @@
+export { ArgumentsReader } from "./arguments.js";
+export { PackageJsonReader } from "./package-json.js";
+export { TSConfigReader } from "./tsconfig.js";
+export { TypeDocReader } from "./typedoc.js";

package/dist/lib/utils/options/readers/index.js

@@ -0,0 +1,4 @@
+export { ArgumentsReader } from "./arguments.js";
+export { PackageJsonReader } from "./package-json.js";
+export { TSConfigReader } from "./tsconfig.js";
+export { TypeDocReader } from "./typedoc.js";

package/dist/lib/utils/options/readers/package-json.d.ts

@@ -0,0 +1,9 @@
+import type { OptionsReader } from "../index.js";
+import type { Options } from "../options.js";
+import { type Logger } from "#utils";
+export declare class PackageJsonReader implements OptionsReader {
+    order: number;
+    supportsPackages: boolean;
+    name: string;
+    read(container: Options, logger: Logger, cwd: string, usedFile: (path: string) => void): void;
+}

package/dist/lib/utils/options/readers/package-json.js

@@ -0,0 +1,40 @@
+import { ok } from "assert";
+import { nicePath } from "../../paths.js";
+import { discoverPackageJson } from "../../fs.js";
+import { dirname } from "path";
+import { i18n } from "#utils";
+export class PackageJsonReader {
+    // Should run after the TypeDoc config reader but before the TS config
+    // reader, so that it can still specify a path to a `tsconfig.json` file.
+    order = 150;
+    supportsPackages = true;
+    name = "package-json";
+    read(container, logger, cwd, usedFile) {
+        const result = discoverPackageJson(cwd, usedFile);
+        if (!result) {
+            return;
+        }
+        const { file, content } = result;
+        if ("typedoc" in content) {
+            logger.warn(i18n.typedoc_key_in_0_ignored(nicePath(file)));
+        }
+        const optsKey = "typedocOptions";
+        if (!(optsKey in content)) {
+            return;
+        }
+        const opts = content[optsKey];
+        if (opts === null || typeof opts !== "object") {
+            logger.error(i18n.typedoc_options_must_be_object_in_0(nicePath(file)));
+            return;
+        }
+        for (const [opt, val] of Object.entries(opts)) {
+            try {
+                container.setValue(opt, val, dirname(file));
+            }
+            catch (err) {
+                ok(err instanceof Error);
+                logger.error(err.message);
+            }
+        }
+    }
+}

package/dist/lib/utils/options/readers/tsconfig.d.ts

@@ -0,0 +1,14 @@
+import type { Options, OptionsReader } from "../options.js";
+import { type Logger } from "#utils";
+export declare class TSConfigReader implements OptionsReader {
+    /**
+     * Note: Runs after the {@link TypeDocReader}.
+     */
+    order: number;
+    name: string;
+    supportsPackages: boolean;
+    private seenTsdocPaths;
+    read(container: Options, logger: Logger, cwd: string, usedFile?: (path: string) => void): void;
+    private addTagsFromTsdocJson;
+    private readTsDoc;
+}