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

package/README.md

@@ -2,8 +2,6 @@
 
 Documentation generator for TypeScript projects.
 
-Plugins: [plugins](./internal-docs/plugins.md)
-
 [![CI](https://github.com/TypeStrong/typedoc/workflows/CI/badge.svg)](https://github.com/TypeStrong/typedoc/actions)
 [![NPM Version](https://img.shields.io/npm/v/typedoc?color=33cd56&logo=npm)](https://www.npmjs.com/package/typedoc)
 

package/dist/lib/application.d.ts

@@ -22,6 +22,11 @@ export declare function createAppForTesting(): Application;
  *
  * Both the {@link Converter} and the {@link Renderer} emit a series of events while processing the project.
  * Subscribe to these Events to control the application flow or alter the output.
+ *
+ * @remarks
+ *
+ * Access to an Application instance can be retrieved with {@link Application.bootstrap} or
+ * {@link Application.bootstrapWithPlugins}. It can not be constructed manually.
  */
 export declare class Application extends ChildableComponent<Application, AbstractComponent<Application>> {
     /**
@@ -66,7 +71,7 @@ export declare class Application extends ChildableComponent<Application, Abstrac
     /**
      * The version number of TypeDoc.
      */
-    static VERSION: string;
+    static readonly VERSION: string;
     /**
      * Emitted after plugins have been loaded and options have been read, but before they have been frozen.
      * The listener will be given an instance of {@link Application}.

package/dist/lib/application.js

@@ -130,6 +130,11 @@ const DEFAULT_READERS = [
  *
  * Both the {@link Converter} and the {@link Renderer} emit a series of events while processing the project.
  * Subscribe to these Events to control the application flow or alter the output.
+ *
+ * @remarks
+ *
+ * Access to an Application instance can be retrieved with {@link Application.bootstrap} or
+ * {@link Application.bootstrapWithPlugins}. It can not be constructed manually.
  */
 let Application = (() => {
     var _Application_lang_accessor_storage, _Application_skipErrorChecking_accessor_storage, _Application_entryPointStrategy_accessor_storage, _Application_entryPoints_accessor_storage;
@@ -259,6 +264,11 @@ let Application = (() => {
                         .join("\n\t")));
                 this.logger.info("You can define/override local locales with the `locales` option, or contribute them to TypeDoc!");
             }
+            if (this.options.getValue("useHostedBaseUrlForAbsoluteLinks") &&
+                !this.options.getValue("hostedBaseUrl")) {
+                this.logger.warn(this.i18n.useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl());
+                this.options.setValue("useHostedBaseUrlForAbsoluteLinks", false);
+            }
         }
         setOptions(options, reportErrors = true) {
             for (const [key, val] of Object.entries(options)) {

package/dist/lib/cli.js

@@ -49,6 +49,7 @@ async function main() {
         const exitCode = await run(app);
         if (exitCode !== ExitCodes.Watching) {
             app.logger.verbose(`Full run took ${Date.now() - start}ms`);
+            logRunSummary(app.logger);
             process.exit(exitCode);
         }
     }
@@ -83,6 +84,7 @@ async function run(app) {
     }
     if (app.options.getValue("watch")) {
         app.convertAndWatch(async (project) => {
+            app.validate(project);
             const json = app.options.getValue("json");
             if (!json || app.options.isSet("out")) {
                 await app.generateDocs(project, app.options.getValue("out"));
@@ -130,3 +132,15 @@ async function run(app) {
     }
     return ExitCodes.Ok;
 }
+/**
+ * Generate a string with the number of errors and warnings found.
+ */
+function logRunSummary(logger) {
+    const { errorCount, warningCount } = logger;
+    if (errorCount) {
+        logger.error(logger.i18n.found_0_errors_and_1_warnings(errorCount.toString(), warningCount.toString()));
+    }
+    else if (warningCount) {
+        logger.warn(logger.i18n.found_0_errors_and_1_warnings(errorCount.toString(), warningCount.toString()));
+    }
+}

package/dist/lib/converter/comments/discovery.js

@@ -284,7 +284,6 @@ function getRootModuleDeclaration(node) {
 }
 function declarationToCommentNode(node) {
     // ts.SourceFile is a counterexample
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (!node.parent)
         return node;
     // const abc = 123

package/dist/lib/converter/comments/index.d.ts

@@ -11,7 +11,7 @@ export interface CommentParserConfig {
 }
 export declare function clearCommentCache(): void;
 export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
-export declare function getNodeComment(node: ts.Node, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getNodeComment(node: ts.Node, moduleComment: boolean, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
 export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
 export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
 export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;

package/dist/lib/converter/comments/index.js

@@ -58,6 +58,9 @@ function getCommentWithCache(discovered, config, logger, checker, files) {
 }
 function getCommentImpl(commentSource, config, logger, moduleComment, checker, files) {
     const comment = getCommentWithCache(commentSource, config, logger, checker, files);
+    if (comment?.getTag("@import") || comment?.getTag("@license")) {
+        return;
+    }
     if (moduleComment && comment) {
         // Module comment, make sure it is tagged with @packageDocumentation or @module.
         // If it isn't then the comment applies to the first statement in the file, so throw it away.
@@ -97,8 +100,8 @@ function getComment(symbol, kind, config, logger, commentStyle, checker, files)
     }
     return comment;
 }
-function getNodeComment(node, kind, config, logger, commentStyle, checker, files) {
-    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, kind === models_1.ReflectionKind.Module, checker, files);
+function getNodeComment(node, moduleComment, config, logger, commentStyle, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, moduleComment, checker, files);
 }
 function getFileComment(file, config, logger, commentStyle, checker, files) {
     for (const commentSource of (0, discovery_1.discoverFileComments)(file, commentStyle)) {

package/dist/lib/converter/comments/textParser.d.ts

@@ -12,8 +12,5 @@ import { type Token } from "./lexer";
 /**
  * Look for relative links within a piece of text and add them to the {@link FileRegistry}
  * so that they can be correctly resolved during rendering.
- *
- * TODO: We also handle `<a>` and `<img>` tags with relative targets here.
- *
  */
 export declare function textContent(sourcePath: string, token: Token, i18n: TranslationProxy, warning: (msg: TranslatedString, token: Token) => void, outContent: CommentDisplayPart[], files: FileRegistry, atNewLine: boolean): void;

package/dist/lib/converter/comments/textParser.js

@@ -4,15 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.textContent = textContent;
+const html_1 = require("../../utils/html");
 const lexer_1 = require("./lexer");
 const markdown_it_1 = __importDefault(require("markdown-it"));
 const MdHelpers = new markdown_it_1.default().helpers;
 /**
  * Look for relative links within a piece of text and add them to the {@link FileRegistry}
  * so that they can be correctly resolved during rendering.
- *
- * TODO: We also handle `<a>` and `<img>` tags with relative targets here.
- *
  */
 function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine) {
     let lastPartEnd = 0;
@@ -56,6 +54,11 @@ function textContent(sourcePath, token, i18n, warning, outContent, files, atNewL
             addRef(reference);
             continue;
         }
+        const tagLink = checkTagLink(data);
+        if (tagLink) {
+            addRef(tagLink);
+            continue;
+        }
         ++data.pos;
     }
     if (lastPartEnd !== token.text.length) {
@@ -138,6 +141,39 @@ function checkReference(data) {
         }
     }
 }
+/**
+ * Looks for `<a href="./relative">` and `<img src="./relative">`
+ */
+function checkTagLink(data) {
+    const { pos, token } = data;
+    if (token.text.startsWith("<img ", pos)) {
+        data.pos += 4;
+        return checkAttribute(data, "src");
+    }
+    if (token.text.startsWith("<a ", pos)) {
+        data.pos += 3;
+        return checkAttribute(data, "href");
+    }
+}
+function checkAttribute(data, attr) {
+    const parser = new html_1.HtmlAttributeParser(data.token.text, data.pos);
+    while (parser.state !== html_1.ParserState.END) {
+        if (parser.state === html_1.ParserState.BeforeAttributeValue &&
+            parser.currentAttributeName === attr) {
+            parser.step();
+            if (isRelativeLink(parser.currentAttributeValue)) {
+                data.pos = parser.pos;
+                return {
+                    pos: parser.currentAttributeValueStart,
+                    end: parser.currentAttributeValueEnd,
+                    target: data.files.register(data.sourcePath, parser.currentAttributeValue),
+                };
+            }
+            return;
+        }
+        parser.step();
+    }
+}
 function isRelativeLink(link) {
     return !/^[a-z]+:\/\/|^\/|^[a-z]:\\/i.test(link);
 }

package/dist/lib/converter/context.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { type Reflection, type ProjectReflection, DeclarationReflection, ReflectionKind, type DocumentReflection } from "../models/index";
+import { type Reflection, type ProjectReflection, DeclarationReflection, type DocumentReflection, ReflectionKind } from "../models/index";
 import type { Converter } from "./converter";
 import type { TranslationProxy } from "../internationalization/internationalization";
 /**
@@ -84,7 +84,7 @@ export declare class Context {
     /** @internal */
     setActiveProgram(program: ts.Program | undefined): void;
     getComment(symbol: ts.Symbol, kind: ReflectionKind): import("../models/index").Comment | undefined;
-    getNodeComment(node: ts.Node, kind: ReflectionKind): import("../models/index").Comment | undefined;
+    getNodeComment(node: ts.Node, moduleComment: boolean): import("../models/index").Comment | undefined;
     getFileComment(node: ts.SourceFile): import("../models/index").Comment | undefined;
     getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): import("../models/index").Comment | undefined;
     getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): import("../models/index").Comment | undefined;

package/dist/lib/converter/context.js

@@ -73,12 +73,10 @@ class Context {
             if (node.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.symbol);
                 // The TS types lie due to ts.SourceFile
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             }
             else if (node.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.symbol);
                 // The TS types lie due to ts.SourceFile
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             }
             else if (node.parent?.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.parent.symbol);
@@ -190,8 +188,8 @@ class Context {
     getComment(symbol, kind) {
         return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
-    getNodeComment(node, kind) {
-        return (0, comments_1.getNodeComment)(node, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+    getNodeComment(node, moduleComment) {
+        return (0, comments_1.getNodeComment)(node, moduleComment, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     getFileComment(node) {
         return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);

package/dist/lib/converter/converter.d.ts

@@ -177,5 +177,6 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /** @internal */
     isExternal(symbol: ts.Symbol): boolean;
     processDocumentTags(reflection: Reflection, parent: ContainerReflection): void;
+    private addDocument;
     private _buildCommentParserConfig;
 }

package/dist/lib/converter/converter.js

@@ -221,11 +221,15 @@ let Converter = (() => {
         addProjectDocuments(project) {
             const projectDocuments = (0, utils_1.getDocumentEntryPoints)(this.application.logger, this.application.options);
             for (const { displayName, path } of projectDocuments) {
-                const file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
-                const { content, frontmatter } = this.parseRawComment(file, project.files);
-                const docRefl = new index_1.DocumentReflection(displayName, project, content, frontmatter);
-                project.addChild(docRefl);
-                project.registerReflection(docRefl, undefined, path);
+                let file;
+                try {
+                    file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_project_document(path));
+                    continue;
+                }
+                this.addDocument(project, file, displayName);
             }
         }
         /** @internal */
@@ -407,11 +411,56 @@ let Converter = (() => {
                         this.application.logger.warn(this.application.logger.i18n.failed_to_read_0_when_processing_document_tag_in_1((0, paths_1.nicePath)(path), (0, paths_1.nicePath)(reflection.comment.sourcePath)));
                         continue;
                     }
-                    const { content, frontmatter } = this.parseRawComment(file, reflection.project.files);
-                    const docRefl = new index_1.DocumentReflection((0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""), parent, content, frontmatter);
-                    parent.addChild(docRefl);
-                    parent.project.registerReflection(docRefl, undefined, file.fileName);
+                    this.addDocument(parent, file, (0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""));
+                }
+            }
+        }
+        addDocument(parent, file, displayName) {
+            const { content, frontmatter } = this.parseRawComment(file, parent.project.files);
+            const children = frontmatter["children"];
+            delete frontmatter["children"];
+            const docRefl = new index_1.DocumentReflection(displayName, parent, content, frontmatter);
+            parent.addChild(docRefl);
+            parent.project.registerReflection(docRefl, undefined, file.fileName);
+            const childrenToAdd = [];
+            if (children && typeof children === "object") {
+                if (Array.isArray(children)) {
+                    for (const child of children) {
+                        if (typeof child === "string") {
+                            childrenToAdd.push([
+                                (0, path_1.basename)(child).replace(/\.[^.]+$/, ""),
+                                child,
+                            ]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+                else {
+                    for (const [name, path] of Object.entries(children)) {
+                        if (typeof path === "string") {
+                            childrenToAdd.push([name, path]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+            }
+            for (const [displayName, path] of childrenToAdd) {
+                const absPath = (0, path_1.resolve)((0, path_1.dirname)(file.fileName), path);
+                let childFile;
+                try {
+                    childFile = new utils_1.MinimalSourceFile((0, utils_1.readFile)(absPath), absPath);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_document_child_in_1(path, (0, paths_1.nicePath)(file.fileName)));
+                    continue;
                 }
+                this.addDocument(docRefl, childFile, displayName);
             }
         }
         _buildCommentParserConfig() {

package/dist/lib/converter/factories/index-signature.js

@@ -18,7 +18,7 @@ function convertIndexSignatures(context, symbol) {
         const param = indexDeclaration.parameters[0];
         (0, assert_1.default)(param && typescript_1.default.isParameter(param));
         const index = new models_1.SignatureReflection("__index", models_1.ReflectionKind.IndexSignature, context.scope);
-        index.comment = context.getNodeComment(indexDeclaration, index.kind);
+        index.comment = context.getNodeComment(indexDeclaration, false);
         index.parameters = [
             new models_1.ParameterReflection(param.name.getText(), models_1.ReflectionKind.Parameter, index),
         ];

package/dist/lib/converter/plugins/ImplementsPlugin.js

@@ -292,7 +292,7 @@ function findProperty(reflection, parent) {
             : prop.name === reflection.name;
     });
 }
-function createLink(context, reflection, clause, expr, symbol, isOverwrite) {
+function createLink(context, reflection, clause, expr, symbol, isInherit) {
     const project = context.project;
     const name = `${expr.expression.getText()}.${(0, utils_1.getHumanName)(symbol.name)}`;
     link(reflection);
@@ -313,7 +313,8 @@ function createLink(context, reflection, clause, expr, symbol, isOverwrite) {
             target.implementationOf ??= types_1.ReferenceType.createBrokenReference(name, project);
             return;
         }
-        if (isOverwrite) {
+        if (isInherit) {
+            target.setFlag(index_1.ReflectionFlag.Inherited);
             target.inheritedFrom ??= types_1.ReferenceType.createBrokenReference(name, project);
         }
         else {

package/dist/lib/converter/plugins/LinkResolverPlugin.js

@@ -86,6 +86,13 @@ let LinkResolverPlugin = (() => {
                 if (reflection.comment) {
                     this.owner.resolveLinks(reflection.comment, reflection);
                 }
+                if (reflection.isDeclaration()) {
+                    reflection.type?.visit((0, models_1.makeRecursiveVisitor)({
+                        union: (type) => {
+                            type.elementSummaries = type.elementSummaries?.map((parts) => this.owner.resolveLinks(parts, reflection));
+                        },
+                    }));
+                }
                 if (reflection instanceof models_1.DeclarationReflection &&
                     reflection.readme) {
                     reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);

package/dist/lib/converter/plugins/SourcePlugin.d.ts

@@ -13,14 +13,7 @@ export declare class SourcePlugin extends ConverterComponent {
      * All file names to find the base path from.
      */
     private fileNames;
-    /**
-     * List of known repositories.
-     */
-    private repositories;
-    /**
-     * List of paths known to be not under git control.
-     */
-    private ignoredPaths;
+    private repositories?;
     /**
      * Create a new SourceHandler instance.
      */
@@ -42,11 +35,4 @@ export declare class SourcePlugin extends ConverterComponent {
      * @param context  The context object describing the current state the converter is in.
      */
     private onBeginResolve;
-    /**
-     * Check whether the given file is placed inside a repository.
-     *
-     * @param fileName  The name of the file a repository should be looked for.
-     * @returns The found repository info or undefined.
-     */
-    private getRepository;
 }

package/dist/lib/converter/plugins/SourcePlugin.js

@@ -62,7 +62,6 @@ const nodes_1 = require("../utils/nodes");
 const path_1 = require("path");
 const models_1 = require("../../models");
 const repository_1 = require("../utils/repository");
-const base_path_1 = require("../utils/base-path");
 /**
  * A handler that attaches source file information to reflections.
  */
@@ -104,14 +103,6 @@ let SourcePlugin = (() => {
              * All file names to find the base path from.
              */
             this.fileNames = (__runInitializers(this, _basePath_extraInitializers), new Set());
-            /**
-             * List of known repositories.
-             */
-            this.repositories = {};
-            /**
-             * List of paths known to be not under git control.
-             */
-            this.ignoredPaths = new Set();
         }
         get disableSources() { return __classPrivateFieldGet(this, _SourcePlugin_disableSources_accessor_storage, "f"); }
         set disableSources(value) { __classPrivateFieldSet(this, _SourcePlugin_disableSources_accessor_storage, value, "f"); }
@@ -154,7 +145,7 @@ let SourcePlugin = (() => {
             const symbol = reflection.project.getSymbolFromReflection(reflection);
             for (const node of symbol?.declarations || []) {
                 const sourceFile = node.getSourceFile();
-                const fileName = base_path_1.BasePath.normalize(sourceFile.fileName);
+                const fileName = (0, utils_1.normalizePath)(sourceFile.fileName);
                 this.fileNames.add(fileName);
                 let position;
                 if (typescript_1.default.isSourceFile(node)) {
@@ -171,7 +162,7 @@ let SourcePlugin = (() => {
             if (this.disableSources || !sig)
                 return;
             const sourceFile = sig.getSourceFile();
-            const fileName = base_path_1.BasePath.normalize(sourceFile.fileName);
+            const fileName = (0, utils_1.normalizePath)(sourceFile.fileName);
             this.fileNames.add(fileName);
             const position = typescript_1.default.getLineAndCharacterOfPosition(sourceFile, getLocationNode(sig).getStart());
             reflection.sources ||= [];
@@ -195,6 +186,7 @@ let SourcePlugin = (() => {
                 this.application.logger.warn(context.i18n.disable_git_set_and_git_revision_used());
             }
             const basePath = this.basePath || (0, utils_1.getCommonDirectory)([...this.fileNames]);
+            this.repositories ||= new repository_1.RepositoryManager(basePath, this.gitRevision, this.gitRemote, this.sourceLinkTemplate, this.disableGit, this.application.logger);
             for (const id in context.project.reflections) {
                 const refl = context.project.reflections[id];
                 if (!(refl instanceof index_1.DeclarationReflection ||
@@ -206,46 +198,13 @@ let SourcePlugin = (() => {
                 }
                 for (const source of refl.sources || []) {
                     if (this.disableGit || (0, repository_1.gitIsInstalled)()) {
-                        const repo = this.getRepository(basePath, source.fullFileName);
+                        const repo = this.repositories.getRepository(source.fullFileName);
                         source.url = repo?.getURL(source.fullFileName, source.line);
                     }
                     source.fileName = (0, utils_1.normalizePath)((0, path_1.relative)(basePath, source.fullFileName));
                 }
             }
         }
-        /**
-         * Check whether the given file is placed inside a repository.
-         *
-         * @param fileName  The name of the file a repository should be looked for.
-         * @returns The found repository info or undefined.
-         */
-        getRepository(basePath, fileName) {
-            if (this.disableGit) {
-                return new repository_1.AssumedRepository(basePath, this.gitRevision, this.sourceLinkTemplate);
-            }
-            // Check for known non-repositories
-            const dirName = (0, path_1.dirname)(fileName);
-            const segments = dirName.split("/");
-            for (let i = segments.length; i > 0; i--) {
-                if (this.ignoredPaths.has(segments.slice(0, i).join("/"))) {
-                    return;
-                }
-            }
-            // Check for known repositories
-            for (const path of Object.keys(this.repositories)) {
-                if (fileName.toLowerCase().startsWith(path)) {
-                    return this.repositories[path];
-                }
-            }
-            // Try to create a new repository
-            const repository = repository_1.GitRepository.tryCreateRepository(dirName, this.sourceLinkTemplate, this.gitRevision, this.gitRemote, this.application.logger);
-            if (repository) {
-                this.repositories[repository.path.toLowerCase()] = repository;
-                return repository;
-            }
-            // No repository found, add path to ignored paths
-            this.ignoredPaths.add(dirName);
-        }
     };
     _SourcePlugin_disableSources_accessor_storage = new WeakMap();
     _SourcePlugin_gitRevision_accessor_storage = new WeakMap();

package/dist/lib/converter/symbols.js

@@ -198,6 +198,9 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         }
         const reflection = context.createDeclarationReflection(models_1.ReflectionKind.TypeAlias, symbol, exportSymbol);
         reflection.type = context.converter.convertType(context.withScope(reflection), declaration.type);
+        if (reflection.type.type === "union") {
+            attachUnionComments(context, declaration, reflection.type);
+        }
         context.finalizeDeclarationReflection(reflection);
         // Do this after finalization so that the CommentPlugin can get @typeParam tags
         // from the parent comment. Ugly, but works for now. Should be cleaned up eventually.
@@ -211,6 +214,25 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         (0, jsdoc_1.convertJsDocCallback)(context, symbol, declaration, exportSymbol);
     }
 }
+function attachUnionComments(context, declaration, union) {
+    const list = declaration.type.getChildAt(0);
+    if (list.kind !== typescript_1.default.SyntaxKind.SyntaxList)
+        return;
+    let unionIndex = 0;
+    for (const child of list.getChildren()) {
+        const comment = context.getNodeComment(child, false);
+        if (comment?.modifierTags.size || comment?.blockTags.length) {
+            context.logger.warn(context.logger.i18n.comment_for_0_should_not_contain_block_or_modifier_tags(`${context.scope.getFriendlyFullName()}.${unionIndex}`), child);
+        }
+        if (comment) {
+            union.elementSummaries ||= Array.from({ length: union.types.length }, () => []);
+            union.elementSummaries[unionIndex] = comment.summary;
+        }
+        if (child.kind !== typescript_1.default.SyntaxKind.BarToken) {
+            ++unionIndex;
+        }
+    }
+}
 function convertTypeAliasAsInterface(context, symbol, exportSymbol, declaration) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Interface, symbol, exportSymbol);
     context.finalizeDeclarationReflection(reflection);

package/dist/lib/converter/types.js

@@ -53,7 +53,6 @@ function loadConverters() {
         jsDocNonNullableTypeConverter,
     ]) {
         for (const key of actor.kind) {
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             if (key === undefined) {
                 // Might happen if running on an older TS version.
                 continue;
@@ -672,6 +671,7 @@ const unionConverter = {
     },
     convertType(context, type) {
         const types = type.types.map((type) => convertType(context, type));
+        normalizeUnion(types);
         sortLiteralUnion(types);
         return new models_1.UnionType(types);
     },
@@ -735,3 +735,22 @@ function sortLiteralUnion(types) {
         return aLit.value - bLit.value;
     });
 }
+function normalizeUnion(types) {
+    let trueIndex = -1;
+    let falseIndex = -1;
+    for (let i = 0; i < types.length && (trueIndex === -1 || falseIndex === -1); i++) {
+        const t = types[i];
+        if (t instanceof models_1.LiteralType) {
+            if (t.value === true) {
+                trueIndex = i;
+            }
+            if (t.value === false) {
+                falseIndex = i;
+            }
+        }
+    }
+    if (trueIndex !== -1 && falseIndex !== -1) {
+        types.splice(Math.max(trueIndex, falseIndex), 1);
+        types.splice(Math.min(trueIndex, falseIndex), 1, new models_1.IntrinsicType("boolean"));
+    }
+}

package/dist/lib/converter/utils/repository.d.ts

@@ -1,6 +1,7 @@
-import type { Logger } from "../../utils";
+import { type Logger } from "../../utils";
 export declare function gitIsInstalled(): boolean;
 export interface Repository {
+    readonly path: string;
     getURL(fileName: string, line: number): string | undefined;
 }
 export declare class AssumedRepository implements Repository {
@@ -48,4 +49,48 @@ export declare class GitRepository implements Repository {
      */
     static tryCreateRepository(path: string, sourceLinkTemplate: string, gitRevision: string, gitRemote: string, logger: Logger): GitRepository | undefined;
 }
+/**
+ * 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.
+ */
+export declare class RepositoryManager {
+    private basePath;
+    private gitRevision;
+    private gitRemote;
+    private sourceLinkTemplate;
+    private disableGit;
+    private logger;
+    private cache;
+    private assumedRepo;
+    constructor(basePath: string, gitRevision: string, gitRemote: string, sourceLinkTemplate: string, disableGit: boolean, logger: Logger);
+    /**
+     * Check whether the given file is placed inside a repository.
+     *
+     * @param fileName  The name of the file a repository should be looked for.
+     * @returns The found repository info or undefined.
+     */
+    getRepository(fileName: string): Repository | undefined;
+    private getRepositoryFolder;
+}
 export declare function guessSourceUrlTemplate(remotes: string[]): string | undefined;