typedoc 0.23.25 → 0.24.0-beta.1

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

@@ -3,3 +3,20 @@ export declare class DefaultMap<K, V> extends Map<K, V> {
     constructor(creator: () => V);
     get(key: K): V;
 }
+export declare class StableKeyMap<K extends {
+    getStableKey(): string;
+}, V> implements Map<K, V> {
+    [Symbol.toStringTag]: string;
+    private impl;
+    get size(): number;
+    set(key: K, value: V): this;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    clear(): void;
+    delete(key: K): boolean;
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}

package/dist/lib/utils/map.js

@@ -1,6 +1,7 @@
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultMap = void 0;
+exports.StableKeyMap = exports.DefaultMap = void 0;
 class DefaultMap extends Map {
     constructor(creator) {
         super();
@@ -17,3 +18,50 @@ class DefaultMap extends Map {
     }
 }
 exports.DefaultMap = DefaultMap;
+class StableKeyMap {
+    constructor() {
+        this[_a] = "StableKeyMap";
+        this.impl = new Map();
+    }
+    get size() {
+        return this.impl.size;
+    }
+    set(key, value) {
+        this.impl.set(key.getStableKey(), [key, value]);
+        return this;
+    }
+    get(key) {
+        return this.impl.get(key.getStableKey())?.[1];
+    }
+    has(key) {
+        return this.get(key) != null;
+    }
+    clear() {
+        this.impl.clear();
+    }
+    delete(key) {
+        return this.impl.delete(key.getStableKey());
+    }
+    forEach(callbackfn, thisArg) {
+        for (const [k, v] of this.entries()) {
+            callbackfn.apply(thisArg, [v, k, this]);
+        }
+    }
+    entries() {
+        return this.impl.values();
+    }
+    *keys() {
+        for (const [k] of this.entries()) {
+            yield k;
+        }
+    }
+    *values() {
+        for (const [, v] of this.entries()) {
+            yield v;
+        }
+    }
+    [(_a = Symbol.toStringTag, Symbol.iterator)]() {
+        return this.entries();
+    }
+}
+exports.StableKeyMap = StableKeyMap;

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

@@ -10,7 +10,7 @@ export declare const EmitStrategy: {
     readonly none: "none";
 };
 /** @hidden */
-export type EmitStrategy = (typeof EmitStrategy)[keyof typeof EmitStrategy];
+export type EmitStrategy = typeof EmitStrategy[keyof typeof EmitStrategy];
 /**
  * Determines how TypeDoc searches for comments.
  * @enum
@@ -21,7 +21,7 @@ export declare const CommentStyle: {
     readonly Line: "line";
     readonly All: "all";
 };
-export type CommentStyle = (typeof CommentStyle)[keyof typeof CommentStyle];
+export type CommentStyle = typeof CommentStyle[keyof typeof CommentStyle];
 /**
  * An interface describing all TypeDoc specific options. Generated from a
  * map which contains more information about each option for better types when
@@ -41,6 +41,17 @@ export type TypeDocOptionValues = {
 /**
  * Describes all TypeDoc options. Used internally to provide better types when fetching options.
  * External consumers should likely use {@link TypeDocOptions} instead.
+ *
+ * If writing a plugin, you may find it useful to use declaration merging to add your options to this interface
+ * so that you have autocomplete when using `app.options.getValue`.
+ *
+ * ```ts
+ * declare module "typedoc" {
+ *   export interface TypeDocOptionMap {
+ *     pluginOption: string[];
+ *   }
+ * }
+ * ```
  */
 export interface TypeDocOptionMap {
     options: string;
@@ -52,7 +63,6 @@ export interface TypeDocOptionMap {
     externalPattern: string[];
     excludeExternals: boolean;
     excludeNotDocumented: boolean;
-    excludeNotDocumentedKinds: Array<keyof typeof ReflectionKind>;
     excludeInternal: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;
@@ -95,7 +105,7 @@ export interface TypeDocOptionMap {
     defaultCategory: string;
     categoryOrder: string[];
     sort: SortStrategy[];
-    kindSortOrder: Array<keyof typeof ReflectionKind>;
+    kindSortOrder: ReflectionKind.KindString[];
     visibilityFilters: ManuallyValidatedOption<{
         protected?: boolean;
         private?: boolean;
@@ -112,12 +122,11 @@ export interface TypeDocOptionMap {
     version: boolean;
     showConfig: boolean;
     plugin: string[];
-    logger: unknown;
     logLevel: typeof LogLevel;
     treatWarningsAsErrors: boolean;
     intentionallyNotExported: string[];
     validation: ValidationOptions;
-    requiredToBeDocumented: (keyof typeof ReflectionKind)[];
+    requiredToBeDocumented: ReflectionKind.KindString[];
 }
 /**
  * Wrapper type for values in TypeDocOptionMap which are represented with an unknown option type, but
@@ -199,6 +208,11 @@ export interface DeclarationOptionBase {
      * If not set, the type will be a string.
      */
     type?: ParameterType;
+    /**
+     * If set, this option will be omitted from `--help`, and attempting to specify it on the command
+     * line will produce an error.
+     */
+    configFileOnly?: boolean;
 }
 export interface StringDeclarationOption extends DeclarationOptionBase {
     /**

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

@@ -21,7 +21,7 @@ function getParameterHelp(options) {
     const helps = [];
     let margin = 0;
     for (const parameter of parameters) {
-        if (!parameter.help) {
+        if (!parameter.help || parameter.configFileOnly) {
             continue;
         }
         let name = " --" + parameter.name;

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

@@ -9,35 +9,36 @@ import { DeclarationOption, KeyToDeclaration, TypeDocOptionMap, TypeDocOptions,
  */
 export interface OptionsReader {
     /**
-     * Readers will be processed according to their priority.
-     * A higher priority indicates that the reader should be called *later* so that
-     * it can override options set by lower priority readers.
+     * Readers will be processed according to their orders.
+     * A higher order indicates that the reader should be called *later*.
      *
      * Note that to preserve expected behavior, the argv reader must have both the lowest
-     * priority so that it may set the location of config files used by other readers and
-     * the highest priority so that it can override settings from lower priority readers.
-     *
-     * Note: In 0.23. `priority` will be renamed to `order`, with the same meaning
+     * order so that it may set the location of config files used by other readers and
+     * the highest order so that it can override settings from lower order readers.
      */
-    priority: number;
+    readonly order: number;
     /**
      * The name of this reader so that it may be removed by plugins without the plugin
      * accessing the instance performing the read. Multiple readers may have the same
      * name.
      */
-    name: string;
+    readonly name: string;
+    /**
+     * Flag to indicate that this reader should be included in sub-options objects created
+     * to read options for packages mode.
+     */
+    readonly supportsPackages: boolean;
     /**
      * Read options from the reader's source and place them in the options parameter.
      * Options without a declared name may be treated as if they were declared with type
      * {@link ParameterType.Mixed}. Options which have been declared must be converted to the
      * correct type. As an alternative to doing this conversion in the reader,
      * the reader may use {@link Options.setValue}, which will correctly convert values.
-     * @param options
-     * @param compilerOptions
      * @param container the options container that provides declarations
-     * @param logger
+     * @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): void;
+    read(container: Options, logger: Logger, cwd: string): void;
 }
 /**
  * Maintains a collection of option declarations split into TypeDoc options
@@ -69,6 +70,10 @@ export declare class Options {
     private _projectReferences;
     private _logger;
     constructor(logger: Logger);
+    /**
+     * Clones the options, intended for use in packages mode.
+     */
+    copyForPackage(): Options;
     /**
      * Marks the options as readonly, enables caching when fetching options, which improves performance.
      */
@@ -96,10 +101,6 @@ export declare class Options {
      * @param logger
      */
     setLogger(logger: Logger): void;
-    /**
-     * Adds the option declarations declared by the TypeDoc and all supported TypeScript declarations.
-     */
-    addDefaultDeclarations(): void;
     /**
      * Resets the option bag to all default values.
      * If a name is provided, will only reset that name.
@@ -112,7 +113,7 @@ export declare class Options {
      * @param reader
      */
     addReader(reader: OptionsReader): void;
-    read(logger: Logger): void;
+    read(logger: Logger, cwd?: string): void;
     /**
      * Adds an option declaration to the container with extra type checking to ensure that
      * the runtime type is consistent with the declared type.
@@ -177,6 +178,14 @@ export declare class Options {
      * Sets the compiler options that will be used to get a TS program.
      */
     setCompilerOptions(fileNames: readonly string[], options: ts.CompilerOptions, projectReferences: readonly ts.ProjectReference[] | undefined): void;
+    /**
+     * Discover similar option names to the given name, for use in error reporting.
+     */
+    getSimilarOptions(missingName: string): string[];
+    /**
+     * Get the help message to be displayed to the user if `--help` is passed.
+     */
+    getHelp(): string;
 }
 /**
  * Binds an option to the given property. Does not register the option.

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

@@ -5,6 +5,7 @@ const declaration_1 = require("./declaration");
 const array_1 = require("../array");
 const declaration_2 = require("./declaration");
 const sources_1 = require("./sources");
+const help_1 = require("./help");
 const optionSnapshots = new WeakMap();
 /**
  * Maintains a collection of option declarations split into TypeDoc options
@@ -36,6 +37,16 @@ class Options {
         this._fileNames = [];
         this._projectReferences = [];
         this._logger = logger;
+        (0, sources_1.addTypeDocOptions)(this);
+    }
+    /**
+     * Clones the options, intended for use in packages mode.
+     */
+    copyForPackage() {
+        const options = new Options(this._logger);
+        options._readers = this._readers.filter((reader) => reader.supportsPackages);
+        options._declarations = new Map(this._declarations);
+        return options;
     }
     /**
      * Marks the options as readonly, enables caching when fetching options, which improves performance.
@@ -77,12 +88,6 @@ class Options {
     setLogger(logger) {
         this._logger = logger;
     }
-    /**
-     * Adds the option declarations declared by the TypeDoc and all supported TypeScript declarations.
-     */
-    addDefaultDeclarations() {
-        (0, sources_1.addTypeDocOptions)(this);
-    }
     reset(name) {
         if (name != null) {
             const declaration = this.getDeclaration(name);
@@ -107,11 +112,11 @@ class Options {
      * @param reader
      */
     addReader(reader) {
-        (0, array_1.insertPrioritySorted)(this._readers, reader);
+        (0, array_1.insertOrderSorted)(this._readers, reader);
     }
-    read(logger) {
+    read(logger, cwd = process.cwd()) {
         for (const reader of this._readers) {
-            reader.read(this, logger);
+            reader.read(this, logger, cwd);
         }
     }
     addDeclaration(declaration) {
@@ -152,7 +157,8 @@ class Options {
     getValue(name) {
         const declaration = this.getDeclaration(name);
         if (!declaration) {
-            throw new Error(`Unknown option '${name}'`);
+            const nearNames = this.getSimilarOptions(name);
+            throw new Error(`Unknown option '${name}', you may have meant:\n\t${nearNames.join("\n\t")}`);
         }
         return this._values[declaration.name];
     }
@@ -162,7 +168,8 @@ class Options {
         }
         const declaration = this.getDeclaration(name);
         if (!declaration) {
-            throw new Error(`Tried to set an option (${name}) that was not declared.`);
+            const nearNames = this.getSimilarOptions(name);
+            throw new Error(`Tried to set an option (${name}) that was not declared. You may have meant:\n\t${nearNames.join("\n\t")}`);
         }
         let oldValue = this._values[declaration.name];
         if (typeof oldValue === "undefined")
@@ -226,6 +233,28 @@ class Options {
         this._compilerOptions = { ...options };
         this._projectReferences = projectReferences ?? [];
     }
+    /**
+     * Discover similar option names to the given name, for use in error reporting.
+     */
+    getSimilarOptions(missingName) {
+        const results = {};
+        let lowest = Infinity;
+        for (const name of this._declarations.keys()) {
+            const distance = editDistance(missingName, name);
+            lowest = Math.min(lowest, distance);
+            results[distance] || (results[distance] = []);
+            results[distance].push(name);
+        }
+        // Experimenting a bit, it seems an edit distance of 3 is roughly the
+        // right metric for relevant "similar" results without showing obviously wrong suggestions
+        return results[lowest].concat(results[lowest + 1] || [], results[lowest + 2] || []);
+    }
+    /**
+     * Get the help message to be displayed to the user if `--help` is passed.
+     */
+    getHelp() {
+        return (0, help_1.getOptionsHelp)(this);
+    }
 }
 exports.Options = Options;
 function BindOption(name) {
@@ -234,9 +263,6 @@ function BindOption(name) {
             get() {
                 const options = "options" in this ? this.options : this.application.options;
                 const value = options.getValue(name);
-                if (options.isFrozen()) {
-                    Object.defineProperty(this, key, { value });
-                }
                 return value;
             },
             enumerable: true,
@@ -245,3 +271,31 @@ function BindOption(name) {
     };
 }
 exports.BindOption = BindOption;
+// Based on https://en.wikipedia.org/wiki/Levenshtein_distance#Iterative_with_two_matrix_rows
+// Slightly modified for improved match results for options
+function editDistance(s, t) {
+    if (s.length < t.length)
+        return editDistance(t, s);
+    let v0 = Array.from({ length: t.length + 1 }, (_, i) => i);
+    let v1 = Array.from({ length: t.length + 1 }, () => 0);
+    for (let i = 0; i < s.length; i++) {
+        v1[0] = i + 1;
+        for (let j = 0; j < s.length; j++) {
+            const deletionCost = v0[j + 1] + 1;
+            const insertionCost = v1[j] + 1;
+            let substitutionCost;
+            if (s[i] === t[j]) {
+                substitutionCost = v0[j];
+            }
+            else if (s[i]?.toUpperCase() === t[j]?.toUpperCase()) {
+                substitutionCost = v0[j] + 1;
+            }
+            else {
+                substitutionCost = v0[j] + 3;
+            }
+            v1[j + 1] = Math.min(deletionCost, insertionCost, substitutionCost);
+        }
+        [v0, v1] = [v1, v0];
+    }
+    return v0[t.length];
+}

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

@@ -5,7 +5,8 @@ import type { Logger } from "../../loggers";
  */
 export declare class ArgumentsReader implements OptionsReader {
     readonly name = "arguments";
-    readonly priority: number;
+    readonly order: number;
+    readonly supportsPackages = false;
     private args;
     constructor(priority: number, args?: string[]);
     read(container: Options, logger: Logger): void;

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

@@ -15,7 +15,8 @@ const ARRAY_OPTION_TYPES = new Set([
 class ArgumentsReader {
     constructor(priority, args = process.argv.slice(2)) {
         this.name = "arguments";
-        this.priority = priority;
+        this.supportsPackages = false;
+        this.order = priority;
         this.args = args;
     }
     read(container, logger) {
@@ -38,6 +39,10 @@ class ArgumentsReader {
                 ? (index++, options.getDeclaration(name.replace(/^--?/, "")))
                 : options.getDeclaration("entryPoints");
             if (decl) {
+                if (decl.configFileOnly) {
+                    logger.error(`The '${decl.name}' option can only be specified via a config file.`);
+                    continue;
+                }
                 if (seen.has(decl.name) && ARRAY_OPTION_TYPES.has(decl.type)) {
                     trySet(decl.name, options.getValue(decl.name).concat(this.args[index]));
                 }
@@ -82,7 +87,9 @@ class ArgumentsReader {
                     continue;
                 }
             }
-            logger.error(`Unknown option: ${name}`);
+            logger.error(`Unknown option: ${name}, you may have meant:\n\t${options
+                .getSimilarOptions(name)
+                .join("\n\t")}`);
             index++;
         }
     }

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

@@ -4,15 +4,11 @@ export declare class TSConfigReader implements OptionsReader {
     /**
      * Note: Runs after the {@link TypeDocReader}.
      */
-    priority: number;
+    order: number;
     name: string;
+    supportsPackages: boolean;
     private seenTsdocPaths;
-    /**
-     * Not considered part of the public API. You can use it, but it might break.
-     * @internal
-     */
-    static findConfigFile(file: string): string | undefined;
-    read(container: Options, logger: Logger): void;
+    read(container: Options, logger: Logger, cwd: string): void;
     private addTagsFromTsdocJson;
     private readTsDoc;
 }

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

@@ -1,13 +1,32 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TSConfigReader = void 0;
 const path_1 = require("path");
-const fs_1 = require("fs");
-const typescript_1 = __importDefault(require("typescript"));
-const fs_2 = require("../../fs");
+const ts = __importStar(require("typescript"));
+const fs_1 = require("../../fs");
 const assert_1 = require("assert");
 const validation_1 = require("../../validation");
 const paths_1 = require("../../paths");
@@ -15,12 +34,7 @@ const module_1 = require("module");
 const tsdoc_defaults_1 = require("../tsdoc-defaults");
 const array_1 = require("../../array");
 const entry_point_1 = require("../../entry-point");
-function isFile(file) {
-    return (0, fs_1.existsSync)(file) && (0, fs_1.statSync)(file).isFile();
-}
-function isDir(path) {
-    return (0, fs_1.existsSync)(path) && (0, fs_1.statSync)(path).isDirectory();
-}
+const tsconfig_1 = require("../../tsconfig");
 function isSupportForTags(obj) {
     return ((0, validation_1.validate)({}, obj) &&
         Object.entries(obj).every(([key, val]) => {
@@ -52,27 +66,14 @@ class TSConfigReader {
         /**
          * Note: Runs after the {@link TypeDocReader}.
          */
-        this.priority = 200;
+        this.order = 200;
         this.name = "tsconfig-json";
+        this.supportsPackages = true;
         this.seenTsdocPaths = new Set();
     }
-    /**
-     * Not considered part of the public API. You can use it, but it might break.
-     * @internal
-     */
-    static findConfigFile(file) {
-        let fileToRead = file;
-        if (isDir(fileToRead)) {
-            fileToRead = typescript_1.default.findConfigFile(file, isFile);
-        }
-        if (!fileToRead || !isFile(fileToRead)) {
-            return;
-        }
-        return fileToRead;
-    }
-    read(container, logger) {
-        const file = container.getValue("tsconfig");
-        let fileToRead = TSConfigReader.findConfigFile(file);
+    read(container, logger, cwd) {
+        const file = container.getValue("tsconfig") || cwd;
+        let fileToRead = (0, tsconfig_1.findTsConfigFile)(file);
         if (!fileToRead) {
             // If the user didn't give us this option, we shouldn't complain about not being able to find it.
             if (container.isSet("tsconfig")) {
@@ -84,12 +85,10 @@ class TSConfigReader {
             }
             return;
         }
-        fileToRead = (0, fs_2.normalizePath)((0, path_1.resolve)(fileToRead));
+        fileToRead = (0, fs_1.normalizePath)((0, path_1.resolve)(fileToRead));
+        logger.verbose(`Reading tsconfig at ${(0, paths_1.nicePath)(fileToRead)}`);
         this.addTagsFromTsdocJson(container, logger, (0, path_1.resolve)(fileToRead));
-        const parsed = typescript_1.default.getParsedCommandLineOfConfigFile(fileToRead, {}, {
-            ...typescript_1.default.sys,
-            onUnRecoverableConfigFileDiagnostic: logger.diagnostic.bind(logger),
-        });
+        const parsed = (0, tsconfig_1.readTsConfig)(fileToRead, logger);
         if (!parsed) {
             return;
         }
@@ -121,7 +120,7 @@ class TSConfigReader {
     addTagsFromTsdocJson(container, logger, tsconfig) {
         this.seenTsdocPaths.clear();
         const tsdoc = (0, path_1.join)((0, path_1.dirname)(tsconfig), "tsdoc.json");
-        if (!isFile(tsdoc)) {
+        if (!(0, fs_1.isFile)(tsdoc)) {
             return;
         }
         const overwritten = ["blockTags", "inlineTags", "modifierTags"].filter((opt) => container.isSet(opt));
@@ -163,7 +162,7 @@ class TSConfigReader {
             return;
         }
         this.seenTsdocPaths.add(path);
-        const { config, error } = typescript_1.default.readConfigFile((0, fs_2.normalizePath)(path), typescript_1.default.sys.readFile);
+        const { config, error } = ts.readConfigFile((0, fs_1.normalizePath)(path), ts.sys.readFile);
         if (error) {
             logger.error(`Failed to read tsdoc.json file at ${(0, paths_1.nicePath)(path)}.`);
             return;

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

@@ -9,14 +9,13 @@ export declare class TypeDocReader implements OptionsReader {
     /**
      * Should run before the tsconfig reader so that it can specify a tsconfig file to read.
      */
-    priority: number;
+    order: number;
     name: string;
+    supportsPackages: boolean;
     /**
      * Read user configuration from a typedoc.json or typedoc.js configuration file.
-     * @param container
-     * @param logger
      */
-    read(container: Options, logger: Logger): void;
+    read(container: Options, logger: Logger, cwd: string): void;
     /**
      * Read the given options file + any extended files.
      * @param file
@@ -25,7 +24,7 @@ export declare class TypeDocReader implements OptionsReader {
      */
     private readFile;
     /**
-     * Search for the configuration file given path
+     * Search for the typedoc.js or typedoc.json file from the given path
      *
      * @param  path Path to the typedoc.(js|json) file. If path is a directory
      *   typedoc file will be attempted to be found at the root of this path