@depup/typedoc 0.28.17-depup.0

package/dist/lib/converter/comments/rawLexer.js

@@ -0,0 +1,218 @@
+import { TokenSyntaxKind } from "./lexer.js";
+/**
+ * Note: This lexer intentionally *only* recognizes inline tags and code blocks.
+ * This is because it is intended for use on markdown documents, and we shouldn't
+ * take some stray `@user` mention within a "Thanks" section of someone's changelog
+ * as starting a block!
+ */
+export function* lexCommentString(file) {
+    // Wrapper around our real lex function to collapse adjacent text tokens.
+    let textToken;
+    for (const token of lexCommentString2(file)) {
+        if (token.kind === TokenSyntaxKind.Text ||
+            token.kind === TokenSyntaxKind.NewLine) {
+            if (textToken) {
+                textToken.text += token.text;
+            }
+            else {
+                token.kind = TokenSyntaxKind.Text;
+                textToken = token;
+            }
+        }
+        else {
+            if (textToken) {
+                yield textToken;
+                textToken = void 0;
+            }
+            yield token;
+        }
+    }
+    if (textToken) {
+        yield textToken;
+    }
+    return;
+}
+function* lexCommentString2(file) {
+    let pos = 0;
+    let end = file.length;
+    // Skip leading whitespace
+    while (pos < end && /\s/.test(file[pos])) {
+        pos++;
+    }
+    // Trailing whitespace
+    while (pos < end && /\s/.test(file[end - 1])) {
+        end--;
+    }
+    let expectingTag = false;
+    for (;;) {
+        if (pos >= end) {
+            return;
+        }
+        switch (file[pos]) {
+            case "\n":
+                yield makeToken(TokenSyntaxKind.NewLine, 1);
+                expectingTag = false;
+                break;
+            case "{":
+                yield makeToken(TokenSyntaxKind.OpenBrace, 1);
+                expectingTag = true;
+                break;
+            case "}":
+                yield makeToken(TokenSyntaxKind.CloseBrace, 1);
+                expectingTag = false;
+                break;
+            case "`": {
+                // Markdown's code rules are a royal pain. This could be one of several things.
+                // 1. Inline code: <1-n ticks><text without multiple consecutive newlines or ticks at start of line><same number of ticks>
+                // 2. Code block: <newline><3+ ticks><language, no ticks>\n<text>\n<3 ticks>\n
+                // 3. Unmatched tick(s), not code, but part of some text.
+                // We don't quite handle #2 correctly yet. PR welcome!
+                let tickCount = 1;
+                let lookahead = pos - 1;
+                let atNewline = true;
+                while (lookahead > 0 && file[lookahead] !== "\n") {
+                    if (/\S/.test(file[lookahead])) {
+                        atNewline = false;
+                        break;
+                    }
+                    --lookahead;
+                }
+                lookahead = pos;
+                while (lookahead + 1 < end && file[lookahead + 1] === "`") {
+                    tickCount++;
+                    lookahead++;
+                }
+                const isCodeBlock = atNewline && tickCount >= 3;
+                let lookaheadStart = pos;
+                const codeText = [];
+                lookahead++;
+                while (lookahead < end) {
+                    if (lookaheadExactlyNTicks(lookahead, tickCount)) {
+                        lookahead += tickCount;
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        const codeTextStr = codeText.join("");
+                        if (isCodeBlock || !/\n\s*\n/.test(codeTextStr)) {
+                            yield {
+                                kind: TokenSyntaxKind.Code,
+                                text: codeTextStr,
+                                pos,
+                            };
+                            expectingTag = false;
+                            pos = lookahead;
+                        }
+                        else {
+                            yield makeToken(TokenSyntaxKind.Text, tickCount);
+                            expectingTag = false;
+                        }
+                        break;
+                    }
+                    else if (file[lookahead] === "`") {
+                        while (lookahead < end && file[lookahead] === "`") {
+                            lookahead++;
+                        }
+                    }
+                    else if (file[lookahead] === "\\" &&
+                        lookahead + 1 < end &&
+                        file[lookahead + 1] !== "\n") {
+                        lookahead += 2;
+                    }
+                    else if (file[lookahead] === "\n") {
+                        lookahead++;
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        lookaheadStart = lookahead;
+                    }
+                    else {
+                        lookahead++;
+                    }
+                }
+                if (lookahead >= end && pos !== lookahead) {
+                    if (isCodeBlock &&
+                        file.substring(pos, end).includes("\n")) {
+                        codeText.push(file.substring(lookaheadStart, end));
+                        yield {
+                            kind: TokenSyntaxKind.Code,
+                            text: codeText.join(""),
+                            pos,
+                        };
+                        expectingTag = false;
+                        pos = lookahead;
+                    }
+                    else {
+                        yield makeToken(TokenSyntaxKind.Text, tickCount);
+                        expectingTag = false;
+                    }
+                }
+                break;
+            }
+            case "@": {
+                let lookahead = pos + 1;
+                while (lookahead < end && /[a-z]/i.test(file[lookahead])) {
+                    lookahead++;
+                }
+                if (lookahead !== pos + 1) {
+                    while (lookahead < end &&
+                        /[a-z0-9-]/i.test(file[lookahead])) {
+                        lookahead++;
+                    }
+                }
+                if (expectingTag &&
+                    lookahead !== pos + 1 &&
+                    (lookahead === end || /[\s}]/.test(file[lookahead]))) {
+                    yield makeToken(TokenSyntaxKind.Tag, lookahead - pos);
+                    break;
+                }
+            }
+            // fall through if we didn't find something that looks like a tag
+            default: {
+                const textParts = [];
+                let lookaheadStart = pos;
+                let lookahead = pos;
+                while (lookahead < end) {
+                    if ("{}\n`".includes(file[lookahead]))
+                        break;
+                    if (lookahead !== pos &&
+                        file[lookahead] === "@" &&
+                        /\s/.test(file[lookahead - 1])) {
+                        // Probably the start of a modifier tag
+                        break;
+                    }
+                    if (file[lookahead] === "\\" &&
+                        lookahead + 1 < end &&
+                        "{}@`".includes(file[lookahead + 1])) {
+                        textParts.push(file.substring(lookaheadStart, lookahead), file[lookahead + 1]);
+                        lookahead++;
+                        lookaheadStart = lookahead + 1;
+                    }
+                    lookahead++;
+                }
+                textParts.push(file.substring(lookaheadStart, lookahead));
+                if (textParts.some((part) => /\S/.test(part))) {
+                    expectingTag = false;
+                }
+                // This piece of text had line continuations or escaped text
+                yield {
+                    kind: TokenSyntaxKind.Text,
+                    text: textParts.join(""),
+                    pos,
+                };
+                pos = lookahead;
+                break;
+            }
+        }
+    }
+    function makeToken(kind, size) {
+        const start = pos;
+        pos += size;
+        return {
+            kind,
+            text: file.substring(start, pos),
+            pos: start,
+        };
+    }
+    function lookaheadExactlyNTicks(pos, n) {
+        if (pos + n > end) {
+            return false;
+        }
+        return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";
+    }
+}

package/dist/lib/converter/comments/tagName.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Determines the name of the parameter/template/property from the tag content
+ * when processing `@param x`
+ */
+export declare function extractTagName(text: string): {
+    name: string;
+    newText: string;
+};

package/dist/lib/converter/comments/tagName.js

@@ -0,0 +1,58 @@
+/**
+ * Determines the name of the parameter/template/property from the tag content
+ * when processing `@param x`
+ */
+export function extractTagName(text) {
+    let pos = skipWs(text, 0);
+    // Extract the "name" part of the comment, this might also include a default
+    // value if bracketed.
+    let nameStart = pos;
+    let bracketDepth = 0;
+    let stringChar = "";
+    while (pos < text.length && (bracketDepth > 0 || /\S/.test(text[pos]))) {
+        if (stringChar) {
+            if (text[pos] == stringChar) {
+                stringChar = "";
+                ++pos;
+            }
+            else if (text[pos] == "\\") {
+                pos += 2;
+            }
+            else {
+                ++pos;
+            }
+        }
+        else {
+            if ("\"'`".includes(text[pos])) {
+                stringChar = text[pos];
+            }
+            else if (text[pos] == "[") {
+                ++bracketDepth;
+            }
+            else if (text[pos] == "]") {
+                --bracketDepth;
+            }
+            ++pos;
+        }
+    }
+    let nameEnd = pos;
+    if (text[nameStart] === "[") {
+        nameStart = skipWs(text, nameStart + 1);
+        nameEnd = skipWith(text, nameStart, /[^\s=\]]/);
+    }
+    // Skip any whitespace & an optional dash before the description
+    pos = skipWith(text, pos, /[\s-]/);
+    return {
+        name: text.substring(nameStart, nameEnd),
+        newText: text.substring(pos),
+    };
+}
+function skipWs(text, pos) {
+    return skipWith(text, pos, /\s/);
+}
+function skipWith(text, pos, reg) {
+    while (pos < text.length && reg.test(text[pos])) {
+        ++pos;
+    }
+    return pos;
+}

package/dist/lib/converter/comments/textParser.d.ts

@@ -0,0 +1,33 @@
+import type { CommentDisplayPart } from "../../models/index.js";
+import type { FileRegistry } from "../../models/FileRegistry.js";
+import { type ValidationOptions } from "#node-utils";
+import { type Token } from "./lexer.js";
+import type { NormalizedPath, TranslatedString } from "#utils";
+interface TextParserData {
+    sourcePath: NormalizedPath;
+    token: Token;
+    pos: number;
+    warning: (msg: TranslatedString, token: Token) => void;
+    validationWarning: (msg: TranslatedString, token: Token) => void;
+    files: FileRegistry;
+    atNewLine: boolean;
+    validationOptions: ValidationOptions;
+}
+/**
+ * This is incredibly unfortunate. The comment lexer owns the responsibility
+ * for splitting up text into text/code, this is totally fine for HTML links
+ * but for markdown links, ``[`code`](./link)`` is valid, so we need to keep
+ * track of state across calls to {@link textContent}.
+ */
+export declare class TextParserReentryState {
+    withinLinkLabel: boolean;
+    withinLinkDest: boolean;
+    private lastPartWasNewline;
+    checkState(token: Token): void;
+}
+/**
+ * Look for relative links within a piece of text and add them to the {@link FileRegistry}
+ * so that they can be correctly resolved during rendering.
+ */
+export declare function textContent(parserData: Omit<TextParserData, "pos">, outContent: CommentDisplayPart[], reentry: TextParserReentryState): void;
+export {};

package/dist/lib/converter/comments/textParser.js

@@ -0,0 +1,372 @@
+/**
+ * Parser to handle plain text markdown.
+ *
+ * Responsible for recognizing relative paths within the text and turning
+ * them into references.
+ * @module
+ */
+import { i18n } from "#utils";
+import { HtmlAttributeParser, ParserState } from "#node-utils";
+import { TokenSyntaxKind } from "./lexer.js";
+import MarkdownIt from "markdown-it";
+const MdHelpers = new MarkdownIt().helpers;
+/**
+ * This is incredibly unfortunate. The comment lexer owns the responsibility
+ * for splitting up text into text/code, this is totally fine for HTML links
+ * but for markdown links, ``[`code`](./link)`` is valid, so we need to keep
+ * track of state across calls to {@link textContent}.
+ */
+export class TextParserReentryState {
+    withinLinkLabel = false;
+    withinLinkDest = false;
+    lastPartWasNewline = false;
+    checkState(token) {
+        switch (token.kind) {
+            case TokenSyntaxKind.Code:
+                if (/\n\s*\n/.test(token.text)) {
+                    this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
+                }
+                break;
+            case TokenSyntaxKind.NewLine:
+                if (this.lastPartWasNewline) {
+                    this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
+                }
+                break;
+        }
+        this.lastPartWasNewline = token.kind === TokenSyntaxKind.NewLine;
+    }
+}
+/**
+ * Look for relative links within a piece of text and add them to the {@link FileRegistry}
+ * so that they can be correctly resolved during rendering.
+ */
+export function textContent(parserData, outContent, reentry) {
+    let lastPartEnd = 0;
+    let canEndMarkdownLink = true;
+    const data = {
+        ...parserData,
+        pos: 0, // relative to the token
+    };
+    function addRef(ref) {
+        canEndMarkdownLink = true;
+        outContent.push({
+            kind: "text",
+            text: data.token.text.slice(lastPartEnd, ref.pos),
+        });
+        const link = {
+            kind: "relative-link",
+            text: data.token.text.slice(ref.pos, ref.end),
+            target: ref.target,
+            targetAnchor: ref.targetAnchor,
+        };
+        outContent.push(link);
+        lastPartEnd = ref.end;
+        data.pos = ref.end;
+        if (!ref.target && data.validationOptions.invalidPath) {
+            data.validationWarning(i18n.relative_path_0_is_not_a_file_and_will_not_be_copied_to_output(data.token.text.slice(ref.pos, ref.end)), {
+                kind: TokenSyntaxKind.Text,
+                // ref.pos is relative to the token, but this pos is relative to the file.
+                pos: data.token.pos + ref.pos,
+                text: data.token.text.slice(ref.pos, ref.end),
+            });
+        }
+    }
+    while (data.pos < data.token.text.length) {
+        if (canEndMarkdownLink) {
+            const link = checkMarkdownLink(data, reentry);
+            if (link) {
+                addRef(link);
+                continue;
+            }
+            // If we're within a Markdown link, then `checkMarkdownLink`
+            // already scanned `token` up to a line feed (if any).
+            canEndMarkdownLink = !reentry.withinLinkLabel && !reentry.withinLinkDest;
+        }
+        const reference = checkReference(data);
+        if (reference) {
+            addRef(reference);
+            continue;
+        }
+        const tagLinks = checkTagLink(data);
+        if (tagLinks.length) {
+            for (const tagLink of tagLinks) {
+                addRef(tagLink);
+            }
+            continue;
+        }
+        const atNewLine = data.token.text[data.pos] === "\n";
+        data.atNewLine = atNewLine;
+        if (atNewLine && !reentry.withinLinkDest)
+            canEndMarkdownLink = true;
+        ++data.pos;
+    }
+    if (lastPartEnd !== data.token.text.length) {
+        outContent.push({ kind: "text", text: data.token.text.slice(lastPartEnd) });
+    }
+}
+/**
+ * Links are inline text with the form `[ text ]( url title )`.
+ *
+ * Images are just links with a leading `!` and lack of support for `[ref]` referring to a path
+ * defined elsewhere, we don't care about that distinction here as we'll only replace the path
+ * piece of the image.
+ *
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/link.mjs
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/image.mjs
+ */
+function checkMarkdownLink(data, reentry) {
+    const { token, sourcePath, files } = data;
+    let searchStart;
+    if (reentry.withinLinkLabel || reentry.withinLinkDest) {
+        searchStart = data.pos;
+    }
+    else if (token.text[data.pos] === "[") {
+        searchStart = data.pos + 1;
+    }
+    else {
+        return;
+    }
+    if (!reentry.withinLinkDest) {
+        const labelEnd = findLabelEnd(token.text, searchStart);
+        if (labelEnd === -1 || token.text[labelEnd] === "\n") {
+            // This markdown link might be split across multiple lines or input tokens
+            //     [prefix `code` suffix](target)
+            //     ........^^^^^^................
+            // Unless we encounter two consecutive line feeds, expect it to keep going.
+            reentry.withinLinkLabel = labelEnd !== data.pos || !data.atNewLine;
+            return;
+        }
+        reentry.withinLinkLabel = false;
+        if (!token.text.startsWith("](", labelEnd))
+            return;
+        searchStart = labelEnd + 2;
+    }
+    // Skip whitespace (including line breaks) between "](" and the link destination.
+    // https://spec.commonmark.org/0.31.2/#links
+    const end = token.text.length;
+    let lookahead = searchStart;
+    for (let newlines = 0;; ++lookahead) {
+        if (lookahead === end) {
+            reentry.withinLinkDest = true;
+            return;
+        }
+        switch (token.text[lookahead]) {
+            case "\n":
+                if (++newlines === 2) {
+                    reentry.withinLinkDest = false;
+                    return;
+                }
+                continue;
+            case " ":
+            case "\t":
+                continue;
+        }
+        break;
+    }
+    reentry.withinLinkDest = false;
+    const link = MdHelpers.parseLinkDestination(token.text, lookahead, end);
+    if (link.ok) {
+        // Only make a relative-link display part if it's actually a relative link.
+        // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
+        const decoded = decodeURI(link.str);
+        if (isRelativePath(decoded)) {
+            const { target, anchor } = files.register(sourcePath, decoded) || { target: undefined, anchor: undefined };
+            return {
+                pos: lookahead,
+                end: link.pos,
+                target,
+                targetAnchor: anchor,
+            };
+        }
+        // This was a link, skip ahead to ensure we don't happen to parse
+        // something else as a link within the link.
+        data.pos = link.pos - 1;
+    }
+}
+/**
+ * Reference definitions are blocks with the form `[label]: link title`
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_block/reference.mjs
+ *
+ * Note: This may include false positives where TypeDoc recognizes a reference block that markdown
+ * does not if users start lines with something that looks like a reference block without fully
+ * separating it from an above paragraph. For a first cut, this is good enough.
+ */
+function checkReference(data) {
+    const { atNewLine, pos, token, files, sourcePath } = data;
+    if (atNewLine) {
+        let lookahead = pos;
+        while (/[ \t]/.test(token.text[lookahead])) {
+            ++lookahead;
+        }
+        // #2991, we check that this reference also doesn't look like a footnote reference
+        // as it is unlikely that someone uses that syntax without intending for footnote behavior.
+        // This introduces a problem if someone has an [^ref] and doesn't intend for that to
+        // be interpreted as a footnote, but as a reference, but we can't have it both ways,
+        // and having people rename their reference to not be confused with a footnote isn't a
+        // horrible workaround.
+        if (token.text[lookahead] === "[" && token.text[lookahead + 1] !== "^") {
+            while (lookahead < token.text.length &&
+                /[^\n\]]/.test(token.text[lookahead])) {
+                ++lookahead;
+            }
+            if (token.text.startsWith("]:", lookahead)) {
+                lookahead += 2;
+                while (/[ \t]/.test(token.text[lookahead])) {
+                    ++lookahead;
+                }
+                const link = MdHelpers.parseLinkDestination(token.text, lookahead, token.text.length);
+                if (link.ok) {
+                    const decoded = decodeURI(link.str);
+                    if (isRelativePath(decoded)) {
+                        const { target, anchor } = files.register(sourcePath, decoded) || { target: undefined, anchor: undefined };
+                        return {
+                            pos: lookahead,
+                            end: link.pos,
+                            target,
+                            targetAnchor: anchor,
+                        };
+                    }
+                    data.pos = link.pos - 1;
+                }
+            }
+        }
+    }
+}
+/**
+ * Looks for `<a href="./relative">`, `<img src="./relative">`, and `<source srcset="./relative">`
+ */
+function checkTagLink(data) {
+    const { pos, token } = data;
+    if (token.text.startsWith("<img ", pos)) {
+        data.pos += 4;
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
+    }
+    if (token.text.startsWith("<link ", pos)) {
+        data.pos += 4;
+        return checkAttributes(data, {
+            // cspell:words imagesrcset
+            imagesrcset: checkAttributeSrcSet,
+        });
+    }
+    if (token.text.startsWith("<a ", pos)) {
+        data.pos += 3;
+        return checkAttributes(data, { href: checkAttributeDirectPath });
+    }
+    if (token.text.startsWith("<source ", pos)) {
+        data.pos += 8;
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
+    }
+    return [];
+}
+function checkAttributes(data, attributes) {
+    const links = [];
+    const parser = new HtmlAttributeParser(data.token.text, data.pos);
+    while (parser.state !== ParserState.END) {
+        if (parser.state === ParserState.BeforeAttributeValue &&
+            Object.prototype.hasOwnProperty.call(attributes, parser.currentAttributeName)) {
+            parser.step();
+            links.push(...attributes[parser.currentAttributeName](data, parser.currentAttributeValue, parser.currentAttributeValueStart, parser.currentAttributeValueEnd));
+        }
+        parser.step();
+    }
+    return links;
+}
+function checkAttributeDirectPath(data, text, pos, end) {
+    const decoded = decodeURI(text.trim());
+    if (isRelativePath(decoded)) {
+        const { target, anchor } = data.files.register(data.sourcePath, decoded) || { target: undefined, anchor: undefined };
+        return [{
+                pos,
+                end,
+                target,
+                targetAnchor: anchor,
+            }];
+    }
+    return [];
+}
+// See https://html.spec.whatwg.org/multipage/images.html#srcset-attribute
+function checkAttributeSrcSet(data, text, pos, _end) {
+    const result = [];
+    let textPos = 0;
+    parseImageCandidate();
+    while (textPos < text.length && text[textPos] == ",") {
+        ++textPos;
+        parseImageCandidate();
+    }
+    return result;
+    function parseImageCandidate() {
+        // 1. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+        // 2. A valid non-empty URL that does not start or end with a comma
+        // TypeDoc: We don't exactly match this, PR welcome! For now, just permit anything
+        // that's not whitespace or a comma
+        const url = text.slice(textPos).match(/^[^\t\r\f\n ,]+/);
+        const decoded = url && decodeURI(url[0]);
+        if (decoded && isRelativePath(decoded)) {
+            const { target, anchor } = data.files.register(data.sourcePath, decoded) || { target: undefined, anchor: undefined };
+            result.push({
+                pos: pos + textPos,
+                end: pos + textPos + url[0].length,
+                target,
+                targetAnchor: anchor,
+            });
+        }
+        textPos += url ? url[0].length : 0;
+        // 3. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+        // 4. Zero or one of the following:
+        {
+            // A width descriptor, consisting of: ASCII whitespace, a valid non-negative integer giving
+            // a number greater than zero representing the width descriptor value, and a U+0077 LATIN
+            // SMALL LETTER W character.
+            const w = text.slice(textPos).match(/^\+?\d+\s*w/);
+            textPos += w ? w[0].length : 0;
+            // A pixel density descriptor, consisting of: ASCII whitespace, a valid floating-point number
+            // giving a number greater than zero representing the pixel density descriptor value, and a
+            // U+0078 LATIN SMALL LETTER X character.
+            if (!w) {
+                const x = text.slice(textPos).match(/^\+?\d+(\.\d+)?([eE][+-]\d+)?\s*x/);
+                textPos += x ? x[0].length : 0;
+            }
+        }
+        // 5. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+    }
+}
+function isRelativePath(link) {
+    // Lots of edge cases encoded right here!
+    // Originally, this attempted to match protocol://, but...
+    // `mailto:example@example.com` is not a relative path
+    // `C:\foo` is not a relative path
+    // `/etc/passwd` is not a relative path
+    // `#anchor` is not a relative path
+    return !/^[a-z]+:|^\/|^#/i.test(link);
+}
+function findLabelEnd(text, pos) {
+    while (pos < text.length) {
+        switch (text[pos]) {
+            case "\\":
+                ++pos;
+                if (pos < text.length && text[pos] === "\n")
+                    return pos;
+                break;
+            case "\n":
+            case "]":
+            case "[":
+                return pos;
+        }
+        ++pos;
+    }
+    return -1;
+}

package/dist/lib/converter/components.d.ts

@@ -0,0 +1,4 @@
+import { AbstractComponent } from "../utils/component.js";
+import type { Converter } from "./converter.js";
+export declare abstract class ConverterComponent extends AbstractComponent<Converter, {}> {
+}