@depup/typedoc 0.28.17-depup.0

package/dist/lib/utils/sort.js

@@ -0,0 +1,153 @@
+/**
+ * Module which handles sorting reflections according to a user specified strategy.
+ * @module
+ */
+import { ReflectionKind } from "../models/kind.js";
+import * as OptionDefaults from "./options/defaults.js";
+export const SORT_STRATEGIES = [
+    "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",
+];
+// Return true if a < b
+const sorts = {
+    "source-order"(a, b) {
+        // This is going to be somewhat ambiguous. No way around that. Treat the first
+        // declaration of a symbol as its ordering declaration.
+        const aSymbol = a.project.getSymbolIdFromReflection(a);
+        const bSymbol = b.project.getSymbolIdFromReflection(b);
+        if (aSymbol && bSymbol) {
+            if (aSymbol.packageName < bSymbol.packageName) {
+                return true;
+            }
+            if (aSymbol.packageName === bSymbol.packageName &&
+                aSymbol.packagePath < bSymbol.packagePath) {
+                return true;
+            }
+            if (aSymbol.packageName === bSymbol.packageName &&
+                aSymbol.packagePath === bSymbol.packagePath &&
+                aSymbol.pos < bSymbol.pos) {
+                return true;
+            }
+            return false;
+        }
+        // Someone is doing something weird. Fail to re-order. This could happen if someone
+        // tries to sort with a reflection that has been removed from the project.
+        return false;
+    },
+    alphabetical(a, b) {
+        return a.name.localeCompare(b.name) < 0;
+    },
+    "alphabetical-ignoring-documents"(a, b) {
+        if (a.kindOf(ReflectionKind.Document) ||
+            b.kindOf(ReflectionKind.Document)) {
+            return false;
+        }
+        return a.name.localeCompare(b.name) < 0;
+    },
+    "enum-value-ascending"(a, b) {
+        if (a.kind == ReflectionKind.EnumMember &&
+            b.kind == ReflectionKind.EnumMember) {
+            const aRefl = a;
+            const bRefl = b;
+            const aValue = aRefl.type?.type === "literal" ? aRefl.type.value : -Infinity;
+            const bValue = bRefl.type?.type === "literal" ? bRefl.type.value : -Infinity;
+            return aValue < bValue;
+        }
+        return false;
+    },
+    "enum-value-descending"(a, b) {
+        if (a.kind == ReflectionKind.EnumMember &&
+            b.kind == ReflectionKind.EnumMember) {
+            const aRefl = a;
+            const bRefl = b;
+            const aValue = aRefl.type?.type === "literal" ? aRefl.type.value : -Infinity;
+            const bValue = bRefl.type?.type === "literal" ? bRefl.type.value : -Infinity;
+            return bValue < aValue;
+        }
+        return false;
+    },
+    "enum-member-source-order"(a, b, data) {
+        if (a.kind === ReflectionKind.EnumMember &&
+            b.kind === ReflectionKind.EnumMember) {
+            return sorts["source-order"](a, b, data);
+        }
+        return false;
+    },
+    "static-first"(a, b) {
+        return a.flags.isStatic && !b.flags.isStatic;
+    },
+    "instance-first"(a, b) {
+        return !a.flags.isStatic && b.flags.isStatic;
+    },
+    visibility(a, b) {
+        // Note: flags.isPublic may not be set on public members. It will only be set
+        // if the user explicitly marks members as public. Therefore, we can't use it
+        // here to get a reliable sort order.
+        if (a.flags.isPrivate) {
+            return false; // Not sorted before anything
+        }
+        if (a.flags.isProtected) {
+            return b.flags.isPrivate; // Sorted before privates
+        }
+        if (b.flags.isPrivate || b.flags.isProtected) {
+            return true; // We are public, sort before b if b is less visible
+        }
+        return false;
+    },
+    "required-first"(a, b) {
+        return !a.flags.isOptional && b.flags.isOptional;
+    },
+    kind(a, b, { kindSortOrder }) {
+        return kindSortOrder.indexOf(a.kind) < kindSortOrder.indexOf(b.kind);
+    },
+    "external-last"(a, b) {
+        return !a.flags.isExternal && b.flags.isExternal;
+    },
+    "documents-first"(a, b) {
+        return (a.kindOf(ReflectionKind.Document) &&
+            !b.kindOf(ReflectionKind.Document));
+    },
+    "documents-last"(a, b) {
+        return (!a.kindOf(ReflectionKind.Document) &&
+            b.kindOf(ReflectionKind.Document));
+    },
+};
+export function isValidSortStrategy(strategy) {
+    return SORT_STRATEGIES.includes(strategy);
+}
+export function getSortFunction(opts, strategies = opts.getValue("sort")) {
+    const kindSortOrder = opts
+        .getValue("kindSortOrder")
+        .map((k) => ReflectionKind[k]);
+    for (const kind of OptionDefaults.kindSortOrder) {
+        if (!kindSortOrder.includes(ReflectionKind[kind])) {
+            kindSortOrder.push(ReflectionKind[kind]);
+        }
+    }
+    const data = { kindSortOrder };
+    return function sortReflections(reflections) {
+        reflections.sort((a, b) => {
+            for (const s of strategies) {
+                if (sorts[s](a, b, data)) {
+                    return -1;
+                }
+                if (sorts[s](b, a, data)) {
+                    return 1;
+                }
+            }
+            return 0;
+        });
+    };
+}

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

@@ -0,0 +1,5 @@
+import ts from "typescript";
+import type { Logger } from "#utils";
+export declare function findTsConfigFile(path: string, usedFile?: (path: string) => void): string | undefined;
+export declare function getTypeDocOptionsFromTsConfig(file: string): any;
+export declare function readTsConfig(path: string, logger: Logger): ts.ParsedCommandLine | undefined;

package/dist/lib/utils/tsconfig.js

@@ -0,0 +1,60 @@
+import ts from "typescript";
+import { isDir, isFile, readFile } from "./fs.js";
+import { createRequire } from "module";
+import { diagnostic, diagnostics } from "./loggers.js";
+export function findTsConfigFile(path, usedFile) {
+    let fileToRead = path;
+    if (isDir(fileToRead)) {
+        fileToRead = ts.findConfigFile(path, (file) => (usedFile?.(file), isFile(file)));
+    }
+    if (!fileToRead || !isFile(fileToRead)) {
+        return;
+    }
+    return fileToRead;
+}
+// We don't need recursive read checks because that would cause a diagnostic
+// when reading the tsconfig for compiler options, which happens first, and we bail before
+// doing this in that case.
+export function getTypeDocOptionsFromTsConfig(file) {
+    const readResult = ts.readConfigFile(file, readFile);
+    const result = {};
+    if (readResult.error) {
+        return result;
+    }
+    if ("extends" in readResult.config) {
+        const resolver = createRequire(file);
+        const extended = Array.isArray(readResult.config.extends)
+            ? readResult.config.extends.map(String)
+            : [String(readResult.config.extends)];
+        for (const extendedFile of extended) {
+            let resolvedParent;
+            try {
+                resolvedParent = resolver.resolve(extendedFile);
+            }
+            catch {
+                continue;
+            }
+            Object.assign(result, getTypeDocOptionsFromTsConfig(resolvedParent));
+        }
+    }
+    if ("typedocOptions" in readResult.config) {
+        Object.assign(result, readResult.config.typedocOptions);
+    }
+    return result;
+}
+const tsConfigCache = {};
+export function readTsConfig(path, logger) {
+    if (tsConfigCache[path]) {
+        return tsConfigCache[path];
+    }
+    const parsed = ts.getParsedCommandLineOfConfigFile(path, {}, {
+        ...ts.sys,
+        onUnRecoverableConfigFileDiagnostic: diagnostic.bind(null, logger),
+    });
+    if (!parsed) {
+        return;
+    }
+    diagnostics(logger, parsed.errors);
+    tsConfigCache[path] = parsed;
+    return parsed;
+}

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

@@ -0,0 +1,3 @@
+import ts from "typescript";
+export declare function getQualifiedName(symbol: ts.Symbol, defaultName: string): string;
+export declare function getHumanName(name: string): string;

package/dist/lib/utils/tsutils.js

@@ -0,0 +1,23 @@
+import ts from "typescript";
+export function getQualifiedName(symbol, defaultName) {
+    // Two implementation options for this one:
+    // 1. Use the internal symbol.parent, to walk up until we hit a source file symbol (if in a module)
+    //    or undefined (if in a global file)
+    // 2. Use checker.getFullyQualifiedName and parse out the name from the returned string.
+    // The symbol.parent method is easier to check for now.
+    let sym = symbol;
+    const parts = [];
+    while (sym && !sym.declarations?.some(ts.isSourceFile)) {
+        parts.unshift(getHumanName(sym.name));
+        sym = sym.parent;
+    }
+    return parts.join(".") || defaultName;
+}
+export function getHumanName(name) {
+    // Unique symbols get a name that will change between runs of the compiler.
+    const match = /^__@(.*)@\d+$/.exec(name);
+    if (match) {
+        return `[${match[1]}]`;
+    }
+    return name;
+}

package/dist/lib/utils-common/array.d.ts

@@ -0,0 +1,57 @@
+export declare const emptyArray: readonly [];
+/**
+ * Inserts an item into an array sorted by priority. If two items have the same priority,
+ * the item will be inserted later will be placed later in the array.
+ * Higher priority is placed earlier in the array.
+ * @param arr modified by inserting item.
+ * @param item
+ */
+export declare function insertPrioritySorted<T extends {
+    priority: number;
+}>(arr: T[], item: T): T[];
+/**
+ * Inserts an item into an array sorted by order. If two items have the same order,
+ * the item inserted later will be placed later in the array.
+ * The array will be sorted with lower order being placed sooner.
+ * @param arr modified by inserting item.
+ * @param item
+ */
+export declare function insertOrderSorted<T extends {
+    order: number;
+}>(arr: T[], item: T): T[];
+/**
+ * Performs a binary search of a given array, returning the index of the first item
+ * for which `partition` returns true. Returns the -1 if there are no items in `arr`
+ * such that `partition(item)` is true.
+ * @param arr
+ * @param partition should return true while less than the partition point.
+ */
+export declare function binaryFindPartition<T>(arr: readonly T[], partition: (item: T) => boolean): number;
+/**
+ * Removes an item from the array if the array exists and the item is included
+ * within it.
+ * @param arr
+ * @param item
+ */
+export declare function removeIfPresent<T>(arr: T[] | undefined, item: T): void;
+/**
+ * Remove items in an array which match a predicate.
+ * @param arr
+ * @param predicate
+ */
+export declare function removeIf<T>(arr: T[], predicate: (item: T) => boolean): void;
+/**
+ * Filters out duplicate values from the given iterable.
+ * @param arr
+ */
+export declare function unique<T>(arr: Iterable<T> | undefined): T[];
+export declare function partition<T>(iter: Iterable<T>, predicate: (item: T) => boolean): [T[], T[]];
+export declare function zip<T extends Iterable<any>[]>(...args: T): Iterable<{
+    [K in keyof T]: T[K] extends Iterable<infer U> ? U : T[K];
+}>;
+export declare function filterMap<T, U>(iter: Iterable<T> | undefined, fn: (item: T) => U | undefined): U[];
+export declare function firstDefined<T, U>(array: readonly T[], callback: (element: T, index: number) => U | undefined): U | undefined;
+export declare function filter<T>(array: readonly T[] | undefined, predicate: (value: T, index: number, array: readonly T[]) => boolean): readonly T[];
+export declare function aggregate<T>(arr: T[], fn: (item: T) => number): number;
+export declare function joinArray<T>(arr: readonly T[] | undefined, joiner: string, mapper: (item: T) => string): string;
+export declare function maxElementByScore<T>(arr: readonly T[], score: (a: T) => number): T | undefined;

package/dist/lib/utils-common/array.js

@@ -0,0 +1,152 @@
+export const emptyArray = [];
+/**
+ * Inserts an item into an array sorted by priority. If two items have the same priority,
+ * the item will be inserted later will be placed later in the array.
+ * Higher priority is placed earlier in the array.
+ * @param arr modified by inserting item.
+ * @param item
+ */
+export function insertPrioritySorted(arr, item) {
+    const index = binaryFindPartition(arr, (v) => v.priority < item.priority);
+    arr.splice(index === -1 ? arr.length : index, 0, item);
+    return arr;
+}
+/**
+ * Inserts an item into an array sorted by order. If two items have the same order,
+ * the item inserted later will be placed later in the array.
+ * The array will be sorted with lower order being placed sooner.
+ * @param arr modified by inserting item.
+ * @param item
+ */
+export function insertOrderSorted(arr, item) {
+    const index = binaryFindPartition(arr, (v) => v.order > item.order);
+    arr.splice(index === -1 ? arr.length : index, 0, item);
+    return arr;
+}
+/**
+ * Performs a binary search of a given array, returning the index of the first item
+ * for which `partition` returns true. Returns the -1 if there are no items in `arr`
+ * such that `partition(item)` is true.
+ * @param arr
+ * @param partition should return true while less than the partition point.
+ */
+export function binaryFindPartition(arr, partition) {
+    if (arr.length === 0) {
+        return -1;
+    }
+    let low = 0, high = arr.length - 1;
+    while (high > low) {
+        const mid = low + Math.floor((high - low) / 2);
+        if (partition(arr[mid])) {
+            high = mid;
+        }
+        else {
+            low = mid + 1;
+        }
+    }
+    return partition(arr[low]) ? low : -1;
+}
+/**
+ * Removes an item from the array if the array exists and the item is included
+ * within it.
+ * @param arr
+ * @param item
+ */
+export function removeIfPresent(arr, item) {
+    if (!arr) {
+        return;
+    }
+    const index = arr.indexOf(item);
+    if (index !== -1) {
+        arr.splice(index, 1);
+    }
+}
+/**
+ * Remove items in an array which match a predicate.
+ * @param arr
+ * @param predicate
+ */
+export function removeIf(arr, predicate) {
+    for (let i = 0; i < arr.length; i++) {
+        if (predicate(arr[i])) {
+            arr.splice(i, 1);
+            i--;
+        }
+    }
+}
+/**
+ * Filters out duplicate values from the given iterable.
+ * @param arr
+ */
+export function unique(arr) {
+    return Array.from(new Set(arr));
+}
+export function partition(iter, predicate) {
+    const left = [];
+    const right = [];
+    for (const item of iter) {
+        if (predicate(item)) {
+            left.push(item);
+        }
+        else {
+            right.push(item);
+        }
+    }
+    return [left, right];
+}
+export function* zip(...args) {
+    const iterators = args.map((x) => x[Symbol.iterator]());
+    for (;;) {
+        const next = iterators.map((i) => i.next());
+        if (next.some((v) => v.done)) {
+            break;
+        }
+        yield next.map((v) => v.value);
+    }
+}
+export function filterMap(iter, fn) {
+    const result = [];
+    for (const item of iter || []) {
+        const newItem = fn(item);
+        if (newItem !== void 0) {
+            result.push(newItem);
+        }
+    }
+    return result;
+}
+export function firstDefined(array, callback) {
+    for (let i = 0; i < array.length; i++) {
+        const result = callback(array[i], i);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    return undefined;
+}
+export function filter(array, predicate) {
+    return array ? array.filter(predicate) : emptyArray;
+}
+export function aggregate(arr, fn) {
+    return arr.reduce((sum, it) => sum + fn(it), 0);
+}
+export function joinArray(arr, joiner, mapper) {
+    if (arr?.length) {
+        return arr.map(mapper).join(joiner);
+    }
+    return "";
+}
+export function maxElementByScore(arr, score) {
+    if (arr.length === 0) {
+        return undefined;
+    }
+    let largest = arr[0];
+    let largestScore = score(arr[0]);
+    for (let i = 1; i < arr.length; ++i) {
+        const itemScore = score(arr[i]);
+        if (itemScore > largestScore) {
+            largest = arr[i];
+            largestScore = itemScore;
+        }
+    }
+    return largest;
+}

package/dist/lib/utils-common/declarationReference.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parser for declaration references, see the [TSDoc grammar](https://github.com/microsoft/tsdoc/blob/main/tsdoc/src/beta/DeclarationReference.grammarkdown)
+ * for reference. TypeDoc **does not** support the full grammar today. This is intentional, since the TSDoc
+ * specified grammar allows the user to construct nonsensical declaration references such as `abc![def!ghi]`
+ *
+ * @module
+ */
+export declare const MeaningKeywords: readonly ["class", "interface", "type", "enum", "namespace", "function", "var", "constructor", "member", "event", "call", "new", "index", "complex", "getter", "setter"];
+export type MeaningKeyword = (typeof MeaningKeywords)[number];
+export interface DeclarationReference {
+    resolutionStart: "global" | "local";
+    moduleSource?: string;
+    symbolReference?: SymbolReference;
+}
+export interface Meaning {
+    keyword?: MeaningKeyword;
+    label?: string;
+    index?: number;
+}
+export declare function meaningToString(meaning: Meaning): string;
+export interface SymbolReference {
+    path?: ComponentPath[];
+    meaning?: Meaning;
+}
+export interface ComponentPath {
+    /**
+     * How to resolve the `path`
+     * - `.` - Navigate via `exports` of symbol
+     * - `#` - Navigate via `members` of symbol
+     * - `~` - Navigate via `locals` of symbol (note: TypeDoc does not support
+     *   locals, see the declaration reference docs)
+     */
+    navigation: "." | "#" | "~";
+    path: string;
+}
+export declare function parseString(source: string, pos: number, end: number): [string, number] | undefined;
+export declare function parseModuleSource(source: string, pos: number, end: number): [string, number] | undefined;
+export declare function parseSymbolReference(source: string, pos: number, end: number): [SymbolReference, number] | undefined;
+export declare function parseComponent(source: string, pos: number, end: number): [string, number] | undefined;
+export declare function parseComponentPath(source: string, pos: number, end: number): readonly [ComponentPath[], number] | undefined;
+export declare function parseMeaning(source: string, pos: number, end: number): [Meaning, number] | undefined;
+export declare function parseDeclarationReference(source: string, pos: number, end: number): [DeclarationReference, number] | undefined;