@depup/typedoc 0.28.17-depup.0

package/dist/lib/models/FileRegistry.d.ts

@@ -0,0 +1,46 @@
+import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+import type { ProjectReflection, Reflection } from "./index.js";
+import type { ReflectionId } from "./Reflection.js";
+import { type NormalizedPath } from "#utils";
+export type FileId = number & {
+    __mediaIdBrand: never;
+};
+export declare class FileRegistry {
+    protected nextId: number;
+    protected mediaToReflection: Map<FileId, ReflectionId>;
+    protected mediaToPath: Map<FileId, NormalizedPath>;
+    protected reflectionToPath: Map<ReflectionId, NormalizedPath>;
+    protected pathToMedia: Map<NormalizedPath, FileId>;
+    protected names: Map<FileId, string>;
+    protected nameUsage: Map<string, number>;
+    registerAbsolute(absolute: NormalizedPath): {
+        target: FileId;
+        anchor: string | undefined;
+    };
+    /**
+     * Registers the specified path as the canonical file for this reflection
+     */
+    registerReflection(absolute: NormalizedPath, reflection: Reflection): void;
+    /**
+     * Registers the specified path as a path which should be resolved to the specified
+     * reflection. A reflection *may* be associated with multiple paths.
+     */
+    registerReflectionPath(absolute: NormalizedPath, reflection: Reflection): void;
+    getReflectionPath(reflection: Reflection): string | undefined;
+    register(sourcePath: NormalizedPath, relativePath: NormalizedPath): {
+        target: FileId;
+        anchor: string | undefined;
+    } | undefined;
+    removeReflection(reflection: Reflection): void;
+    resolve(id: FileId, project: ProjectReflection): string | Reflection | undefined;
+    resolvePath(id: FileId): string | undefined;
+    getName(id: FileId): string | undefined;
+    getNameToAbsoluteMap(): ReadonlyMap<string, string>;
+    toObject(ser: Serializer): JSONOutput.FileRegistry;
+    /**
+     * Revive a file registry from disc.
+     * Note that in the packages context this may be called multiple times on
+     * a single object, and should merge in files from the other registries.
+     */
+    fromObject(de: Deserializer, obj: JSONOutput.FileRegistry): void;
+}

package/dist/lib/models/FileRegistry.js

@@ -0,0 +1,133 @@
+import { NormalizedPathUtils } from "#utils";
+export class FileRegistry {
+    nextId = 1;
+    // The combination of these two make up the registry
+    mediaToReflection = new Map();
+    mediaToPath = new Map();
+    reflectionToPath = new Map();
+    pathToMedia = new Map();
+    // Lazily created as we get names for rendering
+    names = new Map();
+    nameUsage = new Map();
+    registerAbsolute(absolute) {
+        const anchorIndex = absolute.indexOf("#");
+        let anchor = undefined;
+        if (anchorIndex !== -1) {
+            anchor = absolute.substring(anchorIndex + 1);
+            absolute = absolute.substring(0, anchorIndex);
+        }
+        const existing = this.pathToMedia.get(absolute);
+        if (existing) {
+            return { target: existing, anchor };
+        }
+        this.mediaToPath.set(this.nextId, absolute);
+        this.pathToMedia.set(absolute, this.nextId);
+        return { target: this.nextId++, anchor };
+    }
+    /**
+     * Registers the specified path as the canonical file for this reflection
+     */
+    registerReflection(absolute, reflection) {
+        const { target } = this.registerAbsolute(absolute);
+        this.reflectionToPath.set(reflection.id, absolute);
+        this.mediaToReflection.set(target, reflection.id);
+    }
+    /**
+     * Registers the specified path as a path which should be resolved to the specified
+     * reflection. A reflection *may* be associated with multiple paths.
+     */
+    registerReflectionPath(absolute, reflection) {
+        const { target } = this.registerAbsolute(absolute);
+        this.mediaToReflection.set(target, reflection.id);
+    }
+    getReflectionPath(reflection) {
+        return this.reflectionToPath.get(reflection.id);
+    }
+    register(sourcePath, relativePath) {
+        return this.registerAbsolute(NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath));
+    }
+    removeReflection(reflection) {
+        const absolute = this.reflectionToPath.get(reflection.id);
+        if (absolute) {
+            const media = this.pathToMedia.get(absolute);
+            this.mediaToReflection.delete(media);
+        }
+    }
+    resolve(id, project) {
+        const reflId = this.mediaToReflection.get(id);
+        if (typeof reflId === "number") {
+            return project.getReflectionById(reflId);
+        }
+        return this.mediaToPath.get(id);
+    }
+    resolvePath(id) {
+        return this.mediaToPath.get(id);
+    }
+    getName(id) {
+        const absolute = this.mediaToPath.get(id);
+        if (!absolute)
+            return;
+        if (this.names.has(id)) {
+            return this.names.get(id);
+        }
+        const file = NormalizedPathUtils.basename(absolute);
+        if (!this.nameUsage.has(file)) {
+            this.nameUsage.set(file, 1);
+            this.names.set(id, file);
+        }
+        else {
+            const { name, ext } = NormalizedPathUtils.splitFilename(file);
+            let counter = this.nameUsage.get(file);
+            while (this.nameUsage.has(`${name}-${counter}${ext}`)) {
+                ++counter;
+            }
+            this.nameUsage.set(file, counter + 1);
+            this.nameUsage.set(`${name}-${counter}${ext}`, counter + 1);
+            this.names.set(id, `${name}-${counter}${ext}`);
+        }
+        return this.names.get(id);
+    }
+    getNameToAbsoluteMap() {
+        const result = new Map();
+        for (const [id, name] of this.names.entries()) {
+            result.set(name, this.mediaToPath.get(id));
+        }
+        return result;
+    }
+    toObject(ser) {
+        const result = {
+            entries: {},
+            reflections: {},
+        };
+        for (const [key, val] of this.mediaToPath.entries()) {
+            result.entries[key] = NormalizedPathUtils.relative(ser.projectRoot, val);
+        }
+        for (const [key, val] of this.mediaToReflection.entries()) {
+            // A registry may be shared by multiple projects. When serializing,
+            // only save reflection mapping for reflections in the serialized project.
+            if (ser.project.getReflectionById(val)) {
+                result.reflections[key] = val;
+            }
+        }
+        return result;
+    }
+    /**
+     * Revive a file registry from disc.
+     * Note that in the packages context this may be called multiple times on
+     * a single object, and should merge in files from the other registries.
+     */
+    fromObject(de, obj) {
+        for (const [fileId, path] of Object.entries(obj.entries)) {
+            const absolute = NormalizedPathUtils.resolve(de.projectRoot, path);
+            de.oldFileIdToNewFileId[+fileId] = this.registerAbsolute(absolute).target;
+        }
+        de.defer((project) => {
+            for (const [fileId, reflId] of Object.entries(obj.reflections)) {
+                const refl = project.getReflectionById(de.oldIdToNewId[reflId]);
+                if (refl) {
+                    this.mediaToReflection.set(de.oldFileIdToNewFileId[+fileId], refl.id);
+                }
+            }
+        });
+    }
+}

package/dist/lib/models/ParameterReflection.d.ts

@@ -0,0 +1,21 @@
+import type { SomeType } from "./index.js";
+import { Reflection, type TraverseCallback } from "./Reflection.js";
+import type { SignatureReflection } from "./SignatureReflection.js";
+import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+/**
+ * @category Reflections
+ */
+export declare class ParameterReflection extends Reflection {
+    readonly variant = "param";
+    parent?: SignatureReflection;
+    defaultValue?: string;
+    type?: SomeType;
+    traverse(callback: TraverseCallback): void;
+    isParameter(): this is ParameterReflection;
+    /**
+     * Return a string representation of this reflection.
+     */
+    toString(): string;
+    toObject(serializer: Serializer): JSONOutput.ParameterReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.ParameterReflection): void;
+}

package/dist/lib/models/ParameterReflection.js

@@ -0,0 +1,39 @@
+import { ReflectionType } from "./types.js";
+import { Reflection, TraverseProperty } from "./Reflection.js";
+/**
+ * @category Reflections
+ */
+export class ParameterReflection extends Reflection {
+    variant = "param";
+    defaultValue;
+    type;
+    traverse(callback) {
+        if (this.type instanceof ReflectionType) {
+            if (callback(this.type.declaration, TraverseProperty.TypeLiteral) === false) {
+                return;
+            }
+        }
+    }
+    isParameter() {
+        return true;
+    }
+    /**
+     * Return a string representation of this reflection.
+     */
+    toString() {
+        return (super.toString() + (this.type ? ": " + this.type.toString() : ""));
+    }
+    toObject(serializer) {
+        return {
+            ...super.toObject(serializer),
+            variant: this.variant,
+            type: serializer.toObject(this.type),
+            defaultValue: this.defaultValue,
+        };
+    }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        this.type = de.reviveType(obj.type);
+        this.defaultValue = obj.defaultValue;
+    }
+}

package/dist/lib/models/ProjectReflection.d.ts

@@ -0,0 +1,112 @@
+import { type Reflection } from "./Reflection.js";
+import { ContainerReflection } from "./ContainerReflection.js";
+import type { DeclarationReflection } from "./DeclarationReflection.js";
+import { type Type } from "./types.js";
+import { ReflectionKind } from "./kind.js";
+import { type CommentDisplayPart } from "./Comment.js";
+import { ReflectionSymbolId } from "./ReflectionSymbolId.js";
+import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+import { type NormalizedPath } from "#utils";
+import type { FileRegistry } from "./FileRegistry.js";
+export declare const JSON_SCHEMA_VERSION = "2.0";
+/**
+ * A reflection that represents the root of the project.
+ *
+ * The project reflection acts as a global index, one may receive all reflections
+ * and source files of the processed project through this reflection.
+ * @category Reflections
+ */
+export declare class ProjectReflection extends ContainerReflection {
+    readonly variant = "project";
+    private symbolToReflectionIdMap;
+    private reflectionIdToSymbolIdMap;
+    private removedSymbolIds;
+    private referenceGraph?;
+    private reflectionChildren;
+    /**
+     * A list of all reflections within the project. DO NOT MUTATE THIS OBJECT.
+     * All mutation should be done via {@link registerReflection} and {@link removeReflection}
+     * to ensure that links to reflections remain valid.
+     *
+     * This may be replaced with a `Map<number, Reflection>` someday.
+     */
+    reflections: {
+        [id: number]: Reflection;
+    };
+    /**
+     * The name of the package that this reflection documents according to package.json.
+     */
+    packageName?: string;
+    /**
+     * The version of the package that this reflection documents according to package.json.
+     */
+    packageVersion?: string;
+    /**
+     * The contents of the readme.md file of the project when found.
+     */
+    readme?: CommentDisplayPart[];
+    /**
+     * Object which describes where to find content for relative links.
+     */
+    readonly files: FileRegistry;
+    constructor(name: string, registry: FileRegistry);
+    /**
+     * Return whether this reflection is the root / project reflection.
+     */
+    isProject(): this is ProjectReflection;
+    /**
+     * Return a list of all reflections in this project of a certain kind.
+     *
+     * @param kind  The desired kind of reflection.
+     * @returns     An array containing all reflections with the desired kind.
+     */
+    getReflectionsByKind(kind: ReflectionKind): Reflection[];
+    /**
+     * Registers the given reflection so that it can be quickly looked up by helper methods.
+     * Should be called for *every* reflection added to the project.
+     *
+     * Note: During conversion, `Context.registerReflection` should be used instead so
+     * that symbols can be saved for later use.
+     */
+    registerReflection(reflection: Reflection, id: ReflectionSymbolId | undefined, filePath: NormalizedPath | undefined): void;
+    /**
+     * Removes references to reflections contained within the provided type.
+     * Plugins which overwrite types on reflections should pass the type to this
+     * method before overwriting the property.
+     * @since 0.26.6
+     */
+    removeTypeReflections(type: Type | undefined): void;
+    /**
+     * Removes a reflection from the documentation. Can be used by plugins to filter reflections
+     * out of the generated documentation. Has no effect if the reflection is not present in the
+     * project.
+     */
+    removeReflection(reflection: Reflection): void;
+    /** @internal */
+    mergeReflections(source: DeclarationReflection, target: DeclarationReflection | ProjectReflection): void;
+    /**
+     * Remove a reflection without updating the parent reflection to remove references to the removed reflection.
+     */
+    private _removeReflection;
+    /**
+     * Gets the reflection registered for the given reflection ID, or undefined if it is not present
+     * in the project.
+     */
+    getReflectionById(id: number): Reflection | undefined;
+    /**
+     * Gets the reflection associated with the given symbol id, if it exists.
+     * If there are multiple reflections associated with this symbol, gets the first one.
+     * @internal
+     */
+    getReflectionFromSymbolId(symbolId: ReflectionSymbolId): Reflection | undefined;
+    /** @internal */
+    getReflectionsFromSymbolId(symbolId: ReflectionSymbolId): Reflection[];
+    /** @internal */
+    getSymbolIdFromReflection(reflection: Reflection): ReflectionSymbolId | undefined;
+    /** @internal */
+    registerSymbolId(reflection: Reflection, id: ReflectionSymbolId): void;
+    symbolIdHasBeenRemoved(id: ReflectionSymbolId): boolean;
+    private getReferenceGraph;
+    toObject(serializer: Serializer): JSONOutput.ProjectReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.ProjectReflection): void;
+}