typedoc 0.24.7 → 0.25.0

package/dist/lib/utils/jsx.js

@@ -14,7 +14,7 @@
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderElement = exports.createElement = exports.Raw = exports.Fragment = void 0;
+exports.renderElement = exports.setRenderSettings = exports.createElement = exports.Raw = exports.Fragment = void 0;
 const html_1 = require("./html");
 const jsx_elements_1 = require("./jsx.elements");
 var jsx_elements_2 = require("./jsx.elements");
@@ -71,7 +71,12 @@ function createElement(tag, props, ...children) {
     return { tag, props, children };
 }
 exports.createElement = createElement;
-function renderElement(element) {
+let renderPretty = true;
+function setRenderSettings(options) {
+    renderPretty = options.pretty;
+}
+exports.setRenderSettings = setRenderSettings;
+const renderElement = function renderElement(element) {
     if (!element) {
         return "";
     }
@@ -82,22 +87,27 @@ function renderElement(element) {
         }
         return renderElement(tag(Object.assign({ children }, props)));
     }
-    const html = [];
+    let html = "";
     if (tag !== jsx_elements_1.JsxFragment) {
-        if (blockElements.has(tag)) {
-            html.push("\n");
+        if (blockElements.has(tag) && renderPretty) {
+            html += "\n";
         }
-        html.push("<", tag);
+        html += "<";
+        html += tag;
         for (const [key, val] of Object.entries(props ?? {})) {
             if (val == null)
                 continue;
             if (typeof val == "boolean") {
                 if (val) {
-                    html.push(" ", key);
+                    html += " ";
+                    html += key;
                 }
             }
             else {
-                html.push(" ", key, "=", JSON.stringify(val));
+                html += " ";
+                html += key;
+                html += "=";
+                html += JSON.stringify(val);
             }
         }
     }
@@ -105,23 +115,27 @@ function renderElement(element) {
     if (children.length) {
         hasChildren = true;
         if (tag !== jsx_elements_1.JsxFragment)
-            html.push(">");
+            html += ">";
         renderChildren(children);
     }
     if (tag !== jsx_elements_1.JsxFragment) {
         if (!hasChildren) {
             if (voidElements.has(tag)) {
-                html.push("/>");
+                html += "/>";
             }
             else {
-                html.push("></", tag, ">");
+                html += "></";
+                html += tag;
+                html += ">";
             }
         }
         else {
-            html.push("</", tag, ">");
+            html += "</";
+            html += tag;
+            html += ">";
         }
     }
-    return html.join("");
+    return html;
     function renderChildren(children) {
         for (const child of children) {
             if (!child)
@@ -130,12 +144,12 @@ function renderElement(element) {
                 renderChildren(child);
             }
             else if (typeof child === "string" || typeof child === "number") {
-                html.push((0, html_1.escapeHtml)(child.toString()));
+                html += (0, html_1.escapeHtml)(child.toString());
             }
             else {
-                html.push(renderElement(child));
+                html += renderElement(child);
             }
         }
     }
-}
+};
 exports.renderElement = renderElement;

package/dist/lib/utils/loggers.js

@@ -19,7 +19,7 @@ var LogLevel;
     LogLevel[LogLevel["Warn"] = 2] = "Warn";
     LogLevel[LogLevel["Error"] = 3] = "Error";
     LogLevel[LogLevel["None"] = 4] = "None";
-})(LogLevel = exports.LogLevel || (exports.LogLevel = {}));
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
 const Colors = {
     red: "\u001b[91m",
     yellow: "\u001b[93m",

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

@@ -75,6 +75,7 @@ export interface TypeDocOptionMap {
     includeVersion: boolean;
     disableSources: boolean;
     sourceLinkTemplate: string;
+    disableGit: boolean;
     gitRevision: string;
     gitRemote: string;
     readme: string;
@@ -103,6 +104,7 @@ export interface TypeDocOptionMap {
     navigation: {
         includeCategories: boolean;
         includeGroups: boolean;
+        fullTree: boolean;
     };
     visibilityFilters: ManuallyValidatedOption<{
         protected?: boolean;
@@ -115,6 +117,7 @@ export interface TypeDocOptionMap {
     searchGroupBoosts: ManuallyValidatedOption<Record<string, number>>;
     commentStyle: typeof CommentStyle;
     useTsLinkResolution: boolean;
+    preserveLinkText: boolean;
     jsDocCompatibility: JsDocCompatibility;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];
@@ -222,7 +225,7 @@ export declare enum ParameterType {
      */
     GlobArray = 9,
     /**
-     * An unopinionated object that preserves default settings unless explicitly overridden
+     * An object which partially merges user-set values into the defaults.
      */
     Object = 10,
     /**

package/dist/lib/utils/options/declaration.js

@@ -22,7 +22,7 @@ var ParameterHint;
 (function (ParameterHint) {
     ParameterHint[ParameterHint["File"] = 0] = "File";
     ParameterHint[ParameterHint["Directory"] = 1] = "Directory";
-})(ParameterHint = exports.ParameterHint || (exports.ParameterHint = {}));
+})(ParameterHint || (exports.ParameterHint = ParameterHint = {}));
 var ParameterType;
 (function (ParameterType) {
     ParameterType[ParameterType["String"] = 0] = "String";
@@ -48,14 +48,14 @@ var ParameterType;
      */
     ParameterType[ParameterType["GlobArray"] = 9] = "GlobArray";
     /**
-     * An unopinionated object that preserves default settings unless explicitly overridden
+     * An object which partially merges user-set values into the defaults.
      */
     ParameterType[ParameterType["Object"] = 10] = "Object";
     /**
      * An object with true/false flags
      */
     ParameterType[ParameterType["Flags"] = 11] = "Flags";
-})(ParameterType = exports.ParameterType || (exports.ParameterType = {}));
+})(ParameterType || (exports.ParameterType = ParameterType = {}));
 const converters = {
     [ParameterType.String](value, option) {
         const stringValue = value == null ? "" : String(value);

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

@@ -38,7 +38,7 @@ export interface OptionsReader {
      * @param logger logger to be used to report errors
      * @param cwd the directory which should be treated as the current working directory for option file discovery
      */
-    read(container: Options, logger: Logger, cwd: string): void;
+    read(container: Options, logger: Logger, cwd: string): void | Promise<void>;
 }
 /**
  * Maintains a collection of option declarations split into TypeDoc options
@@ -68,12 +68,11 @@ export declare class Options {
     private _compilerOptions;
     private _fileNames;
     private _projectReferences;
-    private _logger;
     /**
      * In packages mode, the directory of the package being converted.
      */
     packageDir?: string;
-    constructor(logger: Logger);
+    constructor();
     /**
      * Clones the options, intended for use in packages mode.
      */
@@ -100,11 +99,6 @@ export declare class Options {
     restore(snapshot: {
         __optionSnapshot: never;
     }): void;
-    /**
-     * Sets the logger used when an option declaration fails to be added.
-     * @param logger
-     */
-    setLogger(logger: Logger): void;
     /**
      * Resets the option bag to all default values.
      * If a name is provided, will only reset that name.
@@ -117,7 +111,7 @@ export declare class Options {
      * @param reader
      */
     addReader(reader: OptionsReader): void;
-    read(logger: Logger, cwd?: string): void;
+    read(logger: Logger, cwd?: string): Promise<void>;
     /**
      * Adds an option declaration to the container with extra type checking to ensure that
      * the runtime type is consistent with the declared type.

package/dist/lib/utils/options/options.js

@@ -28,7 +28,7 @@ const optionSnapshots = new WeakMap();
  *    files.
  */
 class Options {
-    constructor(logger) {
+    constructor() {
         this._readers = [];
         this._declarations = new Map();
         this._values = {};
@@ -36,14 +36,13 @@ class Options {
         this._compilerOptions = {};
         this._fileNames = [];
         this._projectReferences = [];
-        this._logger = logger;
         (0, sources_1.addTypeDocOptions)(this);
     }
     /**
      * Clones the options, intended for use in packages mode.
      */
     copyForPackage(packageDir) {
-        const options = new Options(this._logger);
+        const options = new Options();
         options.packageDir = packageDir;
         options._readers = this._readers.filter((reader) => reader.supportsPackages);
         options._declarations = new Map(this._declarations);
@@ -82,13 +81,6 @@ class Options {
         this._values = JSON.parse(data.values);
         this._setOptions = new Set(data.set);
     }
-    /**
-     * Sets the logger used when an option declaration fails to be added.
-     * @param logger
-     */
-    setLogger(logger) {
-        this._logger = logger;
-    }
     reset(name) {
         if (name != null) {
             const declaration = this.getDeclaration(name);
@@ -115,15 +107,15 @@ class Options {
     addReader(reader) {
         (0, array_1.insertOrderSorted)(this._readers, reader);
     }
-    read(logger, cwd = process.cwd()) {
+    async read(logger, cwd = process.cwd()) {
         for (const reader of this._readers) {
-            reader.read(this, logger, cwd);
+            await reader.read(this, logger, cwd);
         }
     }
     addDeclaration(declaration) {
         const decl = this.getDeclaration(declaration.name);
         if (decl) {
-            this._logger.error(`The option ${declaration.name} has already been registered`);
+            throw new Error(`The option ${declaration.name} has already been registered`);
         }
         else {
             this._declarations.set(declaration.name, declaration);

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

@@ -3,7 +3,9 @@ import type { Logger } from "../../loggers";
 import type { Options } from "../options";
 /**
  * Obtains option values from typedoc.json
- * or typedoc.js (discouraged since ~0.14, don't fully deprecate until API has stabilized)
+ *
+ * Changes need to happen here at some point. I think we should follow ESLint's new config
+ * system eventually: https://eslint.org/blog/2022/08/new-config-system-part-1/
  */
 export declare class TypeDocReader implements OptionsReader {
     /**
@@ -15,7 +17,7 @@ export declare class TypeDocReader implements OptionsReader {
     /**
      * Read user configuration from a typedoc.json or typedoc.js configuration file.
      */
-    read(container: Options, logger: Logger, cwd: string): void;
+    read(container: Options, logger: Logger, cwd: string): Promise<void>;
     /**
      * Read the given options file + any extended files.
      * @param file

package/dist/lib/utils/options/readers/typedoc.js

@@ -34,9 +34,12 @@ const assert_1 = require("assert");
 const paths_1 = require("../../paths");
 const fs_1 = require("../../fs");
 const module_1 = require("module");
+const url_1 = require("url");
 /**
  * Obtains option values from typedoc.json
- * or typedoc.js (discouraged since ~0.14, don't fully deprecate until API has stabilized)
+ *
+ * Changes need to happen here at some point. I think we should follow ESLint's new config
+ * system eventually: https://eslint.org/blog/2022/08/new-config-system-part-1/
  */
 class TypeDocReader {
     constructor() {
@@ -50,7 +53,7 @@ class TypeDocReader {
     /**
      * Read user configuration from a typedoc.json or typedoc.js configuration file.
      */
-    read(container, logger, cwd) {
+    async read(container, logger, cwd) {
         const path = container.getValue("options") || cwd;
         const file = this.findTypedocFile(path);
         if (!file) {
@@ -60,7 +63,7 @@ class TypeDocReader {
             return;
         }
         const seen = new Set();
-        this.readFile(file, container, logger, seen);
+        await this.readFile(file, container, logger, seen);
     }
     /**
      * Read the given options file + any extended files.
@@ -68,7 +71,7 @@ class TypeDocReader {
      * @param container
      * @param logger
      */
-    readFile(file, container, logger, seen) {
+    async readFile(file, container, logger, seen) {
         if (seen.has(file)) {
             logger.error(`Tried to load the options file ${(0, paths_1.nicePath)(file)} multiple times.`);
             return;
@@ -86,8 +89,27 @@ class TypeDocReader {
             }
         }
         else {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            fileContent = require(file);
+            try {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    fileContent = await require(file);
+                }
+                catch (error) {
+                    if (error?.code === "ERR_REQUIRE_ESM") {
+                        // On Windows, we need to ensure this path is a file path.
+                        // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                        const esmPath = (0, url_1.pathToFileURL)(file).toString();
+                        fileContent = await (await import(esmPath)).default;
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            catch (error) {
+                logger.error(`Failed to read ${(0, paths_1.nicePath)(file)}: ${error instanceof Error ? error.message : error}`);
+                return;
+            }
         }
         if (typeof fileContent !== "object" || !fileContent) {
             logger.error(`The root value of ${(0, paths_1.nicePath)(file)} is not an object.`);
@@ -108,7 +130,7 @@ class TypeDocReader {
                     logger.error(`Failed to resolve ${extendedFile} to a file in ${(0, paths_1.nicePath)(file)}`);
                     continue;
                 }
-                this.readFile(resolvedParent, container, logger, seen);
+                await this.readFile(resolvedParent, container, logger, seen);
             }
             delete data["extends"];
         }
@@ -138,14 +160,18 @@ class TypeDocReader {
             (0, path_1.join)(path, "typedoc.jsonc"),
             (0, path_1.join)(path, "typedoc.config.js"),
             (0, path_1.join)(path, "typedoc.config.cjs"),
+            (0, path_1.join)(path, "typedoc.config.mjs"),
             (0, path_1.join)(path, "typedoc.js"),
             (0, path_1.join)(path, "typedoc.cjs"),
+            (0, path_1.join)(path, "typedoc.mjs"),
             (0, path_1.join)(path, ".config/typedoc.json"),
             (0, path_1.join)(path, ".config/typedoc.jsonc"),
             (0, path_1.join)(path, ".config/typedoc.config.js"),
             (0, path_1.join)(path, ".config/typedoc.config.cjs"),
+            (0, path_1.join)(path, ".config/typedoc.config.mjs"),
             (0, path_1.join)(path, ".config/typedoc.js"),
             (0, path_1.join)(path, ".config/typedoc.cjs"),
+            (0, path_1.join)(path, ".config/typedoc.mjs"),
         ].find(fs_1.isFile);
     }
 }

package/dist/lib/utils/options/sources/typedoc.js

@@ -111,7 +111,6 @@ function addTypeDocOptions(options) {
                 kind_1.ReflectionKind.TypeLiteral,
                 kind_1.ReflectionKind.TypeParameter,
                 kind_1.ReflectionKind.Parameter,
-                kind_1.ReflectionKind.ObjectLiteral,
             ]) {
                 valid.delete(kind_1.ReflectionKind[notPermitted]);
             }
@@ -322,13 +321,18 @@ function addTypeDocOptions(options) {
         name: "sourceLinkTemplate",
         help: "Specify a link template to be used when generating source urls. If not set, will be automatically created using the git remote. Supports {path}, {line}, {gitRevision} placeholders.",
     });
+    options.addDeclaration({
+        name: "disableGit",
+        help: "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath",
+        type: declaration_1.ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "gitRevision",
-        help: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files.",
+        help: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files. Has no effect if disableSources is set.",
     });
     options.addDeclaration({
         name: "gitRemote",
-        help: "Use the specified remote for linking to GitHub/Bitbucket source files.",
+        help: "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set.",
         defaultValue: "origin",
     });
     options.addDeclaration({
@@ -414,6 +418,7 @@ function addTypeDocOptions(options) {
         defaults: {
             includeCategories: false,
             includeGroups: false,
+            fullTree: false,
         },
     });
     options.addDeclaration({
@@ -499,6 +504,12 @@ function addTypeDocOptions(options) {
         type: declaration_1.ParameterType.Boolean,
         defaultValue: true,
     });
+    options.addDeclaration({
+        name: "preserveLinkText",
+        help: "If set, @link tags without link text will use the text content as the link. If not set, will use the target reflection name.",
+        type: declaration_1.ParameterType.Boolean,
+        defaultValue: true,
+    });
     options.addDeclaration({
         name: "blockTags",
         help: "Block tags which TypeDoc should recognize when parsing comments.",
@@ -539,7 +550,7 @@ function addTypeDocOptions(options) {
         name: "categorizeByGroup",
         help: "Specify whether categorization will be done at the group level.",
         type: declaration_1.ParameterType.Boolean,
-        defaultValue: true, // 0.25, change this to false.
+        defaultValue: false,
     });
     options.addDeclaration({
         name: "defaultCategory",

package/dist/lib/utils/options/tsdoc-defaults.d.ts

@@ -3,4 +3,4 @@ export declare const blockTags: readonly ["@deprecated", "@param", "@remarks", "
 export declare const tsdocInlineTags: readonly ["@link", "@inheritDoc", "@label"];
 export declare const inlineTags: string[];
 export declare const tsdocModifierTags: readonly ["@public", "@private", "@protected", "@internal", "@readonly", "@packageDocumentation", "@eventProperty", "@alpha", "@beta", "@experimental", "@sealed", "@override", "@virtual"];
-export declare const modifierTags: readonly ["@public", "@private", "@protected", "@internal", "@readonly", "@packageDocumentation", "@eventProperty", "@alpha", "@beta", "@experimental", "@sealed", "@override", "@virtual", "@hidden", "@ignore", "@enum", "@event", "@overload", "@namespace", "@interface"];
+export declare const modifierTags: readonly ["@public", "@private", "@protected", "@internal", "@readonly", "@packageDocumentation", "@eventProperty", "@alpha", "@beta", "@experimental", "@sealed", "@override", "@virtual", "@hidden", "@ignore", "@enum", "@event", "@overload", "@namespace", "@interface", "@showCategories", "@hideCategories", "@showGroups", "@hideGroups"];

package/dist/lib/utils/options/tsdoc-defaults.js

@@ -54,4 +54,8 @@ exports.modifierTags = [
     "@overload",
     "@namespace",
     "@interface",
+    "@showCategories",
+    "@hideCategories",
+    "@showGroups",
+    "@hideGroups",
 ];

package/dist/lib/utils/package-manifest.d.ts

@@ -1,36 +1,11 @@
 import type { Logger } from "./loggers";
 import type { Minimatch } from "minimatch";
-import { additionalProperties, Infer } from "./validation";
 /**
  * Loads a package.json and validates that it is a JSON Object
  */
 export declare function loadPackageManifest(logger: Logger, packageJsonPath: string): Record<string, unknown> | undefined;
-declare const typedocPackageManifestConfigSchema: {
-    displayName: import("./validation").Optional<StringConstructor>;
-    entryPoint: import("./validation").Optional<StringConstructor>;
-    readmeFile: import("./validation").Optional<StringConstructor>;
-    tsconfig: import("./validation").Optional<StringConstructor>;
-    [additionalProperties]: boolean;
-};
-export type TypedocPackageManifestConfig = Infer<typeof typedocPackageManifestConfigSchema>;
-/**
- * Extracts typedoc specific config from a specified package manifest
- */
-export declare function extractTypedocConfigFromPackageManifest(logger: Logger, packageJsonPath: string): TypedocPackageManifestConfig | undefined;
 /**
  * Given a list of (potentially wildcarded) package paths,
  * return all the actual package folders found.
  */
 export declare function expandPackages(logger: Logger, packageJsonDir: string, workspaces: string[], exclude: Minimatch[]): string[];
-export declare const ignorePackage: unique symbol;
-/**
- * Given a package.json, attempt to find the TS file that defines its entry point
- * The JS must be built with sourcemaps.
- *
- * When the TS file cannot be determined, the intention is to
- * - Ignore things which don't appear to be `require`-able node packages.
- * - Fail on things which appear to be `require`-able node packages but are missing
- *   the necessary metadata for us to document.
- */
-export declare function getTsEntryPointForPackage(logger: Logger, packageJsonPath: string, packageJson: Record<string, unknown>): string | undefined | typeof ignorePackage;
-export {};