@depup/typedoc 0.28.17-depup.0

package/dist/lib/utils/fs.js

@@ -0,0 +1,372 @@
+import * as fs from "fs";
+import { promises as fsp } from "fs";
+import { Minimatch } from "minimatch";
+import { dirname, join, relative, resolve } from "path";
+import { escapeRegExp, Validation } from "#utils";
+import { normalizePath } from "./paths.js";
+import { ok } from "assert";
+export function isFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isDir(path) {
+    try {
+        return fs.statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load the given file and return its contents.
+ *
+ * @param file  The path of the file to read.
+ * @returns The files contents.
+ */
+export function readFile(file) {
+    const buffer = fs.readFileSync(file);
+    switch (buffer[0]) {
+        case 0xfe:
+            if (buffer[1] === 0xff) {
+                let i = 0;
+                while (i + 1 < buffer.length) {
+                    const temp = buffer[i];
+                    buffer[i] = buffer[i + 1];
+                    buffer[i + 1] = temp;
+                    i += 2;
+                }
+                return buffer.toString("ucs2", 2);
+            }
+            break;
+        case 0xff:
+            if (buffer[1] === 0xfe) {
+                return buffer.toString("ucs2", 2);
+            }
+            break;
+        case 0xef:
+            if (buffer[1] === 0xbb) {
+                return buffer.toString("utf8", 3);
+            }
+    }
+    return buffer.toString("utf8", 0);
+}
+/**
+ * Write a file to disc.
+ *
+ * If the containing directory does not exist it will be created.
+ *
+ * @param fileName  The name of the file that should be written.
+ * @param data  The contents of the file.
+ */
+export function writeFileSync(fileName, data) {
+    fs.mkdirSync(dirname(normalizePath(fileName)), { recursive: true });
+    fs.writeFileSync(normalizePath(fileName), data);
+}
+/**
+ * Write a file to disc.
+ *
+ * If the containing directory does not exist it will be created.
+ *
+ * @param fileName  The name of the file that should be written.
+ * @param data  The contents of the file.
+ */
+export async function writeFile(fileName, data) {
+    await fsp.mkdir(dirname(normalizePath(fileName)), {
+        recursive: true,
+    });
+    await fsp.writeFile(normalizePath(fileName), data);
+}
+/**
+ * Copy a file or directory recursively.
+ */
+export async function copy(src, dest) {
+    const stat = await fsp.stat(src);
+    if (stat.isDirectory()) {
+        const contained = await fsp.readdir(src);
+        await Promise.all(contained.map((file) => copy(join(src, file), join(dest, file))));
+    }
+    else if (stat.isFile()) {
+        await fsp.mkdir(dirname(dest), { recursive: true });
+        await fsp.copyFile(src, dest);
+    }
+    else {
+        // Do nothing for FIFO, special devices.
+    }
+}
+export function copySync(src, dest) {
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+        const contained = fs.readdirSync(src);
+        contained.forEach((file) => copySync(join(src, file), join(dest, file)));
+    }
+    else if (stat.isFile()) {
+        fs.mkdirSync(dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+    else {
+        // Do nothing for FIFO, special devices.
+    }
+}
+// cache of fs.realpathSync results to avoid extra I/O
+const realpathCache = new Map();
+export function discoverFiles(rootDir, controller) {
+    const result = [];
+    const dirs = [normalizePath(rootDir).split("/")];
+    // cache of real paths to avoid infinite recursion
+    const symlinkTargetsSeen = new Set();
+    const { matchDirectories = false, followSymlinks = false } = controller;
+    let dir = dirs.shift();
+    const handleFile = (path) => {
+        const childPath = [...dir, path].join("/");
+        if (controller.matches(childPath)) {
+            result.push(childPath);
+        }
+    };
+    const handleDirectory = (path) => {
+        const childPath = [...dir, path];
+        if (controller.shouldRecurse(childPath)) {
+            dirs.push(childPath);
+        }
+    };
+    const handleSymlink = (path) => {
+        const childPath = [...dir, path].join("/");
+        let realpath;
+        try {
+            realpath = realpathCache.get(childPath) ?? fs.realpathSync(childPath);
+            realpathCache.set(childPath, realpath);
+        }
+        catch {
+            return;
+        }
+        if (symlinkTargetsSeen.has(realpath)) {
+            return;
+        }
+        symlinkTargetsSeen.add(realpath);
+        try {
+            const stats = fs.statSync(realpath);
+            if (stats.isDirectory()) {
+                handleDirectory(path);
+            }
+            else if (stats.isFile()) {
+                handleFile(path);
+            }
+            else if (stats.isSymbolicLink()) {
+                const dirpath = dir.join("/");
+                if (dirpath === realpath) {
+                    // special case: real path of symlink is the directory we're currently traversing
+                    return;
+                }
+                const targetPath = relative(dirpath, realpath);
+                handleSymlink(targetPath);
+            } // everything else should be ignored
+        }
+        catch (e) {
+            // invalid symbolic link; ignore
+        }
+    };
+    while (dir) {
+        if (matchDirectories && controller.matches(dir.join("/"))) {
+            result.push(dir.join("/"));
+        }
+        for (const child of fs.readdirSync(dir.join("/"), {
+            withFileTypes: true,
+        })) {
+            if (child.isFile()) {
+                handleFile(child.name);
+            }
+            else if (child.isDirectory()) {
+                handleDirectory(child.name);
+            }
+            else if (followSymlinks && child.isSymbolicLink()) {
+                handleSymlink(child.name);
+            }
+        }
+        dir = dirs.shift();
+    }
+    return result;
+}
+/**
+ * Simpler version of `glob.sync` that only covers our use cases, always ignoring node_modules.
+ */
+export function glob(pattern, root, options = {}) {
+    const mini = new Minimatch(pattern);
+    const shouldIncludeNodeModules = pattern.includes("node_modules");
+    const controller = {
+        matches(path) {
+            return mini.match(path);
+        },
+        shouldRecurse(childPath) {
+            // if we _specifically asked_ for something in node_modules, fine, otherwise ignore it
+            // to avoid globs like '**/*.ts' finding all the .d.ts files in node_modules.
+            // however, if the pattern is something like `!**/node_modules/**`, this will also
+            // cause node_modules to be considered, though it will be discarded by minimatch.
+            if (childPath[childPath.length - 1] === "node_modules" &&
+                !shouldIncludeNodeModules) {
+                return false;
+            }
+            return mini.set.some((row) => mini.matchOne(childPath, row, /* partial */ true));
+        },
+        matchDirectories: options.includeDirectories,
+        followSymlinks: options.followSymlinks,
+    };
+    return discoverFiles(root, controller);
+}
+export function hasTsExtension(path) {
+    return /\.[cm]?ts$|\.tsx$/.test(path);
+}
+export function hasDeclarationFileExtension(path) {
+    return /\.d\.[cm]?ts$/.test(path);
+}
+export function discoverInParentDirExactMatch(name, dir, read, usedFile) {
+    if (!isDir(dir))
+        return;
+    const reachedTopDirectory = (dirName) => dirName === resolve(join(dirName, ".."));
+    while (!reachedTopDirectory(dir)) {
+        usedFile?.(join(dir, name));
+        try {
+            const content = read(readFile(join(dir, name)));
+            if (content != null) {
+                return { file: join(dir, name), content };
+            }
+        }
+        catch {
+            // Ignore, file didn't pass validation
+        }
+        dir = resolve(join(dir, ".."));
+    }
+}
+export function discoverPackageJson(dir, usedFile) {
+    return discoverInParentDirExactMatch("package.json", dir, (content) => {
+        const pkg = JSON.parse(content);
+        if (Validation.validate({ name: String, version: Validation.optional(String) }, pkg)) {
+            return pkg;
+        }
+    }, usedFile);
+}
+// dir -> package info
+const packageCache = new Map();
+export function findPackageForPath(sourcePath) {
+    // Attempt to decide package name from path if it contains "node_modules"
+    let startIndex = sourcePath.lastIndexOf("node_modules/");
+    if (startIndex !== -1) {
+        startIndex += "node_modules/".length;
+        let stopIndex = sourcePath.indexOf("/", startIndex);
+        // Scoped package, e.g. `@types/node`
+        if (sourcePath[startIndex] === "@") {
+            stopIndex = sourcePath.indexOf("/", stopIndex + 1);
+        }
+        const packageName = sourcePath.substring(startIndex, stopIndex);
+        return [packageName, sourcePath.substring(0, stopIndex)];
+    }
+    const dir = dirname(sourcePath);
+    const cache = packageCache.get(dir);
+    if (cache) {
+        return cache;
+    }
+    const packageJson = discoverPackageJson(dir);
+    if (packageJson) {
+        packageCache.set(dir, [packageJson.content.name, dirname(packageJson.file)]);
+        return [packageJson.content.name, dirname(packageJson.file)];
+    }
+}
+export function inferPackageEntryPointPaths(packagePath) {
+    const packageDir = normalizePath(dirname(packagePath));
+    const packageJson = JSON.parse(readFile(packagePath));
+    const exports = packageJson.exports;
+    if (typeof exports === "string") {
+        return resolveExport(packageDir, ".", exports, false);
+    }
+    if (!exports || typeof exports !== "object") {
+        if (typeof packageJson.main === "string") {
+            return [[".", resolve(packageDir, packageJson.main)]];
+        }
+        return [];
+    }
+    const results = [];
+    if (Array.isArray(exports)) {
+        results.push(...resolveExport(packageDir, ".", exports, true));
+    }
+    else {
+        for (const [importPath, exp] of Object.entries(exports)) {
+            results.push(...resolveExport(packageDir, importPath, exp, false));
+        }
+    }
+    return results;
+}
+function resolveExport(packageDir, name, exportDeclaration, validatePath) {
+    if (typeof exportDeclaration === "string") {
+        return resolveStarredExport(packageDir, name, exportDeclaration, validatePath);
+    }
+    if (Array.isArray(exportDeclaration)) {
+        for (const item of exportDeclaration) {
+            const result = resolveExport(packageDir, name, item, true);
+            if (result.length) {
+                return result;
+            }
+        }
+        return [];
+    }
+    const EXPORT_CONDITIONS = ["typedoc", "types", "import", "node", "default"];
+    for (const cond in exportDeclaration) {
+        if (EXPORT_CONDITIONS.includes(cond)) {
+            return resolveExport(packageDir, name, exportDeclaration[cond], false);
+        }
+    }
+    // No recognized export condition
+    return [];
+}
+function isWildcardName(name) {
+    let starCount = 0;
+    for (let i = 0; i < name.length; ++i) {
+        if (name[i] === "*") {
+            ++starCount;
+        }
+    }
+    return starCount === 1;
+}
+function resolveStarredExport(packageDir, name, exportDeclaration, validatePath) {
+    // Wildcards only do something if there is exactly one star in the name
+    // If there isn't any star in the destination, all entries map to one file
+    // so don't bother enumerating possible files.
+    if (isWildcardName(name) && exportDeclaration.includes("*")) {
+        // Construct a pattern which we can use to determine if a wildcard matches
+        // This will look something like: /^/app\/package\/(.*).js$/
+        // The destination may have multiple wildcards, in which case they should
+        // contain the same text, so we replace "*" with backreferences for all
+        // but the first occurrence.
+        let first = true;
+        const matcher = new RegExp("^" +
+            escapeRegExp(normalizePath(packageDir) +
+                "/" +
+                exportDeclaration.replace(/^\.\//, "")).replaceAll("\\*", () => {
+                if (first) {
+                    first = false;
+                    return "(.*)";
+                }
+                return "\\1";
+            }) +
+            "$");
+        const matchedFiles = discoverFiles(packageDir, {
+            matches(path) {
+                return matcher.test(path);
+            },
+            shouldRecurse(path) {
+                return path[path.length - 1] !== "node_modules";
+            },
+        });
+        return matchedFiles.flatMap((path) => {
+            const starContent = path.match(matcher);
+            ok(starContent, "impossible, discoverFiles uses matcher");
+            return [[name.replace("*", starContent[1]), path]];
+        });
+    }
+    const exportPath = resolve(packageDir, exportDeclaration);
+    if (validatePath && !fs.existsSync(exportPath)) {
+        return [];
+    }
+    return [[name, exportPath]];
+}

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

@@ -0,0 +1,4 @@
+export declare const TYPEDOC_ROOT: string;
+export declare function hasBeenLoadedMultipleTimes(): boolean;
+export declare function getLoadedPaths(): string[];
+export declare function isDebugging(): boolean;

package/dist/lib/utils/general.js

@@ -0,0 +1,25 @@
+import { dirname } from "path";
+import url from "url";
+import { url as debuggerUrl } from "inspector";
+// transform /abs/path/to/typedoc/dist/lib/utils/general -> /abs/path/to/typedoc
+export const TYPEDOC_ROOT = dirname(dirname(dirname(dirname(url.fileURLToPath(import.meta.url)))));
+/**
+ * This is a hack to make it possible to detect and warn about installation setups
+ * which result in TypeDoc being installed multiple times. If TypeDoc has been loaded
+ * multiple times, then parts of it will not work as expected.
+ */
+const loadSymbol = Symbol.for("typedoc_loads");
+const pathSymbol = Symbol.for("typedoc_paths");
+const g = globalThis;
+g[loadSymbol] = (g[loadSymbol] || 0) + 1;
+g[pathSymbol] ||= [];
+g[pathSymbol].push(TYPEDOC_ROOT);
+export function hasBeenLoadedMultipleTimes() {
+    return g[loadSymbol] !== 1;
+}
+export function getLoadedPaths() {
+    return g[pathSymbol] || [];
+}
+export function isDebugging() {
+    return !!debuggerUrl();
+}

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

@@ -0,0 +1,9 @@
+import * as shiki from "@gerrit0/mini-shiki";
+export declare function loadTestHighlighter(): void;
+export declare function loadHighlighter(lightTheme: shiki.BundledTheme, darkTheme: shiki.BundledTheme, langs: shiki.BundledLanguage[], ignoredLangs: string[] | undefined): Promise<void>;
+export declare function isSupportedLanguage(lang: string): boolean;
+export declare function getSupportedLanguages(): string[];
+export declare function getSupportedThemes(): string[];
+export declare function isLoadedLanguage(lang: string): boolean;
+export declare function highlight(code: string, lang: string): string;
+export declare function getStyles(): string;

package/dist/lib/utils/highlighter.js

@@ -0,0 +1,150 @@
+import * as shiki from "@gerrit0/mini-shiki";
+import { JSX, unique } from "#utils";
+import assert from "assert";
+const tsAliases = [["mts", "typescript"], ["cts", "typescript"]];
+const aliases = new Map(tsAliases);
+for (const lang of shiki.bundledLanguagesInfo) {
+    for (const alias of lang.aliases || []) {
+        aliases.set(alias, lang.id);
+    }
+}
+const plaintextLanguages = ["txt", "text"];
+const supportedLanguages = unique([
+    ...plaintextLanguages,
+    ...aliases.keys(),
+    ...shiki.bundledLanguagesInfo.map((lang) => lang.id),
+]).sort();
+const supportedThemes = Object.keys(shiki.bundledThemes);
+class ShikiHighlighter {
+    highlighter;
+    light;
+    dark;
+    schemes = new Map();
+    constructor(highlighter, light, dark) {
+        this.highlighter = highlighter;
+        this.light = light;
+        this.dark = dark;
+    }
+    supports(lang) {
+        return this.highlighter.getLoadedLanguages().includes(lang);
+    }
+    highlight(code, lang) {
+        const tokens = shiki.codeToTokensWithThemes(this.highlighter, code, {
+            themes: { light: this.light, dark: this.dark },
+            lang: lang,
+        });
+        const docEls = [];
+        for (const line of tokens) {
+            for (const token of line) {
+                docEls.push(JSX.createElement("span", { class: this.getClass(token.variants) }, token.content));
+            }
+            docEls.push(JSX.createElement("br", null));
+        }
+        docEls.pop(); // Remove last <br>
+        docEls.pop(); // Remove last <br>
+        return JSX.renderElement(JSX.createElement(JSX.Fragment, null, docEls));
+    }
+    getStyles() {
+        const style = [":root {"];
+        const lightRules = [];
+        const darkRules = [];
+        let i = 0;
+        for (const key of this.schemes.keys()) {
+            const [light, dark] = key.split(" | ");
+            style.push(`    --light-hl-${i}: ${light};`);
+            style.push(`    --dark-hl-${i}: ${dark};`);
+            lightRules.push(`    --hl-${i}: var(--light-hl-${i});`);
+            darkRules.push(`    --hl-${i}: var(--dark-hl-${i});`);
+            i++;
+        }
+        style.push(`    --light-code-background: ${this.highlighter.getTheme(this.light).bg};`);
+        style.push(`    --dark-code-background: ${this.highlighter.getTheme(this.dark).bg};`);
+        lightRules.push(`    --code-background: var(--light-code-background);`);
+        darkRules.push(`    --code-background: var(--dark-code-background);`);
+        style.push("}", "");
+        style.push("@media (prefers-color-scheme: light) { :root {");
+        style.push(...lightRules);
+        style.push("} }", "");
+        style.push("@media (prefers-color-scheme: dark) { :root {");
+        style.push(...darkRules);
+        style.push("} }", "");
+        style.push(":root[data-theme='light'] {");
+        style.push(...lightRules);
+        style.push("}", "");
+        style.push(":root[data-theme='dark'] {");
+        style.push(...darkRules);
+        style.push("}", "");
+        for (i = 0; i < this.schemes.size; i++) {
+            style.push(`.hl-${i} { color: var(--hl-${i}); }`);
+        }
+        style.push("pre, code { background: var(--code-background); }", "");
+        return style.join("\n");
+    }
+    getClass(variants) {
+        const key = `${variants["light"].color} | ${variants["dark"].color}`;
+        let scheme = this.schemes.get(key);
+        if (scheme == null) {
+            scheme = `hl-${this.schemes.size}`;
+            this.schemes.set(key, scheme);
+        }
+        return scheme;
+    }
+}
+class TestHighlighter {
+    supports() {
+        return true;
+    }
+    highlight(code) {
+        return code;
+    }
+    getStyles() {
+        return "";
+    }
+}
+let shikiEngine;
+let highlighter;
+let ignoredLanguages;
+export function loadTestHighlighter() {
+    highlighter = new TestHighlighter();
+}
+export async function loadHighlighter(lightTheme, darkTheme, langs, ignoredLangs) {
+    if (highlighter)
+        return;
+    ignoredLanguages = ignoredLangs;
+    if (!shikiEngine) {
+        await shiki.loadBuiltinWasm();
+        shikiEngine = await shiki.createOnigurumaEngine();
+    }
+    const hl = await shiki.createShikiInternal({
+        engine: shikiEngine,
+        themes: [shiki.bundledThemes[lightTheme], shiki.bundledThemes[darkTheme]],
+        langs: langs.map((lang) => shiki.bundledLanguages[lang]),
+    });
+    highlighter = new ShikiHighlighter(hl, lightTheme, darkTheme);
+}
+function isPlainLanguage(lang) {
+    return ignoredLanguages?.includes(lang) || plaintextLanguages.includes(lang);
+}
+export function isSupportedLanguage(lang) {
+    return isPlainLanguage(lang) || supportedLanguages.includes(lang);
+}
+export function getSupportedLanguages() {
+    return supportedLanguages;
+}
+export function getSupportedThemes() {
+    return supportedThemes;
+}
+export function isLoadedLanguage(lang) {
+    return isPlainLanguage(lang) || highlighter?.supports(lang) || false;
+}
+export function highlight(code, lang) {
+    assert(highlighter, "Tried to highlight with an uninitialized highlighter");
+    if (plaintextLanguages.includes(lang) || ignoredLanguages?.includes(lang)) {
+        return JSX.renderElement(JSX.createElement(JSX.Fragment, null, code));
+    }
+    return highlighter.highlight(code, aliases.get(lang) ?? lang);
+}
+export function getStyles() {
+    assert(highlighter, "Tried to highlight with an uninitialized highlighter");
+    return highlighter.getStyles();
+}