Support relative paths, mostly?

Author: Gerrit0

README.md

@@ -2,6 +2,8 @@
 
 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)
 

scripts/rebuild_specs.js

@@ -106,6 +106,7 @@ function rebuildConverterTests(app, dirs) {
         for (const [file, before, after] of conversions) {
             const out = path.join(fullPath, `${file}.json`);
             if (fs.existsSync(out)) {
+                app.media = new td.ValidatingMediaRegistry();
                 td.resetReflectionID();
                 before(app);
                 const entry = getExpandedEntryPointsForPaths(

src/lib/application.ts

@@ -47,6 +47,7 @@ import {
     type TranslatedString,
 } from "./internationalization/internationalization";
 import { loadShikiMetadata } from "./utils/highlighter";
+import { ValidatingMediaRegistry, MediaRegistry } from "./models/MediaRegistry";
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json") as {
@@ -62,7 +63,9 @@ const DETECTOR = Symbol();
 
 export function createAppForTesting(): Application {
     // @ts-expect-error private constructor
-    return new Application(DETECTOR);
+    const app: Application = new Application(DETECTOR);
+    app.media = new MediaRegistry();
+    return app;
 }
 
 const DEFAULT_READERS = [
@@ -127,6 +130,8 @@ export class Application extends ChildableComponent<
 
     options = new Options(this.i18n);
 
+    media: MediaRegistry = new ValidatingMediaRegistry();
+
     /** @internal */
     @Option("lang")
     accessor lang!: string;
@@ -687,6 +692,8 @@ export class Application extends ChildableComponent<
         const result = this.deserializer.reviveProjects(
             this.options.getValue("name") || "Documentation",
             projects,
+            process.cwd(),
+            this.media,
         );
         this.trigger(ApplicationEvents.REVIVE, result);
         return result;
@@ -734,6 +741,8 @@ export class Application extends ChildableComponent<
         const result = this.deserializer.reviveProjects(
             this.options.getValue("name"),
             jsonProjects,
+            process.cwd(),
+            this.media,
         );
         this.logger.verbose(`Reviving projects took ${Date.now() - start}ms`);
 

src/lib/converter/comments/parser.ts

@@ -125,6 +125,7 @@ export function parseCommentString(
     config: CommentParserConfig,
     file: MinimalSourceFile,
     logger: Logger,
+    media: MediaRegistry,
 ) {
     const suppressWarningsConfig: CommentParserConfig = {
         ...config,
@@ -139,6 +140,7 @@ export function parseCommentString(
     const content: CommentDisplayPart[] = [];
     const lexer = makeLookaheadGenerator(tokens);
 
+    let atNewLine = false;
     while (!lexer.done()) {
         let consume = true;
         const next = lexer.peek();
@@ -152,7 +154,15 @@ export function parseCommentString(
             case TokenSyntaxKind.Text:
             case TokenSyntaxKind.Tag:
             case TokenSyntaxKind.CloseBrace:
-                content.push({ kind: "text", text: next.text });
+                textContent(
+                    file.fileName,
+                    next,
+                    logger.i18n,
+                    (msg, token) => logger.warn(msg, token.pos, file),
+                    content,
+                    media,
+                    atNewLine,
+                );
                 break;
 
             case TokenSyntaxKind.Code:
@@ -174,6 +184,7 @@ export function parseCommentString(
                 assertNever(next.kind);
         }
 
+        atNewLine = next.kind === TokenSyntaxKind.NewLine;
         if (consume) {
             lexer.take();
         }
@@ -573,7 +584,7 @@ function blockContent(
 
             case TokenSyntaxKind.Text:
                 textContent(
-                    comment,
+                    comment.sourcePath!,
                     next,
                     i18n,
                     warning,

src/lib/converter/comments/textParser.ts

@@ -6,15 +6,15 @@
  * @module
  */
 import { TranslationProxy, TranslatedString } from "../../internationalization";
-import { Comment, CommentDisplayPart } from "../../models";
+import type { CommentDisplayPart } from "../../models";
 import { MediaRegistry } from "../../models/MediaRegistry";
-import { Token } from "./lexer";
+import { Token, TokenSyntaxKind } from "./lexer";
 
 import MarkdownIt from "markdown-it";
 const MdHelpers = new MarkdownIt().helpers;
 
 interface TextParserData {
-    comment: Comment;
+    sourcePath: string;
     token: Token;
     pos: number;
     i18n: TranslationProxy;
@@ -26,7 +26,8 @@ interface TextParserData {
 interface RelativeLink {
     pos: number;
     end: number;
-    target: number;
+    /** May be undefined if the registry can't find this file */
+    target: number | undefined;
 }
 
 /**
@@ -37,7 +38,7 @@ interface RelativeLink {
  *
  */
 export function textContent(
-    comment: Comment,
+    sourcePath: string,
     token: Token,
     i18n: TranslationProxy,
     warning: (msg: TranslatedString, token: Token) => void,
@@ -47,7 +48,7 @@ export function textContent(
 ) {
     let lastPartEnd = 0;
     const data: TextParserData = {
-        comment,
+        sourcePath,
         token,
         pos: 0,
         i18n,
@@ -67,7 +68,19 @@ export function textContent(
             target: ref.target,
         });
         lastPartEnd = ref.end;
-        data.pos = lastPartEnd;
+        data.pos = ref.end;
+        if (!ref.target) {
+            warning(
+                i18n.relative_path_0_does_not_exist(
+                    token.text.slice(ref.pos, ref.end),
+                ),
+                {
+                    kind: TokenSyntaxKind.Text,
+                    pos: ref.pos,
+                    text: token.text.slice(ref.pos, ref.end),
+                },
+            );
+        }
     }
 
     while (data.pos < token.text.length) {
@@ -103,7 +116,7 @@ export function textContent(
  *
  */
 function checkMarkdownLink(data: TextParserData): RelativeLink | undefined {
-    const { token, comment, media } = data;
+    const { token, sourcePath, media } = data;
 
     if (token.text[data.pos] === "[") {
         const labelEnd = findLabelEnd(token.text, data.pos + 1);
@@ -125,7 +138,7 @@ function checkMarkdownLink(data: TextParserData): RelativeLink | undefined {
                     return {
                         pos: labelEnd + 2,
                         end: link.pos,
-                        target: media.register(comment.sourcePath!, link.str),
+                        target: media.register(sourcePath, link.str),
                     };
                 }
 
@@ -146,7 +159,7 @@ function checkMarkdownLink(data: TextParserData): RelativeLink | undefined {
  * separating it from an above paragraph. For a first cut, this is good enough.
  */
 function checkReference(data: TextParserData): RelativeLink | undefined {
-    const { atNewLine, pos, token, media, comment } = data;
+    const { atNewLine, pos, token, media, sourcePath } = data;
 
     if (atNewLine) {
         let lookahead = pos;
@@ -177,10 +190,7 @@ function checkReference(data: TextParserData): RelativeLink | undefined {
                         return {
                             pos: lookahead,
                             end: link.pos,
-                            target: media.register(
-                                comment.sourcePath!,
-                                link.str,
-                            ),
+                            target: media.register(sourcePath, link.str),
                         };
                     }
 

src/lib/converter/context.ts

@@ -222,7 +222,13 @@ export class Context {
         if (exportSymbol) {
             this.registerReflection(reflection, exportSymbol);
         }
-        this.registerReflection(reflection, symbol);
+
+        const path = reflection.kindOf(
+            ReflectionKind.Namespace | ReflectionKind.Module,
+        )
+            ? symbol?.declarations?.find(ts.isSourceFile)?.fileName
+            : undefined;
+        this.project.registerReflection(reflection, symbol, path);
     }
 
     finalizeDeclarationReflection(reflection: DeclarationReflection) {
@@ -255,7 +261,7 @@ export class Context {
      * @param symbol  The symbol the given reflection was resolved from.
      */
     registerReflection(reflection: Reflection, symbol: ts.Symbol | undefined) {
-        this.project.registerReflection(reflection, symbol);
+        this.project.registerReflection(reflection, symbol, void 0);
     }
 
     /**

src/lib/converter/converter.ts

@@ -47,6 +47,7 @@ import {
     type DeclarationReference,
 } from "./comments/declarationReference";
 import { basename, dirname, resolve } from "path";
+import { MediaRegistry } from "../models/MediaRegistry";
 
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
@@ -243,6 +244,7 @@ export class Converter extends ChildableComponent<
 
         const project = new ProjectReflection(
             this.application.options.getValue("name"),
+            this.application.media,
         );
         const context = new Context(this, programs, project);
 
@@ -266,15 +268,18 @@ export class Converter extends ChildableComponent<
         );
         for (const { displayName, path } of projectDocuments) {
             const file = new MinimalSourceFile(readFile(path), path);
-            const { content, frontmatter } = this.parseRawComment(file);
+            const { content, frontmatter } = this.parseRawComment(
+                file,
+                project.media,
+            );
             const docRefl = new DocumentReflection(
                 displayName,
                 project,
                 content,
                 frontmatter,
             );
             project.addChild(docRefl);
-            project.registerReflection(docRefl);
+            project.registerReflection(docRefl, undefined, path);
         }
     }
 
@@ -304,12 +309,13 @@ export class Converter extends ChildableComponent<
     /**
      * Parse the given file into a comment. Intended to be used with markdown files.
      */
-    parseRawComment(file: MinimalSourceFile) {
+    parseRawComment(file: MinimalSourceFile, media: MediaRegistry) {
         return parseCommentString(
             lexCommentString(file.text),
             this.config,
             file,
             this.application.logger,
+            media,
         );
     }
 
@@ -426,7 +432,11 @@ export class Converter extends ChildableComponent<
         if (createModuleReflections === false) {
             // Special case for when we're giving a single entry point, we don't need to
             // create modules for each entry. Register the project as this module.
-            context.project.registerReflection(context.project, symbol);
+            context.project.registerReflection(
+                context.project,
+                symbol,
+                entryPoint.sourceFile.fileName,
+            );
             context.project.comment = symbol
                 ? context.getComment(symbol, context.project.kind)
                 : context.getFileComment(node);
@@ -452,6 +462,7 @@ export class Converter extends ChildableComponent<
                 const readme = readFile(entryPoint.readmeFile);
                 const { content } = this.parseRawComment(
                     new MinimalSourceFile(readme, entryPoint.readmeFile),
+                    context.project.media,
                 );
                 reflection.readme = content;
             }
@@ -564,15 +575,22 @@ export class Converter extends ChildableComponent<
                     continue;
                 }
 
-                const { content, frontmatter } = this.parseRawComment(file);
+                const { content, frontmatter } = this.parseRawComment(
+                    file,
+                    reflection.project.media,
+                );
                 const docRefl = new DocumentReflection(
                     basename(file.fileName).replace(/\.[^.]+$/, ""),
                     parent,
                     content,
                     frontmatter,
                 );
                 parent.addChild(docRefl);
-                parent.project.registerReflection(docRefl);
+                parent.project.registerReflection(
+                    docRefl,
+                    undefined,
+                    file.fileName,
+                );
             }
         }
     }

src/lib/converter/plugins/PackagePlugin.ts

@@ -131,6 +131,7 @@ export class PackagePlugin extends ConverterComponent {
         if (this.readmeFile && this.readmeContents) {
             const { content } = this.application.converter.parseRawComment(
                 new MinimalSourceFile(this.readmeContents, this.readmeFile),
+                project.media,
             );
 
             project.readme = content;

src/lib/converter/types.ts

@@ -360,7 +360,7 @@ const functionTypeConverter: TypeConverter<ts.FunctionTypeNode, ts.Type> = {
             signature,
             new ReflectionSymbolId(symbol, node),
         );
-        context.registerReflection(signature, void 0);
+        context.registerReflection(signature, undefined);
         const signatureCtx = rc.withScope(signature);
 
         reflection.signatures = [signature];

src/lib/internationalization/translatable.ts

@@ -59,6 +59,7 @@ export const translatable = {
     // comments/parser.ts
     multiple_type_parameters_on_template_tag_unsupported: `TypeDoc does not support multiple type parameters defined in a single @template tag with a comment.`,
     failed_to_find_jsdoc_tag_for_name_0: `Failed to find JSDoc tag for {0} after parsing comment, please file a bug report.`,
+    relative_path_0_does_not_exist: `The relative path {0} does not exist.`,
 
     inline_inheritdoc_should_not_appear_in_block_tag_in_comment_at_0:
         "An inline @inheritDoc tag should not appear within a block tag as it will not be processed in comment at {0}",
@@ -142,6 +143,7 @@ export const translatable = {
 
     // deserialization
     serialized_project_referenced_0_not_part_of_project: `Serialized project referenced reflection {0}, which was not a part of the project.`,
+    saved_relative_path_0_resolved_from_1_does_not_exist: `Serialized project referenced {0}, which does not exist relative to {1}.`,
 
     // options
     circular_reference_extends_0: `Circular reference encountered for "extends" field of {0}`,