typedoc 0.28.19 → 0.28.20

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

@@ -1,130 +0,0 @@
-import { assert } from "./general.js";
-export var NormalizedPathUtils;
-(function (NormalizedPathUtils) {
-    function dirname(path) {
-        let end = path.length - 2;
-        for (; end > 0; --end) {
-            if (path[end] === "/")
-                break;
-        }
-        switch (end) {
-            case -2:
-            case -1:
-                return (path[0] === "/" ? "/" : ".");
-            case 0:
-                return path.substring(0, path.indexOf("/") + 1);
-            default:
-                return path.slice(0, end);
-        }
-    }
-    NormalizedPathUtils.dirname = dirname;
-    function basename(path) {
-        // We start at length - 2 as /var/typedoc/ should give `typedoc`
-        let end = path.length - 2;
-        for (; end >= 0; --end) {
-            if (path[end] === "/")
-                break;
-        }
-        switch (end) {
-            case -2:
-            case -1:
-                return path;
-            default:
-                if (path.endsWith("/")) {
-                    return path.slice(end + 1, -1);
-                }
-                return path.slice(end + 1);
-        }
-    }
-    NormalizedPathUtils.basename = basename;
-    function relative(from, to) {
-        if (from == to) {
-            return "";
-        }
-        assert(isAbsolute(from) && isAbsolute(to), "resolving relative paths without absolute inputs requires a filesystem");
-        if (!from.endsWith("/")) {
-            from += "/";
-        }
-        const end = to.length;
-        if (!to.endsWith("/")) {
-            to += "/";
-        }
-        const minLen = Math.min(from.length, to.length);
-        let lastCommonSlash = 0;
-        let i = 0;
-        for (; i < minLen; ++i) {
-            if (from[i] === to[i]) {
-                if (from[i] === "/") {
-                    lastCommonSlash = i;
-                }
-            }
-            else {
-                break;
-            }
-        }
-        if (lastCommonSlash === from.length - 1) {
-            return to.substring(from.length, end);
-        }
-        let prefix = "";
-        for (let i = lastCommonSlash + 1; i < from.length; ++i) {
-            if (from[i] === "/" || i + 1 === from.length) {
-                prefix += prefix ? "/.." : "..";
-            }
-        }
-        return prefix + to.substring(lastCommonSlash, end);
-    }
-    NormalizedPathUtils.relative = relative;
-    function normalize(path) {
-        const parts = path.split("/");
-        let canRemoveDotDot = false;
-        for (let i = 0; i < parts.length; /* inside loop */) {
-            if (parts[i] == "." && i + 1 != parts.length) {
-                parts.splice(i, 1);
-            }
-            else if (parts[i] == "..") {
-                if (canRemoveDotDot) {
-                    if (i - 1 === 0 && /\w:/i.test(parts[0])) {
-                        parts.splice(i, 1);
-                    }
-                    else {
-                        parts.splice(i - 1, 2);
-                        i = i - 1;
-                    }
-                }
-                else {
-                    ++i;
-                }
-            }
-            else {
-                canRemoveDotDot = true;
-                ++i;
-            }
-        }
-        return parts.join("/");
-    }
-    NormalizedPathUtils.normalize = normalize;
-    function resolve(from, to) {
-        assert(isAbsolute(from), "resolving without an absolute path requires a filesystem");
-        if (isAbsolute(to)) {
-            return to;
-        }
-        return normalize(`${from}/${to}`);
-    }
-    NormalizedPathUtils.resolve = resolve;
-    function isAbsolute(from) {
-        return /^\/|^\w:\//.test(from);
-    }
-    NormalizedPathUtils.isAbsolute = isAbsolute;
-    function splitFilename(name) {
-        const lastDot = name.lastIndexOf(".");
-        if (lastDot < 1) {
-            return { name, ext: "" };
-        }
-        return { name: name.substring(0, lastDot), ext: name.substring(lastDot) };
-    }
-    NormalizedPathUtils.splitFilename = splitFilename;
-    function isDeclarationFilePath(path) {
-        return /\.d\.(ts|mts|cts)$/.test(path);
-    }
-    NormalizedPathUtils.isDeclarationFilePath = isDeclarationFilePath;
-})(NormalizedPathUtils || (NormalizedPathUtils = {}));

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

@@ -1,23 +0,0 @@
-export function setIntersection(a, b) {
-    const result = new Set();
-    for (const elem of a) {
-        if (b.has(elem)) {
-            result.add(elem);
-        }
-    }
-    return result;
-}
-export function setDifference(a, b) {
-    const result = new Set(a);
-    for (const elem of b) {
-        result.delete(elem);
-    }
-    return result;
-}
-export function setUnion(a, b) {
-    const result = new Set(a);
-    for (const elem of b) {
-        result.add(elem);
-    }
-    return result;
-}

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

@@ -1,84 +0,0 @@
-import { DefaultMap } from "./map.js";
-/** Count the number of times `search` appears in `text` */
-export function countMatches(text, search) {
-    let count = 0;
-    let last = 0;
-    for (;;) {
-        const index = text.indexOf(search, last);
-        if (index === -1) {
-            break;
-        }
-        else {
-            last = index + 1;
-            ++count;
-        }
-    }
-    return count;
-}
-export function dedent(text) {
-    const lines = text.split(/\r?\n/);
-    while (lines.length && lines[0].search(/\S/) === -1) {
-        lines.shift();
-    }
-    while (lines.length && lines[lines.length - 1].search(/\S/) === -1) {
-        lines.pop();
-    }
-    const minIndent = lines.reduce((indent, line) => line.length ? Math.min(indent, line.search(/\S/)) : indent, Infinity);
-    return lines.map((line) => line.substring(minIndent)).join("\n");
-}
-// Based on https://en.wikipedia.org/wiki/Levenshtein_distance#Iterative_with_two_matrix_rows
-// Slightly modified for improved match results for options
-export function editDistance(s, t) {
-    if (s.length < t.length)
-        return editDistance(t, s);
-    let v0 = Array.from({ length: t.length + 1 }, (_, i) => i);
-    let v1 = Array.from({ length: t.length + 1 }, () => 0);
-    for (let i = 0; i < s.length; i++) {
-        v1[0] = i + 1;
-        for (let j = 0; j < s.length; j++) {
-            const deletionCost = v0[j + 1] + 1;
-            const insertionCost = v1[j] + 1;
-            let substitutionCost;
-            if (s[i] === t[j]) {
-                substitutionCost = v0[j];
-            }
-            else if (s[i]?.toUpperCase() === t[j]?.toUpperCase()) {
-                substitutionCost = v0[j] + 1;
-            }
-            else {
-                substitutionCost = v0[j] + 3;
-            }
-            v1[j + 1] = Math.min(deletionCost, insertionCost, substitutionCost);
-        }
-        [v0, v1] = [v1, v0];
-    }
-    return v0[t.length];
-}
-export function getSimilarValues(values, compareTo) {
-    const results = new DefaultMap(() => []);
-    let lowest = Infinity;
-    for (const name of values) {
-        const distance = editDistance(compareTo, name);
-        lowest = Math.min(lowest, distance);
-        results.get(distance).push(name);
-    }
-    // Experimenting a bit, it seems an edit distance of 3 is roughly the
-    // right metric for relevant "similar" results without showing obviously wrong suggestions
-    return results
-        .get(lowest)
-        .concat(results.get(lowest + 1), results.get(lowest + 2));
-}
-// From MDN
-export function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
-}
-const htmlEscapes = {
-    "&": "&amp;",
-    "<": "&lt;",
-    ">": "&gt;",
-    '"': "&quot;",
-    "'": "&#39;",
-};
-export function escapeHtml(html) {
-    return html.replace(/[&<>'"]/g, (c) => htmlEscapes[c]);
-}

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

@@ -1,50 +0,0 @@
-const opt = Symbol();
-/**
- * Symbol that may be placed on a schema object to define how additional properties are handled.
- * By default, additional properties are not checked.
- */
-export const additionalProperties = Symbol();
-export function validate(schema, obj) {
-    let type = schema;
-    if (opt in schema) {
-        if (obj == null) {
-            return true;
-        }
-        type = schema[opt];
-    }
-    if (type === String) {
-        return typeof obj === "string";
-    }
-    if (type === Number) {
-        return typeof obj === "number";
-    }
-    if (type === Boolean) {
-        return typeof obj === "boolean";
-    }
-    if (typeof type === "function") {
-        return type(obj);
-    }
-    if (Array.isArray(type)) {
-        if (type[0] === Array) {
-            return (Array.isArray(obj) &&
-                obj.every((item) => validate(type[1], item)));
-        }
-        return type.includes(obj);
-    }
-    if (additionalProperties in schema &&
-        !schema[additionalProperties]) {
-        if (Object.keys(obj).some((key) => !(key in schema))) {
-            return false;
-        }
-    }
-    return (!!obj &&
-        typeof obj === "object" &&
-        !Array.isArray(obj) &&
-        Object.entries(type).every(([key, prop]) => validate(prop, obj[key])));
-}
-export function optional(x) {
-    return { [opt]: x };
-}
-export function isTagString(x) {
-    return typeof x === "string" && /^@[a-z][a-z0-9-]*$/i.test(x);
-}

package/dist/lib/validation/documentation.js

@@ -1,91 +0,0 @@
-import { DeclarationReflection, ReflectionKind, ReflectionType, } from "../models/index.js";
-import { i18n, removeFlag } from "#utils";
-export function validateDocumentation(project, logger, requiredToBeDocumented, intentionallyNotDocumented, packagesRequiringDocumentation) {
-    let kinds = requiredToBeDocumented.reduce((prev, cur) => prev | ReflectionKind[cur], 0);
-    // Functions, Constructors, and Accessors never have comments directly on them.
-    // If they are required to be documented, what's really required is that their
-    // contained signatures have a comment.
-    if (kinds & ReflectionKind.FunctionOrMethod) {
-        kinds |= ReflectionKind.CallSignature;
-        kinds = removeFlag(kinds, ReflectionKind.FunctionOrMethod);
-    }
-    if (kinds & ReflectionKind.Constructor) {
-        kinds |= ReflectionKind.ConstructorSignature;
-        kinds = removeFlag(kinds, ReflectionKind.Constructor);
-    }
-    if (kinds & ReflectionKind.Accessor) {
-        kinds |= ReflectionKind.GetSignature | ReflectionKind.SetSignature;
-        kinds = removeFlag(kinds, ReflectionKind.Accessor);
-    }
-    const toProcess = project.getReflectionsByKind(kinds);
-    const seen = new Set();
-    const intentionalUsage = new Set();
-    outer: while (toProcess.length) {
-        const ref = toProcess.shift();
-        if (seen.has(ref))
-            continue;
-        seen.add(ref);
-        // If inside a parameter, we shouldn't care. Callback parameter's values don't get deeply documented.
-        let r = ref.parent;
-        while (r) {
-            if (r.kindOf(ReflectionKind.Parameter)) {
-                continue outer;
-            }
-            r = r.parent;
-        }
-        // Type aliases own their comments, even if they're function-likes.
-        // So if we're a type literal owned by a type alias, don't do anything.
-        if (ref.kindOf(ReflectionKind.TypeLiteral) &&
-            ref.parent?.kindOf(ReflectionKind.TypeAlias)) {
-            toProcess.push(ref.parent);
-            continue;
-        }
-        // Call signatures are considered documented if they have a comment directly, or their
-        // container has a comment and they are directly within a type literal belonging to that container.
-        if (ref.kindOf(ReflectionKind.CallSignature) &&
-            ref.parent?.kindOf(ReflectionKind.TypeLiteral)) {
-            toProcess.push(ref.parent.parent);
-            continue;
-        }
-        // Construct signatures are considered documented if they are directly within a documented type alias.
-        if (ref.kindOf(ReflectionKind.ConstructorSignature) &&
-            ref.parent?.parent?.kindOf(ReflectionKind.TypeAlias)) {
-            toProcess.push(ref.parent.parent);
-            continue;
-        }
-        if (ref instanceof DeclarationReflection) {
-            const signatures = ref.type instanceof ReflectionType
-                ? ref.type.declaration.getNonIndexSignatures()
-                : ref.getNonIndexSignatures();
-            if (signatures.length) {
-                // We've been asked to validate this reflection, so we should validate that
-                // signatures all have comments
-                toProcess.push(...signatures);
-                if (ref.kindOf(ReflectionKind.SignatureContainer)) {
-                    // Comments belong to each signature, and will not be included on this object.
-                    continue;
-                }
-            }
-        }
-        const symbolId = project.getSymbolIdFromReflection(ref);
-        // #2644, signatures may be documented by their parent reflection.
-        const hasComment = ref.hasComment() ||
-            (ref.kindOf(ReflectionKind.SomeSignature) &&
-                ref.parent?.hasComment());
-        if (!hasComment && symbolId) {
-            if (!packagesRequiringDocumentation.includes(symbolId.packageName)) {
-                continue;
-            }
-            const intentionalIndex = intentionallyNotDocumented.indexOf(ref.getFriendlyFullName());
-            if (intentionalIndex !== -1) {
-                intentionalUsage.add(intentionalIndex);
-                continue;
-            }
-            logger.validationWarning(i18n.reflection_0_kind_1_defined_in_2_does_not_have_any_documentation(ref.getFriendlyFullName(), ReflectionKind[ref.kind], `${symbolId.packageName}/${symbolId.packagePath}`));
-        }
-    }
-    const unusedIntentional = intentionallyNotDocumented.filter((_, i) => !intentionalUsage.has(i));
-    if (unusedIntentional.length) {
-        logger.validationWarning(i18n.invalid_intentionally_not_documented_names_0(unusedIntentional.join("\n\t")));
-    }
-}

package/dist/lib/validation/exports.js

@@ -1,65 +0,0 @@
-import { ok } from "assert";
-import { discoverAllReferenceTypes } from "../utils/reflections.js";
-import { i18n } from "#utils";
-function makeIntentionallyExportedHelper(project, intentional, logger) {
-    const used = new Set();
-    const processed = intentional.map((v) => {
-        const index = v.lastIndexOf(":");
-        if (index === -1) {
-            return ["", v];
-        }
-        return [v.substring(0, index), v.substring(index + 1)];
-    });
-    return {
-        has(type, typeName) {
-            ok(!type.reflection);
-            // If it isn't declared anywhere, we can't produce a good error message about where
-            // the non-exported symbol is, so even if it isn't ignored, pretend it is. In practice,
-            // this will happen incredibly rarely, since symbols without declarations are very rare.
-            // I know of only two instances:
-            // 1. `undefined` in `globalThis`
-            // 2. Properties on non-homomorphic mapped types, e.g. the symbol for "foo" on `Record<"foo", 1>`
-            // There might be others, so still check this here rather than asserting, but print a debug log
-            // so that we can possibly improve this in the future.
-            if (!type.package) {
-                logger.verbose(`The type ${type.qualifiedName} has no declarations, implicitly allowing missing export.`);
-                return true;
-            }
-            // Don't produce warnings for third-party symbols.
-            if (type.package !== project.packageName) {
-                return true;
-            }
-            for (const [index, [file, name]] of processed.entries()) {
-                if (typeName === name &&
-                    `${type.symbolId.packageName}/${type.symbolId.packagePath}`.endsWith(file)) {
-                    used.add(index);
-                    return true;
-                }
-            }
-            return false;
-        },
-        getUnused() {
-            return intentional.filter((_, i) => !used.has(i));
-        },
-    };
-}
-export function validateExports(project, logger, intentionallyNotExported) {
-    const intentional = makeIntentionallyExportedHelper(project, intentionallyNotExported, logger);
-    const warned = new Set();
-    for (const { type, owner } of discoverAllReferenceTypes(project, true)) {
-        const uniqueId = type.symbolId?.getStableKey();
-        if (!type.reflection &&
-            !type.externalUrl &&
-            !type.isIntentionallyBroken() &&
-            !intentional.has(type, type.qualifiedName) &&
-            !warned.has(uniqueId) &&
-            !project.symbolIdHasBeenRemoved(type.symbolId)) {
-            warned.add(uniqueId);
-            logger.validationWarning(i18n.type_0_defined_in_1_is_referenced_by_2_but_not_included_in_docs(type.qualifiedName, `${type.symbolId.packageName}/${type.symbolId.packagePath}`, owner.getFriendlyFullName()));
-        }
-    }
-    const unusedIntentional = intentional.getUnused();
-    if (unusedIntentional.length) {
-        logger.validationWarning(i18n.invalid_intentionally_not_exported_symbols_0(unusedIntentional.join("\n\t")));
-    }
-}

package/dist/lib/validation/links.js

@@ -1,78 +0,0 @@
-import { i18n } from "#utils";
-import { ReflectionKind, ReflectionSymbolId, } from "../models/index.js";
-const linkTags = ["@link", "@linkcode", "@linkplain"];
-function getBrokenPartLinks(parts) {
-    const links = [];
-    for (const part of parts) {
-        if (part.kind === "inline-tag" &&
-            linkTags.includes(part.tag) &&
-            (!part.target || part.target instanceof ReflectionSymbolId)) {
-            links.push(part);
-        }
-    }
-    return links;
-}
-function getBrokenLinks(comment) {
-    if (!comment)
-        return [];
-    const links = [...getBrokenPartLinks(comment.summary)];
-    for (const tag of comment.blockTags) {
-        links.push(...getBrokenPartLinks(tag.content));
-    }
-    return links;
-}
-export function validateLinks(project, logger) {
-    for (const id in project.reflections) {
-        checkReflection(project.reflections[id], logger);
-    }
-}
-function checkReflection(reflection, logger) {
-    if (reflection.isProject() || reflection.isDeclaration()) {
-        for (const broken of getBrokenPartLinks(reflection.readme || [])) {
-            const linkText = broken.text.trim();
-            // #2360, "@" is a future reserved character in TSDoc component paths
-            // If a link starts with it, and doesn't include a module source indicator "!"
-            // then the user probably is trying to link to a package containing "@" with an absolute link.
-            if (linkText.startsWith("@") && !linkText.includes("!")) {
-                logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
-            }
-            else {
-                logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_readme_for_1(linkText, reflection.getFriendlyFullName()));
-            }
-        }
-    }
-    if (reflection.isDocument()) {
-        for (const broken of getBrokenPartLinks(reflection.content)) {
-            const linkText = broken.text.trim();
-            if (linkText.startsWith("@") && !linkText.includes("!")) {
-                logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_document_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
-            }
-            else {
-                logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_document_1(linkText, reflection.getFriendlyFullName()));
-            }
-        }
-    }
-    for (const broken of getBrokenLinks(reflection.comment)) {
-        reportBrokenCommentLink(broken, reflection, logger);
-    }
-    if (reflection.isDeclaration() &&
-        reflection.kindOf(ReflectionKind.TypeAlias) &&
-        reflection.type?.type === "union" &&
-        reflection.type.elementSummaries) {
-        for (const broken of reflection.type.elementSummaries.flatMap(getBrokenPartLinks)) {
-            reportBrokenCommentLink(broken, reflection, logger);
-        }
-    }
-}
-function reportBrokenCommentLink(broken, reflection, logger) {
-    const linkText = broken.text.trim();
-    if (broken.target instanceof ReflectionSymbolId) {
-        logger.validationWarning(i18n.comment_for_0_links_to_1_not_included_in_docs_use_external_link_2(reflection.getFriendlyFullName(), linkText, `{ "${broken.target.packageName}": { "${broken.target.qualifiedName}": "#" }}`));
-    }
-    else if (linkText.startsWith("@") && !linkText.includes("!")) {
-        logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
-    }
-    else {
-        logger.validationWarning(i18n.failed_to_resolve_link_to_0_in_comment_for_1(linkText, reflection.getFriendlyFullName()));
-    }
-}

package/dist/lib/validation/unusedMergeModuleWith.js

@@ -1,12 +0,0 @@
-import { i18n } from "#utils";
-import { ReflectionKind } from "../models/index.js";
-export function validateMergeModuleWith(project, logger) {
-    for (const refl of project.getReflectionsByKind(ReflectionKind.SomeModule)) {
-        if (refl.comment?.getTag("@mergeModuleWith")) {
-            logger.warn(i18n.reflection_0_has_unused_mergeModuleWith_tag(refl.getFriendlyFullName()));
-        }
-    }
-    if (project.comment?.getTag("@mergeModuleWith")) {
-        logger.warn(i18n.reflection_0_has_unused_mergeModuleWith_tag("<project>"));
-    }
-}