typedoc 0.28.19 → 0.28.20

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

@@ -1,273 +0,0 @@
-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.js

@@ -1,109 +0,0 @@
-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.js

@@ -1,4 +0,0 @@
-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.js

@@ -1,40 +0,0 @@
-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.js

@@ -1,172 +0,0 @@
-import { dirname, join, resolve } from "path";
-import ts from "typescript";
-import { isFile } from "../../fs.js";
-import { ok } from "assert";
-import { i18n, unique, Validation } from "#utils";
-import { nicePath, normalizePath } from "../../paths.js";
-import { createRequire } from "module";
-import { tsdocBlockTags, tsdocInlineTags, tsdocModifierTags } from "../tsdoc-defaults.js";
-import { findTsConfigFile, getTypeDocOptionsFromTsConfig, readTsConfig } from "../../tsconfig.js";
-import { diagnostics } from "../../loggers.js";
-function isSupportForTags(obj) {
-    return (Validation.validate({}, obj) &&
-        Object.entries(obj).every(([key, val]) => {
-            return (/^@[a-zA-Z][a-zA-Z0-9]*$/.test(key) && typeof val === "boolean");
-        }));
-}
-const tsDocSchema = {
-    $schema: Validation.optional(String),
-    extends: Validation.optional([Array, String]),
-    noStandardTags: Validation.optional(Boolean),
-    tagDefinitions: Validation.optional([
-        Array,
-        {
-            tagName: Validation.isTagString,
-            syntaxKind: ["inline", "block", "modifier"],
-            allowMultiple: Validation.optional(Boolean),
-            [Validation.additionalProperties]: false,
-        },
-    ]),
-    supportForTags: Validation.optional(isSupportForTags),
-    // The official parser has code to support for these two, but
-    // the schema doesn't allow them... just silently ignore them for now.
-    supportedHtmlElements: Validation.optional({}),
-    reportUnsupportedHtmlElements: Validation.optional(Boolean),
-    [Validation.additionalProperties]: false,
-};
-export class TSConfigReader {
-    /**
-     * Note: Runs after the {@link TypeDocReader}.
-     */
-    order = 200;
-    name = "tsconfig-json";
-    supportsPackages = true;
-    seenTsdocPaths = new Set();
-    read(container, logger, cwd, usedFile) {
-        const file = container.getValue("tsconfig") || cwd;
-        let fileToRead = findTsConfigFile(file, usedFile);
-        if (!fileToRead) {
-            // If the user didn't give us this option, we shouldn't complain about not being able to find it.
-            if (container.isSet("tsconfig")) {
-                logger.error(i18n.tsconfig_file_0_does_not_exist(nicePath(file)));
-            }
-            return;
-        }
-        fileToRead = normalizePath(resolve(fileToRead));
-        logger.verbose(`Reading tsconfig at ${nicePath(fileToRead)}`);
-        this.addTagsFromTsdocJson(container, logger, resolve(fileToRead));
-        const parsed = readTsConfig(fileToRead, logger);
-        if (!parsed) {
-            return;
-        }
-        diagnostics(logger, parsed.errors);
-        if (parsed.errors.length) {
-            return;
-        }
-        const typedocOptions = getTypeDocOptionsFromTsConfig(fileToRead);
-        if (typedocOptions.options) {
-            logger.error(i18n.tsconfig_file_specifies_options_file());
-            delete typedocOptions.options;
-        }
-        if (typedocOptions.tsconfig) {
-            logger.error(i18n.tsconfig_file_specifies_tsconfig_file());
-            delete typedocOptions.tsconfig;
-        }
-        container.setCompilerOptions(parsed.fileNames, parsed.options, parsed.projectReferences);
-        for (const [key, val] of Object.entries(typedocOptions || {})) {
-            try {
-                // We catch the error, so can ignore the strict type checks
-                container.setValue(key, val, join(fileToRead, ".."));
-            }
-            catch (error) {
-                ok(error instanceof Error);
-                logger.error(error.message);
-            }
-        }
-    }
-    addTagsFromTsdocJson(container, logger, tsconfig) {
-        this.seenTsdocPaths.clear();
-        const tsdoc = join(dirname(tsconfig), "tsdoc.json");
-        if (!isFile(tsdoc)) {
-            return;
-        }
-        const overwritten = ["blockTags", "inlineTags", "modifierTags"].filter((opt) => container.isSet(opt));
-        if (overwritten.length) {
-            logger.warn(i18n.tags_0_defined_in_typedoc_json_overwritten_by_tsdoc_json(overwritten.join(", ")));
-        }
-        const config = this.readTsDoc(logger, tsdoc);
-        if (!config)
-            return;
-        const supported = (tag) => {
-            return config.supportForTags
-                ? !!config.supportForTags[tag.tagName]
-                : true;
-        };
-        const blockTags = [];
-        const inlineTags = [];
-        const modifierTags = [];
-        if (!config.noStandardTags) {
-            blockTags.push(...tsdocBlockTags);
-            inlineTags.push(...tsdocInlineTags);
-            modifierTags.push(...tsdocModifierTags);
-        }
-        for (const { tagName, syntaxKind } of config.tagDefinitions?.filter(supported) || []) {
-            const arr = {
-                block: blockTags,
-                inline: inlineTags,
-                modifier: modifierTags,
-            }[syntaxKind];
-            arr.push(tagName);
-        }
-        container.setValue("blockTags", unique(blockTags));
-        container.setValue("inlineTags", unique(inlineTags));
-        container.setValue("modifierTags", unique(modifierTags));
-    }
-    readTsDoc(logger, path) {
-        if (this.seenTsdocPaths.has(path)) {
-            logger.error(i18n.circular_reference_extends_0(nicePath(path)));
-            return;
-        }
-        this.seenTsdocPaths.add(path);
-        const { config, error } = ts.readConfigFile(normalizePath(path), ts.sys.readFile);
-        if (error) {
-            logger.error(i18n.failed_read_tsdoc_json_0(nicePath(path)));
-            return;
-        }
-        if (!Validation.validate(tsDocSchema, config)) {
-            logger.error(i18n.invalid_tsdoc_json_0(nicePath(path)));
-            return;
-        }
-        const workingConfig = {};
-        if (config.extends) {
-            const resolver = createRequire(path);
-            for (const extendedPath of config.extends) {
-                let resolvedPath;
-                try {
-                    resolvedPath = resolver.resolve(extendedPath);
-                }
-                catch {
-                    logger.error(i18n.failed_resolve_0_to_file_in_1(extendedPath, nicePath(path)));
-                    return;
-                }
-                const parentConfig = this.readTsDoc(logger, resolvedPath);
-                if (!parentConfig)
-                    return;
-                mergeConfigs(parentConfig, workingConfig);
-            }
-        }
-        mergeConfigs(config, workingConfig);
-        return workingConfig;
-    }
-}
-function mergeConfigs(from, into) {
-    if (from.supportForTags) {
-        into.supportForTags ||= {};
-        Object.assign(into.supportForTags, from.supportForTags);
-    }
-    if (from.tagDefinitions) {
-        into.tagDefinitions ||= [];
-        into.tagDefinitions.push(...from.tagDefinitions);
-    }
-    into.noStandardTags = from.noStandardTags ?? into.noStandardTags;
-}