@depup/typedoc 0.28.17-depup.0

package/dist/lib/utils/options/tsdoc-defaults.d.ts

@@ -0,0 +1,6 @@
+export declare const tsdocBlockTags: readonly ["@defaultValue", "@deprecated", "@example", "@jsx", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam"];
+export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@jsx", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@extends", "@augments", "@yields", "@group", "@groupDescription", "@import", "@inheritDoc", "@license", "@module", "@mergeModuleWith", "@prop", "@property", "@return", "@satisfies", "@since", "@sortStrategy", "@template", "@this", "@type", "@typedef", "@summary", "@preventInline", "@inlineType", "@preventExpand", "@expandType"];
+export declare const tsdocInlineTags: readonly ["@link", "@inheritDoc", "@label"];
+export declare const inlineTags: readonly ["@link", "@inheritDoc", "@label", "@linkcode", "@linkplain", "@include", "@includeCode"];
+export declare const tsdocModifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual"];
+export declare const modifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual", "@abstract", "@class", "@disableGroups", "@enum", "@event", "@expand", "@hidden", "@hideCategories", "@hideconstructor", "@hideGroups", "@ignore", "@inline", "@interface", "@namespace", "@function", "@overload", "@private", "@protected", "@showCategories", "@showGroups", "@useDeclaredType", "@primaryExport"];

package/dist/lib/utils/options/tsdoc-defaults.js

@@ -0,0 +1,94 @@
+// If updating these lists, also update tsdoc.json
+export const tsdocBlockTags = [
+    "@defaultValue",
+    "@deprecated",
+    "@example",
+    "@jsx",
+    "@param",
+    "@privateRemarks",
+    "@remarks",
+    "@returns",
+    "@see",
+    "@throws",
+    "@typeParam",
+];
+export const blockTags = [
+    ...tsdocBlockTags,
+    "@author",
+    "@callback",
+    "@category",
+    "@categoryDescription",
+    "@default",
+    "@document",
+    "@extends",
+    "@augments", // Alias for @extends
+    "@yields",
+    "@group",
+    "@groupDescription",
+    "@import",
+    "@inheritDoc",
+    "@license",
+    "@module",
+    "@mergeModuleWith",
+    "@prop",
+    "@property",
+    "@return",
+    "@satisfies",
+    "@since",
+    "@sortStrategy",
+    "@template", // Alias for @typeParam
+    "@this",
+    "@type",
+    "@typedef",
+    "@summary",
+    "@preventInline",
+    "@inlineType",
+    "@preventExpand",
+    "@expandType",
+];
+export const tsdocInlineTags = ["@link", "@inheritDoc", "@label"];
+export const inlineTags = [
+    ...tsdocInlineTags,
+    "@linkcode",
+    "@linkplain",
+    "@include",
+    "@includeCode",
+];
+export const tsdocModifierTags = [
+    "@alpha",
+    "@beta",
+    "@eventProperty",
+    "@experimental",
+    "@internal",
+    "@override",
+    "@packageDocumentation",
+    "@public",
+    "@readonly",
+    "@sealed",
+    "@virtual",
+];
+export const modifierTags = [
+    ...tsdocModifierTags,
+    "@abstract",
+    "@class",
+    "@disableGroups",
+    "@enum",
+    "@event",
+    "@expand",
+    "@hidden",
+    "@hideCategories",
+    "@hideconstructor",
+    "@hideGroups",
+    "@ignore",
+    "@inline",
+    "@interface",
+    "@namespace",
+    "@function",
+    "@overload",
+    "@private",
+    "@protected",
+    "@showCategories",
+    "@showGroups",
+    "@useDeclaredType",
+    "@primaryExport",
+];

package/dist/lib/utils/package-manifest.d.ts

@@ -0,0 +1,11 @@
+import { type MinimatchSet } from "./paths.js";
+import { type GlobString, type Logger, type NormalizedPath } from "#utils";
+/**
+ * Loads a package.json and validates that it is a JSON Object
+ */
+export declare function loadPackageManifest(logger: Logger, packageJsonPath: string): Record<string, unknown> | undefined;
+/**
+ * Given a list of (potentially wildcard containing) package paths,
+ * return all the actual package folders found.
+ */
+export declare function expandPackages(logger: Logger, packageJsonDir: NormalizedPath, workspaces: GlobString[], exclude: MinimatchSet): string[];

package/dist/lib/utils/package-manifest.js

@@ -0,0 +1,84 @@
+// Utilities to support the inspection of node package "manifests"
+import { dirname } from "path";
+import { glob, readFile } from "./fs.js";
+import { createGlobString, nicePath, normalizePath } from "./paths.js";
+import { i18n } from "#utils";
+/**
+ * Helper for the TS type system to understand hasOwnProperty
+ * and narrow a type appropriately.
+ * @param obj the receiver of the hasOwnProperty method call
+ * @param prop the property to test for
+ */
+function hasOwnProperty(obj, prop) {
+    return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+/**
+ * Loads a package.json and validates that it is a JSON Object
+ */
+export function loadPackageManifest(logger, packageJsonPath) {
+    const packageJson = JSON.parse(readFile(packageJsonPath));
+    if (typeof packageJson !== "object" || !packageJson) {
+        logger.error(i18n.file_0_not_an_object(nicePath(packageJsonPath)));
+        return undefined;
+    }
+    return packageJson;
+}
+/**
+ * Load the paths to packages specified in a Yarn workspace package JSON
+ * Returns undefined if packageJSON does not define a Yarn workspace
+ * @param packageJSON the package json object
+ */
+function getPackagePaths(packageJSON) {
+    if (Array.isArray(packageJSON["workspaces"]) &&
+        packageJSON["workspaces"].every((i) => typeof i === "string")) {
+        return packageJSON["workspaces"];
+    }
+    if (typeof packageJSON["workspaces"] === "object" &&
+        packageJSON["workspaces"] != null) {
+        const workspaces = packageJSON["workspaces"];
+        if (hasOwnProperty(workspaces, "packages") &&
+            Array.isArray(workspaces["packages"]) &&
+            workspaces["packages"].every((i) => typeof i === "string")) {
+            return workspaces["packages"];
+        }
+    }
+    return undefined;
+}
+/**
+ * Given a list of (potentially wildcard containing) package paths,
+ * return all the actual package folders found.
+ */
+export function expandPackages(logger, packageJsonDir, workspaces, exclude) {
+    // Technically npm and Yarn workspaces don't support recursive nesting,
+    // however we support the passing of paths to either packages or
+    // to the root of a workspace tree in our params and so we could here
+    // be dealing with either a root or a leaf. So let's do this recursively,
+    // as it actually is simpler from an implementation perspective anyway.
+    return workspaces.flatMap((workspace) => {
+        const expandedPackageJsonPaths = glob(createGlobString(packageJsonDir, `${workspace}/package.json`), packageJsonDir);
+        if (expandedPackageJsonPaths.length === 0) {
+            logger.warn(i18n.entry_point_0_did_not_match_any_packages(nicePath(workspace)));
+        }
+        else if (expandedPackageJsonPaths.length !== 1) {
+            logger.verbose(`Expanded ${nicePath(workspace)} to:\n\t${expandedPackageJsonPaths
+                .map(nicePath)
+                .join("\n\t")}`);
+        }
+        return expandedPackageJsonPaths.flatMap((packageJsonPath) => {
+            if (exclude.matchesAny(dirname(packageJsonPath))) {
+                return [];
+            }
+            const packageJson = loadPackageManifest(logger, packageJsonPath);
+            if (packageJson === undefined) {
+                return [];
+            }
+            const packagePaths = getPackagePaths(packageJson);
+            if (packagePaths === undefined) {
+                // Assume this is a single package repo
+                return [dirname(packageJsonPath)];
+            }
+            // This is a workspace root package, recurse
+            return expandPackages(logger, normalizePath(dirname(packageJsonPath)), packagePaths.map(p => createGlobString(normalizePath(dirname(packageJsonPath)), p)), exclude);
+        });
+    });
+}

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

@@ -0,0 +1,27 @@
+import { type GlobString, type NormalizedPath } from "#utils";
+import { Minimatch } from "minimatch";
+export declare class MinimatchSet {
+    readonly patterns: Minimatch[];
+    constructor(patterns: GlobString[]);
+    matchesAny(path: string): boolean;
+}
+export declare function splitGlobToPathAndSpecial(glob: string): {
+    modifiers: string;
+    path: string;
+    glob: string;
+};
+export declare function createGlobString(relativeTo: NormalizedPath, glob: string): GlobString;
+/**
+ * Get the longest directory path common to all files.
+ */
+export declare function getCommonPath(files: readonly string[]): NormalizedPath;
+export declare function getCommonDirectory(files: readonly string[]): NormalizedPath;
+export declare function deriveRootDir(globPaths: GlobString[]): NormalizedPath;
+export declare function nicePath(absPath: string): string;
+/**
+ * Normalize the given path.
+ *
+ * @param path  The path that should be normalized.
+ * @returns The normalized path.
+ */
+export declare function normalizePath(path: string): NormalizedPath;

package/dist/lib/utils/paths.js

@@ -0,0 +1,127 @@
+import { countMatches, filterMap } from "#utils";
+import { Minimatch } from "minimatch";
+import { dirname, isAbsolute, relative, resolve } from "path";
+export class MinimatchSet {
+    patterns;
+    constructor(patterns) {
+        this.patterns = patterns.map(p => new Minimatch(p, { dot: true }));
+    }
+    matchesAny(path) {
+        return this.patterns.some(p => {
+            return p.match(path);
+        });
+    }
+}
+function escapeGlob(glob) {
+    return glob.replace(/[?*()[\]\\{}]/g, "\\$&");
+}
+function isGlobalGlob(glob) {
+    const start = glob.match(/^[!#]+/)?.[0].length ?? 0;
+    return glob.startsWith("**", start);
+}
+export function splitGlobToPathAndSpecial(glob) {
+    const modifiers = glob.match(/^[!#]+/)?.[0] ?? "";
+    const noModifierGlob = glob.substring(modifiers.length);
+    if (isGlobalGlob(glob)) {
+        return { modifiers, path: "", glob: noModifierGlob };
+    }
+    const mini = new Minimatch(noModifierGlob, { dot: true });
+    const basePaths = mini.set.map(set => {
+        const stop = set.findIndex((part) => typeof part !== "string");
+        if (stop === -1) {
+            return set.join("/");
+        }
+        else {
+            return set.slice(0, stop).join("/");
+        }
+    });
+    const base = getCommonPath(basePaths);
+    if (base) {
+        const skipIndex = countMatches(base, "/") + 1;
+        const globPart = mini.globParts.map(s => s.slice(skipIndex));
+        // This isn't ideal, it will end up re-writing the glob if braces are used,
+        // but I don't want to write a glob minimizer at this point, and this should
+        // handle all the edge cases as we're just using Minimatch's glob parsing
+        const resultingGlob = globPart.length === 1
+            ? globPart[0].join("/")
+            : `{${globPart.map(s => s.join("/")).join(",")}}`;
+        return { modifiers, path: base, glob: resultingGlob };
+    }
+    return { modifiers, path: "", glob: noModifierGlob };
+}
+export function createGlobString(relativeTo, glob) {
+    if (isAbsolute(glob) || isGlobalGlob(glob))
+        return glob;
+    const split = splitGlobToPathAndSpecial(glob);
+    const leadingPath = normalizePath(resolve(relativeTo, split.path));
+    if (!split.glob) {
+        return split.modifiers + escapeGlob(leadingPath);
+    }
+    return `${split.modifiers}${escapeGlob(leadingPath)}/${split.glob}`;
+}
+/**
+ * Get the longest directory path common to all files.
+ */
+export function getCommonPath(files) {
+    if (!files.length) {
+        return "";
+    }
+    const roots = files.map((f) => f.split("/"));
+    if (roots.length === 1) {
+        return roots[0].join("/");
+    }
+    let i = 0;
+    while (i < roots[0].length &&
+        new Set(roots.map((part) => part[i])).size === 1) {
+        i++;
+    }
+    return roots[0].slice(0, i).join("/");
+}
+export function getCommonDirectory(files) {
+    if (files.length === 1) {
+        return normalizePath(dirname(files[0]));
+    }
+    return getCommonPath(files);
+}
+export function deriveRootDir(globPaths) {
+    const globs = new MinimatchSet(globPaths).patterns;
+    const rootPaths = globs.flatMap((glob, i) => filterMap(glob.set, (set) => {
+        const stop = set.findIndex((part) => typeof part !== "string");
+        if (stop === -1) {
+            return globPaths[i];
+        }
+        else {
+            const kept = set.slice(0, stop).join("/");
+            return globPaths[i].substring(0, globPaths[i].indexOf(kept) + kept.length);
+        }
+    }));
+    return getCommonDirectory(rootPaths);
+}
+export function nicePath(absPath) {
+    if (!isAbsolute(absPath))
+        return absPath;
+    const relativePath = relative(process.cwd(), absPath);
+    if (relativePath.startsWith("..")) {
+        return normalizePath(absPath);
+    }
+    return `./${normalizePath(relativePath)}`;
+}
+/**
+ * Normalize the given path.
+ *
+ * @param path  The path that should be normalized.
+ * @returns The normalized path.
+ */
+export function normalizePath(path) {
+    if (process.platform === "win32") {
+        // Ensure forward slashes
+        path = path.replace(/\\/g, "/");
+        // Msys2 git on windows will give paths which use unix-style
+        // absolute paths, like /c/users/you. Since the rest of TypeDoc
+        // expects drive letters, convert it to that here.
+        path = path.replace(/^\/([a-zA-Z])\//, (_m, m1) => `${m1}:/`);
+        // Make Windows drive letters upper case
+        path = path.replace(/^([^:]+):\//, (_m, m1) => m1.toUpperCase() + ":/");
+    }
+    return path;
+}

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

@@ -0,0 +1,6 @@
+export declare function bench<T extends (..._: any) => any>(fn: T, name?: string): T;
+declare function BenchField<T extends (..._: any) => any>(_value: undefined, context: ClassFieldDecoratorContext<unknown, T>): (value: T) => T;
+declare function BenchMethod<T extends (..._: any) => any>(value: T, context: ClassMethodDecoratorContext): T;
+export declare const Bench: typeof BenchField & typeof BenchMethod;
+export declare function measure<T>(cb: () => T): T;
+export {};

package/dist/lib/utils/perf.js

@@ -0,0 +1,86 @@
+/* eslint-disable no-console */
+const benchmarks = [];
+export function bench(fn, name = fn.name) {
+    const matching = benchmarks.find((b) => b.name === name);
+    const timer = matching || {
+        name,
+        calls: 0,
+        time: 0,
+    };
+    if (!matching)
+        benchmarks.push(timer);
+    return function bench(...args) {
+        timer.calls++;
+        const start = performance.now();
+        const end = () => (timer.time += performance.now() - start);
+        let result;
+        try {
+            result = fn.apply(this, args);
+        }
+        catch (error) {
+            end();
+            throw error;
+        }
+        if (result instanceof Promise) {
+            result.then((res) => {
+                end();
+                return res;
+            }, (reason) => {
+                end();
+                throw reason;
+            });
+        }
+        else {
+            end();
+        }
+        return result;
+    };
+}
+function BenchField(_value, context) {
+    let runner;
+    return function (value) {
+        if (!runner) {
+            const className = context.static
+                ? this.name
+                : Object.getPrototypeOf(this).constructor.name;
+            runner = bench(value, `${className}.${String(context.name)}`);
+        }
+        return function (...args) {
+            return runner.apply(this, args);
+        };
+    };
+}
+function BenchMethod(value, context) {
+    let runner;
+    return function (...args) {
+        if (!runner) {
+            const className = context.static
+                ? this.name
+                : Object.getPrototypeOf(this).constructor.name;
+            runner = bench(value, `${className}.${String(context.name)}`);
+        }
+        return runner.apply(this, args);
+    };
+}
+export const Bench = (value, context) => {
+    if (context.kind === "field") {
+        return BenchField(value, context);
+    }
+    return BenchMethod(value, context);
+};
+export function measure(cb) {
+    return bench(cb, "measure()")();
+}
+process.on("exit", () => {
+    if (!benchmarks.length)
+        return;
+    const table = benchmarks.map((b) => {
+        return {
+            Benchmarked: b.name,
+            Calls: b.calls,
+            "Time (ms)": Math.round(b.time * 100) / 100,
+            "Average (ms)": Math.round((b.time / b.calls) * 100) / 100,
+        };
+    });
+    console.table(table);
+});

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

@@ -0,0 +1,3 @@
+import type { Application } from "../application.js";
+import { type NormalizedPathOrModuleOrFunction } from "#utils";
+export declare function loadPlugins(app: Application, plugins: readonly NormalizedPathOrModuleOrFunction[]): Promise<void>;

package/dist/lib/utils/plugins.js

@@ -0,0 +1,61 @@
+import { isAbsolute } from "path";
+import { pathToFileURL } from "url";
+import { nicePath } from "./paths.js";
+import { i18n } from "#utils";
+export async function loadPlugins(app, plugins) {
+    for (const plugin of plugins) {
+        const pluginDisplay = getPluginDisplayName(plugin);
+        try {
+            let initFunction;
+            if (typeof plugin === "function") {
+                initFunction = plugin;
+            }
+            else {
+                let instance;
+                // Try importing first to avoid warnings about requiring ESM being experimental.
+                // If that fails due to importing a directory, fall back to require.
+                try {
+                    // On Windows, we need to ensure this path is a file path.
+                    // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                    const esmPath = isAbsolute(plugin)
+                        ? pathToFileURL(plugin).toString()
+                        : plugin;
+                    instance = await import(esmPath);
+                }
+                catch (error) {
+                    if (error.code === "ERR_UNSUPPORTED_DIR_IMPORT") {
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        instance = require(plugin);
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+                initFunction = instance.load;
+            }
+            if (typeof initFunction === "function") {
+                await initFunction(app);
+                app.logger.info(i18n.loaded_plugin_0(pluginDisplay));
+            }
+            else {
+                app.logger.error(i18n.invalid_plugin_0_missing_load_function(pluginDisplay));
+            }
+        }
+        catch (error) {
+            app.logger.error(i18n.plugin_0_could_not_be_loaded(pluginDisplay));
+            if (error instanceof Error && error.stack) {
+                app.logger.error(error.stack);
+            }
+        }
+    }
+}
+function getPluginDisplayName(plugin) {
+    if (typeof plugin === "function") {
+        return plugin.name || "function";
+    }
+    const path = nicePath(plugin);
+    if (path.startsWith("./node_modules/")) {
+        return path.substring("./node_modules/".length);
+    }
+    return plugin;
+}

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

@@ -0,0 +1,5 @@
+import { type ProjectReflection, type ReferenceType, Reflection } from "../models/index.js";
+export declare function discoverAllReferenceTypes(project: ProjectReflection, forExportValidation: boolean): {
+    type: ReferenceType;
+    owner: Reflection;
+}[];

package/dist/lib/utils/reflections.js

@@ -0,0 +1,64 @@
+import { ContainerReflection, DeclarationReflection, makeRecursiveVisitor, ParameterReflection, Reflection, SignatureReflection, TypeParameterReflection, } from "../models/index.js";
+export function discoverAllReferenceTypes(project, forExportValidation) {
+    let current = project;
+    const queue = [];
+    const result = [];
+    const visitor = makeRecursiveVisitor({
+        reference(type) {
+            result.push({ type, owner: current });
+        },
+        reflection(type) {
+            queue.push(type.declaration);
+        },
+    });
+    const add = (item) => {
+        if (!item)
+            return;
+        if (item instanceof Reflection) {
+            queue.push(item);
+        }
+        else {
+            queue.push(...item);
+        }
+    };
+    do {
+        if (current instanceof ContainerReflection) {
+            add(current.children);
+        }
+        if (current instanceof DeclarationReflection) {
+            current.type?.visit(visitor);
+            add(current.typeParameters);
+            add(current.signatures);
+            add(current.indexSignatures);
+            add(current.getSignature);
+            add(current.setSignature);
+            current.overwrites?.visit(visitor);
+            current.implementedTypes?.forEach((type) => type.visit(visitor));
+            if (!forExportValidation) {
+                current.inheritedFrom?.visit(visitor);
+                current.implementationOf?.visit(visitor);
+                current.extendedTypes?.forEach((t) => t.visit(visitor));
+                current.extendedBy?.forEach((t) => t.visit(visitor));
+                current.implementedBy?.forEach((t) => t.visit(visitor));
+            }
+        }
+        if (current instanceof SignatureReflection) {
+            add(current.parameters);
+            add(current.typeParameters);
+            current.type?.visit(visitor);
+            current.overwrites?.visit(visitor);
+            if (!forExportValidation) {
+                current.inheritedFrom?.visit(visitor);
+                current.implementationOf?.visit(visitor);
+            }
+        }
+        if (current instanceof ParameterReflection) {
+            current.type?.visit(visitor);
+        }
+        if (current instanceof TypeParameterReflection) {
+            current.type?.visit(visitor);
+            current.default?.visit(visitor);
+        }
+    } while ((current = queue.shift()));
+    return result;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Module which handles sorting reflections according to a user specified strategy.
+ * @module
+ */
+import type { DeclarationReflection } from "../models/DeclarationReflection.js";
+import type { Options } from "./options/index.js";
+import type { DocumentReflection } from "../models/index.js";
+export declare const SORT_STRATEGIES: readonly ["source-order", "alphabetical", "alphabetical-ignoring-documents", "enum-value-ascending", "enum-value-descending", "enum-member-source-order", "static-first", "instance-first", "visibility", "required-first", "kind", "external-last", "documents-first", "documents-last"];
+export type SortStrategy = (typeof SORT_STRATEGIES)[number];
+export declare function isValidSortStrategy(strategy: string): strategy is SortStrategy;
+export declare function getSortFunction(opts: Options, strategies?: readonly SortStrategy[]): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;