@depup/typedoc 0.28.17-depup.0

package/dist/lib/converter/components.js

@@ -0,0 +1,3 @@
+import { AbstractComponent } from "../utils/component.js";
+export class ConverterComponent extends AbstractComponent {
+}

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

@@ -0,0 +1,101 @@
+import ts from "typescript";
+import { Comment, DeclarationReflection, type DocumentReflection, type ProjectReflection, ReferenceType, type Reflection, ReflectionKind } from "../models/index.js";
+import type { Converter } from "./converter.js";
+import { type NormalizedPath } from "#utils";
+/**
+ * The context describes the current state the converter is in.
+ */
+export declare class Context {
+    /**
+     * The converter instance that has created the context.
+     */
+    readonly converter: Converter;
+    /**
+     * The TypeChecker instance returned by the TypeScript compiler.
+     */
+    get checker(): ts.TypeChecker;
+    /**
+     * The program currently being converted.
+     * Accessing this property will throw if a source file is not currently being converted.
+     */
+    get program(): ts.Program;
+    private _program?;
+    /**
+     * All programs being converted.
+     */
+    readonly programs: readonly ts.Program[];
+    /**
+     * The project that is currently processed.
+     */
+    readonly project: ProjectReflection;
+    /**
+     * The scope or parent reflection that is currently processed.
+     */
+    readonly scope: Reflection;
+    convertingTypeNode: boolean;
+    convertingClassOrInterface: boolean;
+    shouldBeStatic: boolean;
+    inlineType: Set<string>;
+    preventInline: Set<string>;
+    private reflectionIdToSymbolMap;
+    /**
+     * Create a new Context instance.
+     *
+     * @param converter  The converter instance that has created the context.
+     * @internal
+     */
+    constructor(converter: Converter, programs: readonly ts.Program[], project: ProjectReflection, scope?: Reflection);
+    /** @internal */
+    get logger(): import("#utils").Logger;
+    /**
+     * Return the type declaration of the given node.
+     *
+     * @param node  The TypeScript node whose type should be resolved.
+     * @returns The type declaration of the given node.
+     */
+    getTypeAtLocation(node: ts.Node): ts.Type | undefined;
+    getSymbolAtLocation(node: ts.Node): ts.Symbol | undefined;
+    expectSymbolAtLocation(node: ts.Node): ts.Symbol;
+    resolveAliasedSymbol(symbol: ts.Symbol): ts.Symbol;
+    createDeclarationReflection(kind: ReflectionKind, symbol: ts.Symbol | undefined, exportSymbol: ts.Symbol | undefined, nameOverride?: string): DeclarationReflection;
+    postReflectionCreation(reflection: Reflection, symbol: ts.Symbol | undefined, exportSymbol: ts.Symbol | undefined): void;
+    finalizeDeclarationReflection(reflection: DeclarationReflection): void;
+    /**
+     * Create a {@link ReferenceType} which points to the provided symbol.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     */
+    createSymbolReference(symbol: ts.Symbol, context: Context, name?: string): ReferenceType;
+    /**
+     * Create a stable {@link ReflectionSymbolId} for the provided symbol,
+     * optionally targeting a specific declaration.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     * It might also turn out to be generally useful for other plugin users.
+     */
+    createSymbolId(symbol: ts.Symbol, declaration?: ts.Declaration): import("../models/ReflectionSymbolId.js").ReflectionSymbolId;
+    addChild(reflection: DeclarationReflection | DocumentReflection): void;
+    shouldIgnore(symbol: ts.Symbol): boolean;
+    /**
+     * Register a newly generated reflection. All created reflections should be
+     * passed to this method to ensure that the project helper functions work correctly.
+     *
+     * @param reflection  The reflection that should be registered.
+     * @param symbol  The symbol the given reflection was resolved from.
+     */
+    registerReflection(reflection: Reflection, symbol: ts.Symbol | undefined, filePath?: NormalizedPath): void;
+    getReflectionFromSymbol(symbol: ts.Symbol): Reflection | undefined;
+    getSymbolFromReflection(reflection: Reflection): ts.Symbol | undefined;
+    /** @internal */
+    setActiveProgram(program: ts.Program | undefined): void;
+    private createCommentContext;
+    getComment(symbol: ts.Symbol, kind: ReflectionKind): Comment | undefined;
+    getNodeComment(node: ts.Node, moduleComment: boolean): Comment | undefined;
+    getFileComment(node: ts.SourceFile): Comment | undefined;
+    getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): Comment | undefined;
+    getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): Comment | undefined;
+    shouldInline(symbol: ts.Symbol, name: string): boolean;
+    withScope(scope: Reflection): Context;
+}

package/dist/lib/converter/context.js

@@ -0,0 +1,311 @@
+import { ok as assert } from "assert";
+import ts from "typescript";
+import { Comment, ContainerReflection, DeclarationReflection, ReferenceType, ReflectionFlag, ReflectionKind, } from "../models/index.js";
+import { isNamedNode } from "./utils/nodes.js";
+import { ConverterEvents } from "./converter-events.js";
+import { resolveAliasedSymbol } from "./utils/symbols.js";
+import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment, } from "./comments/index.js";
+import { getHumanName, getQualifiedName } from "../utils/tsutils.js";
+import { findPackageForPath, normalizePath } from "#node-utils";
+import { createSymbolIdImpl } from "./factories/symbol-id.js";
+import { removeIf } from "#utils";
+/**
+ * The context describes the current state the converter is in.
+ */
+export class Context {
+    /**
+     * The converter instance that has created the context.
+     */
+    converter;
+    /**
+     * The TypeChecker instance returned by the TypeScript compiler.
+     */
+    get checker() {
+        return this.program.getTypeChecker();
+    }
+    /**
+     * The program currently being converted.
+     * Accessing this property will throw if a source file is not currently being converted.
+     */
+    get program() {
+        assert(this._program, "Tried to access Context.program when not converting a source file");
+        return this._program;
+    }
+    _program;
+    /**
+     * All programs being converted.
+     */
+    programs;
+    /**
+     * The project that is currently processed.
+     */
+    project;
+    /**
+     * The scope or parent reflection that is currently processed.
+     */
+    scope;
+    convertingTypeNode = false; // Inherited by withScope
+    convertingClassOrInterface = false; // Not inherited
+    shouldBeStatic = false; // Not inherited
+    inlineType = new Set(); // Inherited by withScope
+    preventInline = new Set(); // Inherited by withScope
+    reflectionIdToSymbolMap = new Map();
+    /**
+     * Create a new Context instance.
+     *
+     * @param converter  The converter instance that has created the context.
+     * @internal
+     */
+    constructor(converter, programs, project, scope = project) {
+        this.converter = converter;
+        this.programs = programs;
+        this.project = project;
+        this.scope = scope;
+    }
+    /** @internal */
+    get logger() {
+        return this.converter.application.logger;
+    }
+    /**
+     * Return the type declaration of the given node.
+     *
+     * @param node  The TypeScript node whose type should be resolved.
+     * @returns The type declaration of the given node.
+     */
+    getTypeAtLocation(node) {
+        let nodeType;
+        try {
+            nodeType = this.checker.getTypeAtLocation(node);
+        }
+        catch {
+            // ignore
+        }
+        if (!nodeType) {
+            if (node.symbol) {
+                nodeType = this.checker.getDeclaredTypeOfSymbol(node.symbol);
+                // The TS types lie due to ts.SourceFile
+            }
+            else if (node.parent?.symbol) {
+                nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.symbol);
+                // The TS types lie due to ts.SourceFile
+            }
+            else if (node.parent?.parent?.symbol) {
+                nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.parent.symbol);
+            }
+        }
+        return nodeType;
+    }
+    getSymbolAtLocation(node) {
+        let symbol = this.checker.getSymbolAtLocation(node);
+        if (!symbol && isNamedNode(node)) {
+            symbol = this.checker.getSymbolAtLocation(node.name);
+        }
+        return symbol;
+    }
+    expectSymbolAtLocation(node) {
+        const symbol = this.getSymbolAtLocation(node);
+        if (!symbol) {
+            const { line } = ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.pos);
+            throw new Error(`Expected a symbol for node with kind ${ts.SyntaxKind[node.kind]} at ${node.getSourceFile().fileName}:${line + 1}`);
+        }
+        return symbol;
+    }
+    resolveAliasedSymbol(symbol) {
+        return resolveAliasedSymbol(symbol, this.checker);
+    }
+    createDeclarationReflection(kind, symbol, exportSymbol, 
+    // We need this because modules don't always have symbols.
+    nameOverride) {
+        const name = getHumanName(nameOverride ?? exportSymbol?.name ?? symbol?.name ?? "unknown");
+        if (this.convertingClassOrInterface) {
+            if (kind === ReflectionKind.Function) {
+                kind = ReflectionKind.Method;
+            }
+            if (kind === ReflectionKind.Variable) {
+                kind = ReflectionKind.Property;
+            }
+        }
+        const reflection = new DeclarationReflection(name, kind, this.scope);
+        this.postReflectionCreation(reflection, symbol, exportSymbol);
+        return reflection;
+    }
+    postReflectionCreation(reflection, symbol, exportSymbol) {
+        // Allow comments on export declarations to take priority over comments directly
+        // on the symbol to enable overriding comments on modules/references, #1504
+        if (!reflection.comment &&
+            exportSymbol &&
+            (reflection.kind &
+                (ReflectionKind.SomeModule | ReflectionKind.Reference))) {
+            reflection.comment = this.getComment(exportSymbol, reflection.kind);
+        }
+        // If that didn't get us a comment (the normal case), then get the comment from
+        // the source declarations, this is the common case.
+        if (symbol && !reflection.comment) {
+            reflection.comment = this.getComment(symbol, reflection.kind);
+        }
+        // If we still don't have a comment, check for any comments on the export declaration,
+        // we don't have to worry about functions being weird in this case as the regular declaration
+        // doesn't have any comment.
+        if (exportSymbol && !reflection.comment) {
+            reflection.comment = this.getComment(exportSymbol, ReflectionKind.Reference);
+        }
+        if (this.shouldBeStatic) {
+            reflection.setFlag(ReflectionFlag.Static);
+        }
+        if (reflection instanceof DeclarationReflection) {
+            reflection.escapedName = symbol?.escapedName ? String(symbol.escapedName) : undefined;
+            this.addChild(reflection);
+        }
+        if (symbol && this.converter.isExternal(symbol, this.checker)) {
+            reflection.setFlag(ReflectionFlag.External);
+        }
+        if (exportSymbol) {
+            this.registerReflection(reflection, exportSymbol, void 0);
+        }
+        const path = reflection.kindOf(ReflectionKind.Namespace | ReflectionKind.Module)
+            ? symbol?.declarations?.find(ts.isSourceFile)?.fileName
+            : undefined;
+        if (path) {
+            this.registerReflection(reflection, symbol, normalizePath(path));
+        }
+        else {
+            this.registerReflection(reflection, symbol, undefined);
+        }
+    }
+    finalizeDeclarationReflection(reflection) {
+        this.converter.trigger(ConverterEvents.CREATE_DECLARATION, this, reflection);
+        if (reflection.kindOf(ReflectionKind.MayContainDocuments)) {
+            this.converter.processDocumentTags(reflection, reflection);
+        }
+    }
+    /**
+     * Create a {@link ReferenceType} which points to the provided symbol.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     */
+    createSymbolReference(symbol, context, name) {
+        const ref = ReferenceType.createUnresolvedReference(name ?? symbol.name, this.createSymbolId(symbol), context.project, getQualifiedName(symbol, name ?? symbol.name));
+        ref.refersToTypeParameter = !!(symbol.flags & ts.SymbolFlags.TypeParameter);
+        const symbolPath = symbol.declarations?.[0]?.getSourceFile().fileName;
+        if (!symbolPath)
+            return ref;
+        ref.package = findPackageForPath(symbolPath)?.[0];
+        return ref;
+    }
+    /**
+     * Create a stable {@link ReflectionSymbolId} for the provided symbol,
+     * optionally targeting a specific declaration.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     * It might also turn out to be generally useful for other plugin users.
+     */
+    createSymbolId(symbol, declaration) {
+        return createSymbolIdImpl(symbol, declaration);
+    }
+    addChild(reflection) {
+        if (this.scope instanceof ContainerReflection) {
+            this.scope.addChild(reflection);
+        }
+    }
+    shouldIgnore(symbol) {
+        return this.converter.shouldIgnore(symbol, this.checker);
+    }
+    /**
+     * Register a newly generated reflection. All created reflections should be
+     * passed to this method to ensure that the project helper functions work correctly.
+     *
+     * @param reflection  The reflection that should be registered.
+     * @param symbol  The symbol the given reflection was resolved from.
+     */
+    registerReflection(reflection, symbol, filePath) {
+        if (symbol) {
+            this.reflectionIdToSymbolMap.set(reflection.id, symbol);
+            const id = this.createSymbolId(symbol);
+            // #2466
+            // If we just registered a member of a class or interface, then we need to check if
+            // we've registered this symbol before under the wrong parent reflection.
+            // This can happen because the compiler API will use non-dependently-typed symbols
+            // for properties of classes/interfaces which inherit them, so we can't rely on the
+            // property being unique for each class.
+            if (reflection.parent?.kindOf(ReflectionKind.ClassOrInterface) &&
+                reflection.kindOf(ReflectionKind.SomeMember)) {
+                const saved = this.project["symbolToReflectionIdMap"].get(id);
+                const parentSymbolReflection = symbol.parent &&
+                    this.getReflectionFromSymbol(symbol.parent);
+                if (typeof saved === "object" &&
+                    saved.length > 1 &&
+                    parentSymbolReflection) {
+                    removeIf(saved, (item) => this.project.getReflectionById(item)?.parent !==
+                        parentSymbolReflection);
+                }
+            }
+            this.project.registerReflection(reflection, id, filePath);
+        }
+        else {
+            this.project.registerReflection(reflection, void 0, filePath);
+        }
+    }
+    getReflectionFromSymbol(symbol) {
+        return this.project.getReflectionFromSymbolId(this.createSymbolId(symbol));
+    }
+    getSymbolFromReflection(reflection) {
+        return this.reflectionIdToSymbolMap.get(reflection.id);
+    }
+    /** @internal */
+    setActiveProgram(program) {
+        this._program = program;
+    }
+    createCommentContext() {
+        return {
+            config: this.converter.config,
+            logger: this.logger,
+            checker: this.checker,
+            files: this.project.files,
+            createSymbolId: (s, d) => this.createSymbolId(s, d),
+        };
+    }
+    getComment(symbol, kind) {
+        return getComment(symbol, kind, this.createCommentContext());
+    }
+    getNodeComment(node, moduleComment) {
+        return getNodeComment(node, moduleComment, this.createCommentContext());
+    }
+    getFileComment(node) {
+        return getFileComment(node, this.createCommentContext());
+    }
+    getJsDocComment(declaration) {
+        return getJsDocComment(declaration, this.createCommentContext());
+    }
+    getSignatureComment(declaration) {
+        return getSignatureComment(declaration, this.createCommentContext());
+    }
+    shouldInline(symbol, name) {
+        if (this.preventInline.has(name))
+            return false;
+        if (this.inlineType.has(name))
+            return true;
+        return this
+            .getComment(symbol, ReflectionKind.Interface)
+            ?.hasModifier("@inline") ?? false;
+    }
+    withScope(scope) {
+        assert(scope.parent === this.scope || scope === this.scope, "Incorrect context used for withScope");
+        const context = new Context(this.converter, this.programs, this.project, scope);
+        context.convertingTypeNode = this.convertingTypeNode;
+        context.setActiveProgram(this._program);
+        context.reflectionIdToSymbolMap = this.reflectionIdToSymbolMap;
+        context.preventInline = new Set(this.preventInline);
+        context.inlineType = new Set(this.inlineType);
+        for (const tag of scope.comment?.blockTags || []) {
+            if (tag.tag === "@preventInline") {
+                context.preventInline.add(Comment.combineDisplayParts(tag.content));
+            }
+            else if (tag.tag === "@inlineType") {
+                context.inlineType.add(Comment.combineDisplayParts(tag.content));
+            }
+        }
+        return context;
+    }
+}

package/dist/lib/converter/convert-expression.d.ts

@@ -0,0 +1,9 @@
+import ts from "typescript";
+/**
+ * Return the default value of the given node.
+ *
+ * @param node  The TypeScript node whose default value should be extracted.
+ * @returns The default value as a string.
+ */
+export declare function convertDefaultValue(node: ts.Declaration | undefined): string | undefined;
+export declare function convertExpression(expression: ts.Expression): string;

package/dist/lib/converter/convert-expression.js

@@ -0,0 +1,58 @@
+import ts from "typescript";
+/**
+ * Return the default value of the given node.
+ *
+ * @param node  The TypeScript node whose default value should be extracted.
+ * @returns The default value as a string.
+ */
+export function convertDefaultValue(node) {
+    const anyNode = node;
+    if (anyNode?.initializer) {
+        return convertExpression(anyNode.initializer);
+    }
+    else {
+        return undefined;
+    }
+}
+export function convertExpression(expression) {
+    switch (expression.kind) {
+        case ts.SyntaxKind.StringLiteral:
+        case ts.SyntaxKind.TrueKeyword:
+        case ts.SyntaxKind.FalseKeyword:
+        case ts.SyntaxKind.NullKeyword:
+        case ts.SyntaxKind.NumericLiteral:
+        case ts.SyntaxKind.BigIntLiteral:
+        case ts.SyntaxKind.Identifier:
+            return expression.getText();
+    }
+    if (ts.isPrefixUnaryExpression(expression)) {
+        const inner = convertExpression(expression.operand);
+        if (inner != "...") {
+            return expression.getText();
+        }
+    }
+    if (ts.isArrayLiteralExpression(expression) &&
+        expression.elements.length === 0) {
+        return "[]";
+    }
+    if (ts.isObjectLiteralExpression(expression) &&
+        expression.properties.length === 0) {
+        return "{}";
+    }
+    // a.b.c.d
+    if (ts.isPropertyAccessExpression(expression)) {
+        const parts = [expression.name.getText()];
+        let iter = expression.expression;
+        while (ts.isPropertyAccessExpression(iter)) {
+            parts.unshift(iter.name.getText());
+            iter = iter.expression;
+        }
+        if (ts.isIdentifier(iter)) {
+            parts.unshift(iter.text);
+            return parts.join(".");
+        }
+    }
+    // More complex expressions are generally not useful in the documentation.
+    // Show that there was a value, but not specifics.
+    return "...";
+}

package/dist/lib/converter/converter-events.d.ts

@@ -0,0 +1,13 @@
+export declare const ConverterEvents: {
+    readonly BEGIN: "begin";
+    readonly END: "end";
+    readonly CREATE_PROJECT: "createProject";
+    readonly CREATE_DECLARATION: "createDeclaration";
+    readonly CREATE_DOCUMENT: "createDocument";
+    readonly CREATE_SIGNATURE: "createSignature";
+    readonly CREATE_PARAMETER: "createParameter";
+    readonly CREATE_TYPE_PARAMETER: "createTypeParameter";
+    readonly RESOLVE_BEGIN: "resolveBegin";
+    readonly RESOLVE: "resolveReflection";
+    readonly RESOLVE_END: "resolveEnd";
+};

package/dist/lib/converter/converter-events.js

@@ -0,0 +1,13 @@
+export const ConverterEvents = {
+    BEGIN: "begin",
+    END: "end",
+    CREATE_PROJECT: "createProject",
+    CREATE_DECLARATION: "createDeclaration",
+    CREATE_DOCUMENT: "createDocument",
+    CREATE_SIGNATURE: "createSignature",
+    CREATE_PARAMETER: "createParameter",
+    CREATE_TYPE_PARAMETER: "createTypeParameter",
+    RESOLVE_BEGIN: "resolveBegin",
+    RESOLVE: "resolveReflection",
+    RESOLVE_END: "resolveEnd",
+};