typedoc 0.25.12 → 0.26.0-beta.0

package/dist/lib/converter/utils/repository.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.guessSourceUrlTemplate = exports.GitRepository = exports.AssumedRepository = exports.gitIsInstalled = void 0;
+exports.GitRepository = exports.AssumedRepository = void 0;
+exports.gitIsInstalled = gitIsInstalled;
+exports.guessSourceUrlTemplate = guessSourceUrlTemplate;
 const child_process_1 = require("child_process");
 const base_path_1 = require("../utils/base-path");
 const TEN_MEGABYTES = 1024 * 10000;
@@ -16,7 +18,6 @@ function gitIsInstalled() {
     haveGit ??= git("--version").status === 0;
     return haveGit;
 }
-exports.gitIsInstalled = gitIsInstalled;
 class AssumedRepository {
     constructor(path, gitRevision, sourceLinkTemplate) {
         this.path = path;
@@ -26,10 +27,11 @@ class AssumedRepository {
     getURL(fileName, line) {
         const replacements = {
             gitRevision: this.gitRevision,
+            "gitRevision:short": this.gitRevision.substring(0, 8),
             path: fileName.substring(this.path.length + 1),
             line,
         };
-        return this.sourceLinkTemplate.replace(/\{(gitRevision|path|line)\}/g, (_, key) => replacements[key]);
+        return this.sourceLinkTemplate.replace(/\{(gitRevision|gitRevision:short|path|line)\}/g, (_, key) => replacements[key]);
     }
 }
 exports.AssumedRepository = AssumedRepository;
@@ -71,10 +73,11 @@ class GitRepository {
         }
         const replacements = {
             gitRevision: this.gitRevision,
+            "gitRevision:short": this.gitRevision.substring(0, 8),
             path: fileName.substring(this.path.length + 1),
             line,
         };
-        return this.urlTemplate.replace(/\{(gitRevision|path|line)\}/g, (_, key) => replacements[key]);
+        return this.urlTemplate.replace(/\{(gitRevision|gitRevision:short|path|line)\}/g, (_, key) => replacements[key]);
     }
     /**
      * Try to create a new repository instance.
@@ -89,7 +92,7 @@ class GitRepository {
         const topLevel = git("-C", path, "rev-parse", "--show-toplevel");
         if (topLevel.status !== 0)
             return;
-        gitRevision ||= git("-C", path, "rev-parse", "--short", "HEAD").stdout.trim();
+        gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
         if (!gitRevision)
             return; // Will only happen in a repo with no commits.
         let urlTemplate;
@@ -102,7 +105,7 @@ class GitRepository {
                 urlTemplate = guessSourceUrlTemplate(remotesOut.stdout.split("\n"));
             }
             else {
-                logger.warn(`The provided git remote "${gitRemote}" was not valid. Source links will be broken.`);
+                logger.warn(logger.i18n.git_remote_0_not_valid(gitRemote));
             }
         }
         if (!urlTemplate)
@@ -154,4 +157,3 @@ function guessSourceUrlTemplate(remotes) {
     }
     return `https://${hostname}/${user}/${project}/${sourcePath}/{gitRevision}/{path}#${anchorPrefix}{line}`;
 }
-exports.guessSourceUrlTemplate = guessSourceUrlTemplate;

package/dist/lib/converter/utils/symbols.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveAliasedSymbol = void 0;
+exports.resolveAliasedSymbol = resolveAliasedSymbol;
 const typescript_1 = __importDefault(require("typescript"));
 function resolveAliasedSymbol(symbol, checker) {
     const seen = new Set();
@@ -16,4 +16,3 @@ function resolveAliasedSymbol(symbol, checker) {
     }
     return symbol;
 }
-exports.resolveAliasedSymbol = resolveAliasedSymbol;

package/dist/lib/internationalization/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Internationalization module, see {@link "Adding Locales" | Adding Locales} for details on extending TypeDoc.
+ *
+ * @module
+ * @document ../../../internal-docs/internationalization.md
+ */
+export { type TranslatableStrings, Internationalization, type TranslatedString, type TranslationProxy, } from "./internationalization";

package/dist/lib/internationalization/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Internationalization = void 0;
+/**
+ * Internationalization module, see {@link "Adding Locales" | Adding Locales} for details on extending TypeDoc.
+ *
+ * @module
+ * @document ../../../internal-docs/internationalization.md
+ */
+var internationalization_1 = require("./internationalization");
+Object.defineProperty(exports, "Internationalization", { enumerable: true, get: function () { return internationalization_1.Internationalization; } });

package/dist/lib/internationalization/internationalization.d.ts

@@ -0,0 +1,92 @@
+import type { Application } from "../application";
+import { type BuiltinTranslatableStringArgs } from "./translatable";
+import { ReflectionKind } from "../models/reflections/kind";
+/**
+ * ### What is translatable?
+ * TypeDoc includes a lot of literal strings. By convention, messages which are displayed
+ * to the user at the INFO level or above should be present in this object to be available
+ * for translation. Messages at the VERBOSE level need not be translated as they are primarily
+ * intended for debugging. ERROR/WARNING deprecation messages related to TypeDoc's API, or
+ * requesting users submit a bug report need not be translated.
+ *
+ * Errors thrown by TypeDoc are generally *not* considered translatable as they are not
+ * displayed to the user. An exception to this is errors thrown by the `validate` method
+ * on options, as option readers will use them to report errors to the user.
+ *
+ * ### Interface Keys
+ * This object uses a similar convention as TypeScript, where the specified key should
+ * indicate where placeholders are present by including a number in the name. This is
+ * so that translations can easily tell that they are including the appropriate placeholders.
+ * This will also be validated at runtime by the {@link Internationalization} class, but
+ * it's better to have that hint when editing as well.
+ *
+ * This interface defines the available translatable strings, and the number of placeholders
+ * that are required to use each string. Plugins may use declaration merging to add members
+ * to this interface to use TypeDoc's internationalization module.
+ *
+ * @example
+ * ```ts
+ * declare module "typedoc" {
+ *     interface TranslatableStrings {
+ *         // Define a translatable string with no arguments
+ *         plugin_msg: [];
+ *         // Define a translatable string requiring one argument
+ *         plugin_msg_0: [string];
+ *     }
+ * }
+ * ```
+ */
+export interface TranslatableStrings extends BuiltinTranslatableStringArgs {
+}
+declare const TranslatedString: unique symbol;
+export type TranslatedString = string & {
+    [TranslatedString]: true;
+};
+/**
+ * Dynamic proxy type built from {@link TranslatableStrings}
+ */
+export type TranslationProxy = {
+    [K in keyof TranslatableStrings]: (...args: TranslatableStrings[K]) => TranslatedString;
+};
+/**
+ * Simple internationalization module which supports placeholders.
+ * See {@link TranslatableStrings} for a description of how this module works and how
+ * plugins should add translations.
+ */
+export declare class Internationalization {
+    private application;
+    private allTranslations;
+    /**
+     * Proxy object which supports dynamically translating
+     * all supported keys. This is generally used rather than the translate
+     * method so that renaming a key on the `translatable` object that contains
+     * all of the default translations will automatically update usage locations.
+     */
+    proxy: TranslationProxy;
+    /**
+     * If constructed without an application, will use the default language.
+     * Intended for use in unit tests only.
+     * @internal
+     */
+    constructor(application: Application | null);
+    /**
+     * Get the translation of the specified key, replacing placeholders
+     * with the arguments specified.
+     */
+    translate<T extends keyof TranslatableStrings>(key: T, ...args: TranslatableStrings[T]): TranslatedString;
+    kindSingularString(kind: ReflectionKind): TranslatedString;
+    kindPluralString(kind: ReflectionKind): TranslatedString;
+    /**
+     * Add translations for a string which will be displayed to the user.
+     */
+    addTranslations(lang: string, translations: Partial<Record<keyof TranslatableStrings, string>>, override?: boolean): void;
+    /**
+     * Checks if we have any translations in the specified language.
+     */
+    hasTranslations(lang: string): boolean;
+    /**
+     * Gets a list of all languages with at least one translation.
+     */
+    getSupportedLanguages(): string[];
+}
+export {};

package/dist/lib/internationalization/internationalization.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Internationalization = void 0;
+const assert_1 = require("assert");
+const utils_1 = require("../utils");
+const translatable_1 = require("./translatable");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const kind_1 = require("../models/reflections/kind");
+// If we're running in ts-node, then we need the TS source rather than
+// the compiled file.
+const ext = process[Symbol.for("ts-node.register.instance")]
+    ? "cts"
+    : "cjs";
+/**
+ * Simple internationalization module which supports placeholders.
+ * See {@link TranslatableStrings} for a description of how this module works and how
+ * plugins should add translations.
+ */
+class Internationalization {
+    /**
+     * If constructed without an application, will use the default language.
+     * Intended for use in unit tests only.
+     * @internal
+     */
+    constructor(application) {
+        this.application = application;
+        this.allTranslations = new utils_1.DefaultMap((lang) => {
+            // Make sure this isn't abused to load some random file by mistake
+            (0, assert_1.ok)(/^[A-Za-z-]+$/.test(lang), "Locale names may only contain letters and dashes");
+            try {
+                return new Map(
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                Object.entries(require(`./locales/${lang}.${ext}`)));
+            }
+            catch {
+                return new Map();
+            }
+        });
+        /**
+         * Proxy object which supports dynamically translating
+         * all supported keys. This is generally used rather than the translate
+         * method so that renaming a key on the `translatable` object that contains
+         * all of the default translations will automatically update usage locations.
+         */
+        this.proxy = new Proxy(this, {
+            get(internationalization, key) {
+                return (...args) => internationalization.translate(key, ...args);
+            },
+        });
+    }
+    /**
+     * Get the translation of the specified key, replacing placeholders
+     * with the arguments specified.
+     */
+    translate(key, ...args) {
+        return (this.allTranslations.get(this.application?.lang ?? "en").get(key) ??
+            translatable_1.translatable[key] ??
+            key).replace(/\{(\d+)\}/g, (_, index) => {
+            return args[+index] ?? "(no placeholder)";
+        });
+    }
+    kindSingularString(kind) {
+        switch (kind) {
+            case kind_1.ReflectionKind.Project:
+                return this.proxy.kind_project();
+            case kind_1.ReflectionKind.Module:
+                return this.proxy.kind_module();
+            case kind_1.ReflectionKind.Namespace:
+                return this.proxy.kind_namespace();
+            case kind_1.ReflectionKind.Enum:
+                return this.proxy.kind_enum();
+            case kind_1.ReflectionKind.EnumMember:
+                return this.proxy.kind_enum_member();
+            case kind_1.ReflectionKind.Variable:
+                return this.proxy.kind_variable();
+            case kind_1.ReflectionKind.Function:
+                return this.proxy.kind_function();
+            case kind_1.ReflectionKind.Class:
+                return this.proxy.kind_class();
+            case kind_1.ReflectionKind.Interface:
+                return this.proxy.kind_interface();
+            case kind_1.ReflectionKind.Constructor:
+                return this.proxy.kind_constructor();
+            case kind_1.ReflectionKind.Property:
+                return this.proxy.kind_property();
+            case kind_1.ReflectionKind.Method:
+                return this.proxy.kind_method();
+            case kind_1.ReflectionKind.CallSignature:
+                return this.proxy.kind_call_signature();
+            case kind_1.ReflectionKind.IndexSignature:
+                return this.proxy.kind_index_signature();
+            case kind_1.ReflectionKind.ConstructorSignature:
+                return this.proxy.kind_constructor_signature();
+            case kind_1.ReflectionKind.Parameter:
+                return this.proxy.kind_parameter();
+            case kind_1.ReflectionKind.TypeLiteral:
+                return this.proxy.kind_type_literal();
+            case kind_1.ReflectionKind.TypeParameter:
+                return this.proxy.kind_type_parameter();
+            case kind_1.ReflectionKind.Accessor:
+                return this.proxy.kind_accessor();
+            case kind_1.ReflectionKind.GetSignature:
+                return this.proxy.kind_get_signature();
+            case kind_1.ReflectionKind.SetSignature:
+                return this.proxy.kind_set_signature();
+            case kind_1.ReflectionKind.TypeAlias:
+                return this.proxy.kind_type_alias();
+            case kind_1.ReflectionKind.Reference:
+                return this.proxy.kind_reference();
+            case kind_1.ReflectionKind.Document:
+                return this.proxy.kind_document();
+        }
+    }
+    kindPluralString(kind) {
+        switch (kind) {
+            case kind_1.ReflectionKind.Project:
+                return this.proxy.kind_plural_project();
+            case kind_1.ReflectionKind.Module:
+                return this.proxy.kind_plural_module();
+            case kind_1.ReflectionKind.Namespace:
+                return this.proxy.kind_plural_namespace();
+            case kind_1.ReflectionKind.Enum:
+                return this.proxy.kind_plural_enum();
+            case kind_1.ReflectionKind.EnumMember:
+                return this.proxy.kind_plural_enum_member();
+            case kind_1.ReflectionKind.Variable:
+                return this.proxy.kind_plural_variable();
+            case kind_1.ReflectionKind.Function:
+                return this.proxy.kind_plural_function();
+            case kind_1.ReflectionKind.Class:
+                return this.proxy.kind_plural_class();
+            case kind_1.ReflectionKind.Interface:
+                return this.proxy.kind_plural_interface();
+            case kind_1.ReflectionKind.Constructor:
+                return this.proxy.kind_plural_constructor();
+            case kind_1.ReflectionKind.Property:
+                return this.proxy.kind_plural_property();
+            case kind_1.ReflectionKind.Method:
+                return this.proxy.kind_plural_method();
+            case kind_1.ReflectionKind.CallSignature:
+                return this.proxy.kind_plural_call_signature();
+            case kind_1.ReflectionKind.IndexSignature:
+                return this.proxy.kind_plural_index_signature();
+            case kind_1.ReflectionKind.ConstructorSignature:
+                return this.proxy.kind_plural_constructor_signature();
+            case kind_1.ReflectionKind.Parameter:
+                return this.proxy.kind_plural_parameter();
+            case kind_1.ReflectionKind.TypeLiteral:
+                return this.proxy.kind_plural_type_literal();
+            case kind_1.ReflectionKind.TypeParameter:
+                return this.proxy.kind_plural_type_parameter();
+            case kind_1.ReflectionKind.Accessor:
+                return this.proxy.kind_plural_accessor();
+            case kind_1.ReflectionKind.GetSignature:
+                return this.proxy.kind_plural_get_signature();
+            case kind_1.ReflectionKind.SetSignature:
+                return this.proxy.kind_plural_set_signature();
+            case kind_1.ReflectionKind.TypeAlias:
+                return this.proxy.kind_plural_type_alias();
+            case kind_1.ReflectionKind.Reference:
+                return this.proxy.kind_plural_reference();
+            case kind_1.ReflectionKind.Document:
+                return this.proxy.kind_plural_document();
+        }
+    }
+    /**
+     * Add translations for a string which will be displayed to the user.
+     */
+    addTranslations(lang, translations, override = false) {
+        const target = this.allTranslations.get(lang);
+        for (const [key, val] of Object.entries(translations)) {
+            if (!target.has(key) || override) {
+                target.set(key, val);
+            }
+        }
+    }
+    /**
+     * Checks if we have any translations in the specified language.
+     */
+    hasTranslations(lang) {
+        return this.allTranslations.get(lang).size > 0;
+    }
+    /**
+     * Gets a list of all languages with at least one translation.
+     */
+    getSupportedLanguages() {
+        return (0, utils_1.unique)([
+            ...(0, fs_1.readdirSync)((0, path_1.join)(__dirname, "locales")).map((x) => x.substring(0, x.indexOf("."))),
+            ...this.allTranslations.keys(),
+        ]).sort();
+    }
+}
+exports.Internationalization = Internationalization;

package/dist/lib/internationalization/locales/en.cjs

@@ -0,0 +1,3 @@
+"use strict";
+const translatable_1 = require("../translatable");
+module.exports = translatable_1.translatable;

package/dist/lib/internationalization/locales/en.d.cts

@@ -0,0 +1,2 @@
+import { translatable } from "../translatable";
+export = translatable;

package/dist/lib/internationalization/locales/test.cjs

@@ -0,0 +1,8 @@
+"use strict";
+// This should go away once we have a second language in TypeDoc to use
+// in unit tests. It's here for now so that we have *something* to test with.
+const translatable_1 = require("../translatable");
+module.exports = (0, translatable_1.buildIncompleteTranslation)({
+    no_entry_points_to_merge: "no_entry_points_to_merge",
+    docs_generated_at_0: "docs_generated_at_0 {0}",
+});

package/dist/lib/internationalization/locales/test.d.cts

@@ -0,0 +1,5 @@
+declare const _default: {
+    no_entry_points_to_merge: string;
+    docs_generated_at_0: "docs_generated_at_0 {0}";
+};
+export = _default;