typedoc 0.26.0-beta.2 → 0.26.0-beta.4

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

@@ -1,10 +1,47 @@
 "use strict";
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GitRepository = exports.AssumedRepository = void 0;
+exports.RepositoryManager = 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 utils_1 = require("../../utils");
+const general_1 = require("../../utils/general");
+const path_1 = require("path");
+const fs_1 = require("fs");
 const TEN_MEGABYTES = 1024 * 10000;
 function git(...args) {
     return (0, child_process_1.spawnSync)("git", args, {
@@ -38,82 +75,172 @@ exports.AssumedRepository = AssumedRepository;
 /**
  * Stores data of a repository.
  */
-class GitRepository {
-    /**
-     * Create a new Repository instance.
-     *
-     * @param path  The root path of the repository.
-     */
-    constructor(path, gitRevision, urlTemplate) {
-        /**
-         * All files tracked by the repository.
-         */
-        this.files = new Set();
-        this.path = path;
-        this.gitRevision = gitRevision;
-        this.urlTemplate = urlTemplate;
-        const out = git("-C", path, "ls-files");
-        if (out.status === 0) {
-            out.stdout.split("\n").forEach((file) => {
-                if (file !== "") {
-                    this.files.add(base_path_1.BasePath.normalize(path + "/" + file));
+let GitRepository = (() => {
+    var _a;
+    let _files_decorators;
+    let _files_initializers = [];
+    let _files_extraInitializers = [];
+    return _a = class GitRepository {
+            /**
+             * Create a new Repository instance.
+             *
+             * @param path  The root path of the repository.
+             */
+            constructor(path, gitRevision, urlTemplate) {
+                /**
+                 * All files tracked by the repository.
+                 */
+                this.files = __runInitializers(this, _files_initializers, new Set());
+                this.urlTemplate = __runInitializers(this, _files_extraInitializers);
+                this.path = path;
+                this.gitRevision = gitRevision;
+                this.urlTemplate = urlTemplate;
+                const out = git("-C", path, "ls-files", "-z");
+                if (out.status === 0) {
+                    out.stdout.split("\0").forEach((file) => {
+                        if (file !== "") {
+                            this.files.add((0, utils_1.normalizePath)(path + "/" + file));
+                        }
+                    });
                 }
-            });
-        }
+            }
+            /**
+             * Get the URL of the given file on GitHub or Bitbucket.
+             *
+             * @param fileName  The file whose URL should be determined.
+             * @returns A URL pointing to the web preview of the given file or undefined.
+             */
+            getURL(fileName, line) {
+                if (!this.files.has(fileName)) {
+                    return;
+                }
+                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|gitRevision:short|path|line)\}/g, (_, key) => replacements[key]);
+            }
+            /**
+             * Try to create a new repository instance.
+             *
+             * Checks whether the given path is the root of a valid repository and if so
+             * creates a new instance of {@link GitRepository}.
+             *
+             * @param path  The potential repository root.
+             * @returns A new instance of {@link GitRepository} or undefined.
+             */
+            static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
+                gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
+                if (!gitRevision)
+                    return; // Will only happen in a repo with no commits.
+                let urlTemplate;
+                if (sourceLinkTemplate) {
+                    urlTemplate = sourceLinkTemplate;
+                }
+                else {
+                    const remotesOut = git("-C", path, "remote", "get-url", gitRemote);
+                    if (remotesOut.status === 0) {
+                        urlTemplate = guessSourceUrlTemplate(remotesOut.stdout.split("\n"));
+                    }
+                    else {
+                        logger.warn(logger.i18n.git_remote_0_not_valid(gitRemote));
+                    }
+                }
+                if (!urlTemplate)
+                    return;
+                return new _a((0, utils_1.normalizePath)(path), gitRevision, urlTemplate);
+            }
+        },
+        (() => {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _files_decorators = [general_1.NonEnumerable];
+            __esDecorate(null, null, _files_decorators, { kind: "field", name: "files", static: false, private: false, access: { has: obj => "files" in obj, get: obj => obj.files, set: (obj, value) => { obj.files = value; } }, metadata: _metadata }, _files_initializers, _files_extraInitializers);
+            if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        })(),
+        _a;
+})();
+exports.GitRepository = GitRepository;
+/**
+ * Responsible for keeping track of 0-N repositories which exist on a machine.
+ * This used to be inlined in SourcePlugin, moved out for easy unit testing.
+ *
+ * Git repositories can be nested. Files should be resolved to a repo as shown
+ * below:
+ * ```text
+ * /project
+ * /project/.git (A)
+ * /project/file.js (A)
+ * /project/folder/file.js (A)
+ * /project/sub/.git (B)
+ * /project/sub/file.js (B)
+ * ```
+ *
+ * In order words, it is not safe to assume that just because a file is within
+ * the `/project` directory, that it belongs to repo `A`. As calling git is
+ * expensive (~20-300ms depending on the machine, antivirus, etc.) we check for
+ * `.git` folders manually, and only call git if one is found.
+ *
+ * Symlinked files have the potential to further complicate this. If TypeScript's
+ * `preserveSymlinks` option is on, then this may be passed the path to a symlinked
+ * file. Unlike TypeScript, we will resolve the path, as the repo link should really
+ * point to the actual file.
+ */
+class RepositoryManager {
+    constructor(basePath, gitRevision, gitRemote, sourceLinkTemplate, disableGit, logger) {
+        this.basePath = basePath;
+        this.gitRevision = gitRevision;
+        this.gitRemote = gitRemote;
+        this.sourceLinkTemplate = sourceLinkTemplate;
+        this.disableGit = disableGit;
+        this.logger = logger;
+        this.cache = new Map();
+        this.assumedRepo = new AssumedRepository(this.basePath, this.gitRevision, this.sourceLinkTemplate);
     }
     /**
-     * Get the URL of the given file on GitHub or Bitbucket.
+     * Check whether the given file is placed inside a repository.
      *
-     * @param fileName  The file whose URL should be determined.
-     * @returns A URL pointing to the web preview of the given file or undefined.
+     * @param fileName  The name of the file a repository should be looked for.
+     * @returns The found repository info or undefined.
      */
-    getURL(fileName, line) {
-        if (!this.files.has(fileName)) {
-            return;
+    getRepository(fileName) {
+        if (this.disableGit) {
+            return this.assumedRepo;
         }
-        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|gitRevision:short|path|line)\}/g, (_, key) => replacements[key]);
+        return this.getRepositoryFolder((0, utils_1.normalizePath)((0, path_1.dirname)(fileName)));
     }
-    /**
-     * Try to create a new repository instance.
-     *
-     * Checks whether the given path is the root of a valid repository and if so
-     * creates a new instance of {@link GitRepository}.
-     *
-     * @param path  The potential repository root.
-     * @returns A new instance of {@link GitRepository} or undefined.
-     */
-    static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
-        const topLevel = git("-C", path, "rev-parse", "--show-toplevel");
-        if (topLevel.status !== 0)
-            return;
-        gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
-        if (!gitRevision)
-            return; // Will only happen in a repo with no commits.
-        let urlTemplate;
-        if (sourceLinkTemplate) {
-            urlTemplate = sourceLinkTemplate;
+    getRepositoryFolder(dir) {
+        if (this.cache.has(dir)) {
+            return this.cache.get(dir);
         }
-        else {
-            const remotesOut = git("-C", path, "remote", "get-url", gitRemote);
-            if (remotesOut.status === 0) {
-                urlTemplate = guessSourceUrlTemplate(remotesOut.stdout.split("\n"));
+        if ((0, fs_1.existsSync)((0, path_1.join)(dir, ".git"))) {
+            // This might just be a git repo, or we might be in some self-recursive symlink
+            // loop, and the repo is actually somewhere else. Ask Git where the repo actually is.
+            const repo = git("-C", dir, "rev-parse", "--show-toplevel");
+            if (repo.status === 0) {
+                const repoDir = repo.stdout.replace("\n", "");
+                // This check is only necessary if we're in a symlink loop, otherwise
+                // it will always be true.
+                if (!this.cache.has(repoDir)) {
+                    this.cache.set(repoDir, GitRepository.tryCreateRepository(repoDir, this.sourceLinkTemplate, this.gitRevision, this.gitRemote, this.logger));
+                }
+                this.cache.set(dir, this.cache.get(repoDir));
             }
             else {
-                logger.warn(logger.i18n.git_remote_0_not_valid(gitRemote));
+                // Not a git repo, probably corrupt.
+                this.cache.set(dir, undefined);
             }
         }
-        if (!urlTemplate)
-            return;
-        return new GitRepository(base_path_1.BasePath.normalize(topLevel.stdout.replace("\n", "")), gitRevision, urlTemplate);
+        else {
+            // We may be at the root of the file system, in which case there is no repo.
+            this.cache.set(dir, undefined);
+            this.cache.set(dir, this.getRepositoryFolder((0, path_1.dirname)(dir)));
+        }
+        return this.cache.get(dir);
     }
 }
-exports.GitRepository = GitRepository;
+exports.RepositoryManager = RepositoryManager;
 // Should have three capturing groups:
 // 1. hostname
 // 2. user

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

@@ -1,6 +1,7 @@
 import type { Application } from "../application";
-import { type BuiltinTranslatableStringArgs } from "./translatable";
+import { translatable, type BuiltinTranslatableStringArgs } from "./translatable";
 import { ReflectionKind } from "../models/reflections/kind";
+import { ReflectionFlag } from "../models";
 /**
  * ### What is translatable?
  * TypeDoc includes a lot of literal strings. By convention, messages which are displayed
@@ -73,9 +74,11 @@ export declare class Internationalization {
      * Get the translation of the specified key, replacing placeholders
      * with the arguments specified.
      */
-    translate<T extends keyof TranslatableStrings>(key: T, ...args: TranslatableStrings[T]): TranslatedString;
+    translate<T extends keyof typeof translatable>(key: T, ...args: TranslatableStrings[T]): TranslatedString;
     kindSingularString(kind: ReflectionKind): TranslatedString;
     kindPluralString(kind: ReflectionKind): TranslatedString;
+    flagString(flag: ReflectionFlag): TranslatedString;
+    translateTagName(tag: `@${string}`): TranslatedString;
     /**
      * Add translations for a string which will be displayed to the user.
      */

package/dist/lib/internationalization/internationalization.js

@@ -7,9 +7,9 @@ const translatable_1 = require("./translatable");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const kind_1 = require("../models/reflections/kind");
+const models_1 = require("../models");
 // If we're running in ts-node, then we need the TS source rather than
 // the compiled file.
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 const ext = process[Symbol.for("ts-node.register.instance")]
     ? "cts"
     : "cjs";
@@ -164,6 +164,47 @@ class Internationalization {
                 return this.proxy.kind_plural_document();
         }
     }
+    flagString(flag) {
+        switch (flag) {
+            case models_1.ReflectionFlag.None:
+                throw new Error("Should be unreachable");
+            case models_1.ReflectionFlag.Private:
+                return this.proxy.flag_private();
+            case models_1.ReflectionFlag.Protected:
+                return this.proxy.flag_protected();
+            case models_1.ReflectionFlag.Public:
+                return this.proxy.flag_public();
+            case models_1.ReflectionFlag.Static:
+                return this.proxy.flag_static();
+            case models_1.ReflectionFlag.External:
+                return this.proxy.flag_external();
+            case models_1.ReflectionFlag.Optional:
+                return this.proxy.flag_optional();
+            case models_1.ReflectionFlag.Rest:
+                return this.proxy.flag_rest();
+            case models_1.ReflectionFlag.Abstract:
+                return this.proxy.flag_abstract();
+            case models_1.ReflectionFlag.Const:
+                return this.proxy.flag_const();
+            case models_1.ReflectionFlag.Readonly:
+                return this.proxy.flag_readonly();
+            case models_1.ReflectionFlag.Inherited:
+                return this.proxy.flag_inherited();
+        }
+    }
+    translateTagName(tag) {
+        const tagName = tag.substring(1);
+        const translations = this.allTranslations.get(this.application?.lang ?? "en");
+        if (translations.has(`tag_${tagName}`)) {
+            return translations.get(`tag_${tagName}`);
+        }
+        // In English, the tag names are the translated names, once turned
+        // into title case.
+        return (tagName.substring(0, 1).toUpperCase() +
+            tagName
+                .substring(1)
+                .replace(/[a-z][A-Z]/g, (x) => `${x[0]} ${x[1]}`));
+    }
     /**
      * Add translations for a string which will be displayed to the user.
      */