@depup/typedoc 0.28.17-depup.0

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

@@ -0,0 +1,172 @@
+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;
+}

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

@@ -0,0 +1,33 @@
+import type { OptionsReader } from "../options.js";
+import type { Options } from "../options.js";
+import { type Logger } from "#utils";
+/**
+ * Obtains option values from typedoc.json
+ */
+export declare class TypeDocReader implements OptionsReader {
+    /**
+     * Should run before the tsconfig reader so that it can specify a tsconfig file to read.
+     */
+    order: number;
+    name: string;
+    supportsPackages: boolean;
+    /**
+     * Read user configuration from a typedoc.json or typedoc.js configuration file.
+     */
+    read(container: Options, logger: Logger, cwd: string, usedFile: (path: string) => void): Promise<void>;
+    /**
+     * Read the given options file + any extended files.
+     * @param file
+     * @param container
+     * @param logger
+     */
+    private readFile;
+    /**
+     * Search for the configuration file given path
+     *
+     * @param  path Path to the typedoc.(js|json) file. If path is a directory
+     *   typedoc file will be attempted to be found at the root of this path
+     * @returns the typedoc.(js|json) file path or undefined
+     */
+    private findTypedocFile;
+}

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

@@ -0,0 +1,136 @@
+import { dirname, join, resolve } from "path";
+import * as FS from "fs";
+import ts from "typescript";
+import { ok } from "assert";
+import { nicePath, normalizePath } from "../../paths.js";
+import { isFile } from "../../fs.js";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+import { i18n } from "#utils";
+/**
+ * Obtains option values from typedoc.json
+ */
+export class TypeDocReader {
+    /**
+     * Should run before the tsconfig reader so that it can specify a tsconfig file to read.
+     */
+    order = 100;
+    name = "typedoc-json";
+    supportsPackages = true;
+    /**
+     * Read user configuration from a typedoc.json or typedoc.js configuration file.
+     */
+    async read(container, logger, cwd, usedFile) {
+        const path = container.getValue("options") || cwd;
+        const file = this.findTypedocFile(path, usedFile);
+        if (!file) {
+            if (container.isSet("options")) {
+                logger.error(i18n.options_file_0_does_not_exist(nicePath(path)));
+            }
+            return;
+        }
+        const seen = new Set();
+        await this.readFile(file, container, logger, seen);
+    }
+    /**
+     * Read the given options file + any extended files.
+     * @param file
+     * @param container
+     * @param logger
+     */
+    async readFile(file, container, logger, seen) {
+        if (seen.has(file)) {
+            logger.error(i18n.circular_reference_extends_0(nicePath(file)));
+            return;
+        }
+        seen.add(file);
+        let fileContent;
+        if (file.endsWith(".json") || file.endsWith(".jsonc")) {
+            const readResult = ts.readConfigFile(normalizePath(file), (path) => FS.readFileSync(path, "utf-8"));
+            if (readResult.error) {
+                logger.error(i18n.failed_read_options_file_0(nicePath(file)));
+                return;
+            }
+            else {
+                fileContent = readResult.config;
+            }
+        }
+        else {
+            try {
+                // On Windows, we need to ensure this path is a file path.
+                // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                const esmPath = pathToFileURL(file).toString();
+                fileContent = await (await import(esmPath)).default;
+            }
+            catch (error) {
+                logger.error(i18n.failed_read_options_file_0(nicePath(file)));
+                logger.error(String(error instanceof Error ? error.message : error));
+                return;
+            }
+        }
+        if (typeof fileContent !== "object" || !fileContent) {
+            logger.error(i18n.failed_read_options_file_0(nicePath(file)));
+            return;
+        }
+        // clone option object to avoid of property changes in re-calling this file
+        const data = { ...fileContent };
+        delete data["$schema"]; // Useful for better autocompletion, should not be read as a key.
+        if ("extends" in data) {
+            const resolver = createRequire(file);
+            const extended = getStringArray(data["extends"]);
+            for (const extendedFile of extended) {
+                let resolvedParent;
+                try {
+                    resolvedParent = resolver.resolve(extendedFile);
+                }
+                catch {
+                    logger.error(i18n.failed_resolve_0_to_file_in_1(extendedFile, nicePath(file)));
+                    continue;
+                }
+                await this.readFile(resolvedParent, container, logger, seen);
+            }
+            delete data["extends"];
+        }
+        for (const [key, val] of Object.entries(data)) {
+            try {
+                container.setValue(key, val, resolve(dirname(file)));
+            }
+            catch (error) {
+                ok(error instanceof Error);
+                logger.error(error.message);
+            }
+        }
+    }
+    /**
+     * Search for the configuration file given path
+     *
+     * @param  path Path to the typedoc.(js|json) file. If path is a directory
+     *   typedoc file will be attempted to be found at the root of this path
+     * @returns the typedoc.(js|json) file path or undefined
+     */
+    findTypedocFile(path, usedFile) {
+        path = resolve(path);
+        return [
+            path,
+            join(path, "typedoc.json"),
+            join(path, "typedoc.jsonc"),
+            join(path, "typedoc.config.js"),
+            join(path, "typedoc.config.cjs"),
+            join(path, "typedoc.config.mjs"),
+            join(path, "typedoc.js"),
+            join(path, "typedoc.cjs"),
+            join(path, "typedoc.mjs"),
+            join(path, ".config/typedoc.json"),
+            join(path, ".config/typedoc.jsonc"),
+            join(path, ".config/typedoc.config.js"),
+            join(path, ".config/typedoc.config.cjs"),
+            join(path, ".config/typedoc.config.mjs"),
+            join(path, ".config/typedoc.js"),
+            join(path, ".config/typedoc.cjs"),
+            join(path, ".config/typedoc.mjs"),
+        ].find((file) => (usedFile?.(file), isFile(file)));
+    }
+}
+function getStringArray(arg) {
+    return Array.isArray(arg) ? arg.map(String) : [String(arg)];
+}

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

@@ -0,0 +1 @@
+export { addTypeDocOptions } from "./typedoc.js";

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

@@ -0,0 +1 @@
+export { addTypeDocOptions } from "./typedoc.js";

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

@@ -0,0 +1,2 @@
+import type { Options } from "../options.js";
+export declare function addTypeDocOptions(options: Pick<Options, "addDeclaration">): void;