typedoc 0.28.0-beta.2 → 0.28.1

package/dist/lib/output/router.js

@@ -34,13 +34,16 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import { CategoryPlugin } from "../converter/plugins/CategoryPlugin.js";
 import { GroupPlugin } from "../converter/plugins/GroupPlugin.js";
-import { ReflectionKind, } from "../models/index.js";
+import { ProjectReflection, Reflection, ReflectionKind } from "../models/index.js";
 import { createNormalizedUrl } from "#node-utils";
 import { Option } from "../utils/index.js";
 import { Slugger } from "./themes/default/Slugger.js";
 import { getHierarchyRoots } from "./themes/lib.js";
 /**
  * The type of page which should be rendered. This may be extended in the future.
+ *
+ * Note: TypeDoc any string may be used as the page kind. TypeDoc defines a few
+ * described by this object.
  * @enum
  */
 export const PageKind = {
@@ -49,6 +52,18 @@ export const PageKind = {
     Document: "document",
     Hierarchy: "hierarchy",
 };
+function getFullName(target) {
+    if (target instanceof ProjectReflection) {
+        return target.name;
+    }
+    const parts = [target.name];
+    let current = target;
+    while (!(current instanceof ProjectReflection)) {
+        parts.unshift(current.name);
+        current = current.parent;
+    }
+    return parts.join(".");
+}
 /**
  * Base router class intended to make it easier to implement a router.
  *
@@ -128,24 +143,27 @@ let BaseRouter = (() => {
             }
             return pages;
         }
-        hasUrl(reflection) {
-            return this.fullUrls.has(reflection);
+        hasUrl(target) {
+            return this.fullUrls.has(target);
         }
-        getLinkableReflections() {
+        getLinkTargets() {
             return Array.from(this.fullUrls.keys());
         }
-        getAnchor(refl) {
-            if (!this.anchors.has(refl)) {
-                this.application.logger.verbose(`${refl.getFullName()} does not have an anchor but one was requested, this is a bug in the theme`);
+        getAnchor(target) {
+            if (!this.anchors.has(target)) {
+                this.application.logger.verbose(`${getFullName(target)} does not have an anchor but one was requested, this is a bug in the theme`);
             }
-            return this.anchors.get(refl);
+            return this.anchors.get(target);
         }
-        hasOwnDocument(refl) {
-            return this.anchors.get(refl) === undefined && this.hasUrl(refl);
+        hasOwnDocument(target) {
+            return this.anchors.get(target) === undefined && this.hasUrl(target);
         }
         relativeUrl(from, to) {
             let slashes = 0;
             while (!this.hasOwnDocument(from)) {
+                // We know we must have a parent here as the Project is the only
+                // root level element without a parent, and the project always has
+                // an own document.
                 from = from.parent;
             }
             const fromUrl = this.getFullUrl(from);
@@ -163,7 +181,7 @@ let BaseRouter = (() => {
                     }
                 }
             }
-            if (equal && !to.isProject()) {
+            if (equal && !(to instanceof ProjectReflection)) {
                 if (fromUrl === toUrl) {
                     return "";
                 }
@@ -178,28 +196,35 @@ let BaseRouter = (() => {
                 if (full[i] === "/")
                     ++slashes;
             }
+            // #2910 avoid urls like ".././"
+            if (target == "./" && slashes !== 0) {
+                return "../".repeat(slashes);
+            }
             return "../".repeat(slashes) + target;
         }
-        getFullUrl(refl) {
-            const url = this.fullUrls.get(refl);
+        getFullUrl(target) {
+            const url = this.fullUrls.get(target);
             if (!url) {
-                throw new Error(`Tried to get a URL of a reflection ${refl.getFullName()} which did not receive a URL`);
+                throw new Error(`Tried to get a URL of a router target ${getFullName(target)} which did not receive a URL`);
             }
             return url;
         }
-        getSlugger(reflection) {
-            if (this.sluggers.has(reflection)) {
-                return this.sluggers.get(reflection);
+        getSlugger(target) {
+            if (this.sluggers.has(target)) {
+                return this.sluggers.get(target);
             }
             // A slugger should always be defined at least for the project
-            return this.getSlugger(reflection.parent);
+            return this.getSlugger(target.parent);
         }
         /**
          * Should the page kind to use if a reflection should have its own rendered
          * page in the output. Note that once `undefined` is returned, children of
          * that reflection will not have their own document.
          */
-        getPageKind(reflection) {
+        getPageKind(target) {
+            if (!(target instanceof Reflection)) {
+                return undefined;
+            }
             const pageReflectionKinds = ReflectionKind.Class |
                 ReflectionKind.Interface |
                 ReflectionKind.Enum |
@@ -209,38 +234,43 @@ let BaseRouter = (() => {
                 ReflectionKind.Function |
                 ReflectionKind.Variable;
             const documentReflectionKinds = ReflectionKind.Document;
-            if (reflection.kindOf(pageReflectionKinds)) {
+            if (target.kindOf(pageReflectionKinds)) {
                 return PageKind.Reflection;
             }
-            if (reflection.kindOf(documentReflectionKinds)) {
+            if (target.kindOf(documentReflectionKinds)) {
                 return PageKind.Document;
             }
         }
-        buildChildPages(reflection, outPages) {
-            const kind = this.getPageKind(reflection);
+        buildChildPages(target, outPages) {
+            const kind = this.getPageKind(target);
             if (kind) {
-                const idealName = this.getIdealBaseName(reflection);
+                const idealName = this.getIdealBaseName(target);
                 const actualName = this.getFileName(idealName);
-                this.fullUrls.set(reflection, actualName);
-                this.sluggers.set(reflection, new Slugger(this.sluggerConfiguration));
+                this.fullUrls.set(target, actualName);
+                this.sluggers.set(target, new Slugger(this.sluggerConfiguration));
                 outPages.push({
                     kind,
-                    model: reflection,
+                    model: target,
                     url: actualName,
                 });
-                reflection.traverse((child) => {
-                    this.buildChildPages(child, outPages);
-                    return true;
-                });
+                if (target instanceof Reflection) {
+                    target.traverse((child) => {
+                        this.buildChildPages(child, outPages);
+                        return true;
+                    });
+                }
             }
             else {
-                this.buildAnchors(reflection, reflection.parent);
+                this.buildAnchors(target, target.parent);
             }
         }
-        buildAnchors(reflection, pageReflection) {
-            if (!reflection.isDeclaration() &&
-                !reflection.isSignature() &&
-                !reflection.isTypeParameter()) {
+        buildAnchors(target, pageTarget) {
+            if (!(target instanceof Reflection) || !(pageTarget instanceof Reflection)) {
+                return;
+            }
+            if (!target.isDeclaration() &&
+                !target.isSignature() &&
+                !target.isTypeParameter()) {
                 return;
             }
             // We support linking to reflections for types directly contained within an export
@@ -248,16 +278,16 @@ let BaseRouter = (() => {
             // for a property depending on whether or not it is deemed useful, and defining a link
             // which might not be used may result in a link being generated which isn't valid. #2808.
             // This should be kept in sync with the renderingChildIsUseful function.
-            if (reflection.kindOf(ReflectionKind.TypeLiteral) &&
-                (!reflection.parent?.kindOf(ReflectionKind.SomeExport) ||
-                    reflection.parent.type?.type !==
+            if (target.kindOf(ReflectionKind.TypeLiteral) &&
+                (!target.parent?.kindOf(ReflectionKind.SomeExport) ||
+                    target.parent.type?.type !==
                         "reflection")) {
                 return;
             }
-            if (!reflection.kindOf(ReflectionKind.TypeLiteral)) {
-                let refl = reflection;
+            if (!target.kindOf(ReflectionKind.TypeLiteral)) {
+                let refl = target;
                 const parts = [refl.name];
-                while (refl.parent && refl.parent !== pageReflection) {
+                while (refl.parent && refl.parent !== pageTarget) {
                     refl = refl.parent;
                     // Avoid duplicate names for signatures and useless __type in anchors
                     if (!refl.kindOf(ReflectionKind.TypeLiteral |
@@ -265,12 +295,12 @@ let BaseRouter = (() => {
                         parts.unshift(refl.name);
                     }
                 }
-                const anchor = this.getSlugger(pageReflection).slug(parts.join("."));
-                this.fullUrls.set(reflection, this.fullUrls.get(pageReflection) + "#" + anchor);
-                this.anchors.set(reflection, anchor);
+                const anchor = this.getSlugger(pageTarget).slug(parts.join("."));
+                this.fullUrls.set(target, this.fullUrls.get(pageTarget) + "#" + anchor);
+                this.anchors.set(target, anchor);
             }
-            reflection.traverse((child) => {
-                this.buildAnchors(child, pageReflection);
+            target.traverse((child) => {
+                this.buildAnchors(child, pageTarget);
                 return true;
             });
         }

package/dist/lib/output/theme.d.ts

@@ -1,6 +1,5 @@
 import { RendererComponent } from "./components.js";
 import type { PageEvent, RendererEvent } from "./events.js";
-import type { Reflection } from "../models/index.js";
 /**
  * Base class of all themes.
  *
@@ -11,7 +10,7 @@ export declare abstract class Theme extends RendererComponent {
     /**
      * Renders the provided page to a string, which will be written to disk by the {@link Renderer}
      */
-    abstract render(event: PageEvent<Reflection>): string;
+    abstract render(event: PageEvent): string;
     /**
      * Optional hook to call pre-render jobs
      */

package/dist/lib/output/themes/MarkedPlugin.js

@@ -39,7 +39,22 @@ import { Option } from "../../utils/index.js";
 import { highlight, isLoadedLanguage, isSupportedLanguage } from "../../utils/highlighter.js";
 import { assertNever, escapeHtml, i18n, JSX } from "#utils";
 import { anchorIcon } from "./default/partials/anchor-icon.js";
-import { ReflectionKind, } from "../../models/index.js";
+import { Reflection, ReflectionKind, } from "../../models/index.js";
+function getFriendlyFullName(target) {
+    if (target instanceof Reflection) {
+        return target.getFriendlyFullName();
+    }
+    if (target.parent) {
+        return target.name;
+    }
+    const parts = [target.name];
+    let current = target;
+    while (current.parent) {
+        parts.unshift(current.name);
+        current = current.parent;
+    }
+    return parts.join(".");
+}
 /**
  * Implements markdown and relativeURL helpers for templates.
  * @internal
@@ -115,11 +130,11 @@ let MarkedPlugin = (() => {
             lang = lang || "typescript";
             lang = lang.toLowerCase();
             if (!isSupportedLanguage(lang)) {
-                this.application.logger.warn(i18n.unsupported_highlight_language_0_not_highlighted_in_comment_for_1(lang, this.page?.model.getFriendlyFullName() ?? "(unknown)"));
+                this.application.logger.warn(i18n.unsupported_highlight_language_0_not_highlighted_in_comment_for_1(lang, getFriendlyFullName(this.page?.model || { name: "(unknown)" })));
                 return text;
             }
             if (!isLoadedLanguage(lang)) {
-                this.application.logger.warn(i18n.unloaded_language_0_not_highlighted_in_comment_for_1(lang, this.page?.model.getFriendlyFullName() ?? "(unknown)"));
+                this.application.logger.warn(i18n.unloaded_language_0_not_highlighted_in_comment_for_1(lang, getFriendlyFullName(this.page?.model || { name: "(unknown)" })));
                 return text;
             }
             return highlight(text, lang);
@@ -258,7 +273,7 @@ let MarkedPlugin = (() => {
             for (const { source, target, link } of this.renderedRelativeLinks) {
                 const slugger = this.owner.router.getSlugger(target);
                 if (!slugger.hasAnchor(link.targetAnchor)) {
-                    this.application.logger.warn(i18n.reflection_0_links_to_1_but_anchor_does_not_exist_try_2(source.getFriendlyFullName(), link.text, slugger
+                    this.application.logger.warn(i18n.reflection_0_links_to_1_but_anchor_does_not_exist_try_2(getFriendlyFullName(source), link.text, slugger
                         .getSimilarAnchors(link.targetAnchor)
                         .map((a) => link.text.replace(/#.*/, "#" + a))
                         .join("\n\t")));

package/dist/lib/output/themes/default/DefaultTheme.d.ts

@@ -61,7 +61,7 @@ export declare class DefaultTheme extends Theme {
      * @param renderer  The renderer this theme is attached to.
      */
     constructor(renderer: Renderer);
-    render(page: PageEvent<Reflection>): string;
+    render(page: PageEvent): string;
     preRender(_event: RendererEvent): Promise<void>;
     private _navigationCache;
     /**

package/dist/lib/output/themes/default/DefaultTheme.js

@@ -140,12 +140,19 @@ let DefaultTheme = (() => {
             this.router = renderer.router;
         }
         render(page) {
-            const template = {
+            const templateMapping = {
                 [PageKind.Index]: this.indexTemplate,
                 [PageKind.Document]: this.documentTemplate,
                 [PageKind.Hierarchy]: this.hierarchyTemplate,
                 [PageKind.Reflection]: this.reflectionTemplate,
-            }[page.pageKind];
+            };
+            const template = templateMapping[page.pageKind];
+            if (!template) {
+                throw new Error(`TypeDoc's DefaultTheme does not support the page kind ${page.pageKind}`);
+            }
+            if (!page.isReflectionEvent()) {
+                throw new Error(`TypeDoc's DefaultTheme requires that a page model be a reflection when rendering ${page.pageKind}`);
+            }
             const templateOutput = this.defaultLayoutTemplate(page, template);
             return "<!DOCTYPE html>" + JSX.renderElement(templateOutput) + "\n";
         }

package/dist/lib/output/themes/default/layouts/default.js

@@ -67,7 +67,7 @@ export const defaultLayout = (context, template, props) => (JSX.createElement("h
         JSX.createElement("script", null,
             JSX.createElement(JSX.Raw, { html: 'document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";' }),
             JSX.createElement(JSX.Raw, { html: 'document.body.style.display="none";' }),
-            JSX.createElement(JSX.Raw, { html: 'setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)' })),
+            JSX.createElement(JSX.Raw, { html: 'setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)' })),
         context.toolbar(props),
         JSX.createElement("div", { class: "container container-main" },
             JSX.createElement("div", { class: "col-content" },

package/dist/lib/utils/entry-point.d.ts

@@ -36,7 +36,7 @@ export interface DocumentEntryPoint {
     displayName: string;
     path: NormalizedPath;
 }
-export declare function inferEntryPoints(logger: Logger, options: Options): DocumentationEntryPoint[];
+export declare function inferEntryPoints(logger: Logger, options: Options, programs?: ts.Program[]): DocumentationEntryPoint[];
 export declare function getEntryPoints(logger: Logger, options: Options): DocumentationEntryPoint[] | undefined;
 /**
  * Document entry points are markdown documents that the user has requested we include in the project with

package/dist/lib/utils/entry-point.js

@@ -30,7 +30,7 @@ export const EntryPointStrategy = {
      */
     Merge: "merge",
 };
-export function inferEntryPoints(logger, options) {
+export function inferEntryPoints(logger, options, programs) {
     const packageJson = discoverPackageJson(options.packageDir ?? process.cwd());
     if (!packageJson) {
         logger.warn(i18n.no_entry_points_provided());
@@ -38,7 +38,7 @@ export function inferEntryPoints(logger, options) {
     }
     const pathEntries = inferPackageEntryPointPaths(packageJson.file);
     const entryPoints = [];
-    const programs = getEntryPrograms(pathEntries.map((p) => p[1]), logger, options);
+    programs ||= getEntryPrograms(pathEntries.map((p) => p[1]), logger, options);
     // See also: addInferredDeclarationMapPaths in ReflectionSymbolId
     const jsToTsSource = new Map();
     for (const program of programs) {
@@ -137,10 +137,20 @@ export function getWatchEntryPoints(logger, options, program) {
     const strategy = options.getValue("entryPointStrategy");
     switch (strategy) {
         case EntryPointStrategy.Resolve:
-            result = getEntryPointsForPaths(logger, expandGlobs(entryPoints, exclude, logger), options, [program]);
+            if (options.isSet("entryPoints")) {
+                result = getEntryPointsForPaths(logger, expandGlobs(entryPoints, exclude, logger), options, [program]);
+            }
+            else {
+                result = inferEntryPoints(logger, options, [program]);
+            }
             break;
         case EntryPointStrategy.Expand:
-            result = getExpandedEntryPointsForPaths(logger, expandGlobs(entryPoints, exclude, logger), options, [program]);
+            if (options.isSet("entryPoints")) {
+                result = getExpandedEntryPointsForPaths(logger, expandGlobs(entryPoints, exclude, logger), options, [program]);
+            }
+            else {
+                result = inferEntryPoints(logger, options, [program]);
+            }
             break;
         case EntryPointStrategy.Packages:
             logger.error(i18n.watch_does_not_support_packages_mode());

package/dist/lib/utils/html.js

@@ -52,7 +52,7 @@ export function createNormalizedUrl(url) {
         }
         codePoints[i] = Chars.UNDERSCORE;
     }
-    return String.fromCharCode(...codePoints);
+    return String.fromCodePoint(...codePoints);
 }
 var Chars;
 (function (Chars) {

package/dist/lib/utils/options/declaration.d.ts

@@ -26,7 +26,7 @@ export type CommentStyle = (typeof CommentStyle)[keyof typeof CommentStyle];
 export type OutputSpecification = {
     name: string;
     path: string;
-    options?: Partial<TypeDocOptions>;
+    options?: TypeDocOptions;
 };
 /**
  * List of option names which, with `entryPointStrategy` set to `packages`
@@ -40,12 +40,13 @@ export declare const rootPackageOptions: readonly ["plugin", "packageOptions", "
  * @interface
  */
 export type TypeDocOptions = {
-    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is
  * slightly more restrictive than the {@link TypeDocOptions} since it does not allow both
  * keys and values for mapped option types, and does not allow partials of flag values.
+ * It also does not mark keys as optional.
  * @interface
  */
 export type TypeDocOptionValues = {
@@ -80,7 +81,7 @@ export interface TypeDocOptionMap {
     plugin: NormalizedPathOrModule[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
-    packageOptions: ManuallyValidatedOption<Partial<TypeDocPackageOptions>>;
+    packageOptions: ManuallyValidatedOption<TypeDocPackageOptions>;
     entryPoints: GlobString[];
     entryPointStrategy: typeof EntryPointStrategy;
     alwaysCreateEntryPointModule: boolean;

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

@@ -138,7 +138,7 @@ export declare class Options {
     /**
      * Gets all of the TypeDoc option values defined in this option container.
      */
-    getRawValues(): Readonly<Partial<TypeDocOptions>>;
+    getRawValues(): Readonly<Partial<TypeDocOptionValues>>;
     /**
      * Gets a value for the given option key, throwing if the option has not been declared.
      * @param name
@@ -151,7 +151,7 @@ export declare class Options {
      * @param value
      * @param configPath the directory to resolve Path type values against
      */
-    setValue<K extends keyof TypeDocOptions>(name: K, value: TypeDocOptions[K], configPath?: string): void;
+    setValue<K extends keyof TypeDocOptions>(name: K, value: Exclude<TypeDocOptions[K], undefined>, configPath?: string): void;
     setValue(name: NeverIfInternal<string>, value: NeverIfInternal<unknown>, configPath?: NeverIfInternal<string>): void;
     /**
      * Gets the set compiler options.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.0-beta.2",
+  "version": "0.28.1",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
@@ -31,7 +31,7 @@
     "pnpm": ">= 10"
   },
   "dependencies": {
-    "@gerrit0/mini-shiki": "^3.0.0",
+    "@gerrit0/mini-shiki": "^3.2.1",
     "lunr": "^2.3.9",
     "markdown-it": "^14.1.0",
     "minimatch": "^9.0.5",
@@ -41,7 +41,7 @@
     "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x"
   },
   "devDependencies": {
-    "@eslint/js": "^9.21.0",
+    "@eslint/js": "^9.22.0",
     "@types/lunr": "^2.3.7",
     "@types/markdown-it": "^14.1.2",
     "@types/mocha": "^10.0.10",
@@ -49,14 +49,14 @@
     "@typestrong/fs-fixture-builder": "github:TypeStrong/fs-fixture-builder#34113409e3a171e68ce5e2b55461ef5c35591cfe",
     "c8": "^10.1.3",
     "dprint": "^0.49.0",
-    "esbuild": "^0.24.2",
-    "eslint": "^9.21.0",
+    "esbuild": "^0.25.1",
+    "eslint": "^9.22.0",
     "mocha": "^11.1.0",
-    "puppeteer": "^24.2.1",
+    "puppeteer": "^24.4.0",
     "semver": "^7.7.1",
     "tsx": "^4.19.3",
-    "typescript": "5.8.1-rc",
-    "typescript-eslint": "^8.24.1"
+    "typescript": "5.8.2",
+    "typescript-eslint": "^8.26.1"
   },
   "files": [
     "/bin",