Finish moving Node references out of models

Ref: #2528

Author: Gerrit0

CHANGELOG.md

@@ -16,6 +16,13 @@ title: Changelog
   control over export conversion order, #2856
 - API: `Deserializer.reviveProject(s)` no longer accepts an option to add project documents.
 - API: `Deserializer.reviveProjects` now requires an `alwaysCreateEntryPointModule` option.
+- API: `Comment.serializeDisplayParts` no longer requires a serializer argument.
+- API: `ReflectionSymbolId.fileName` has been removed, TypeDoc now stores a combination of a package name and package relative path instead.
+- API: Removed `DeclarationReflection.relevanceBoost` attribute which was added for plugins, but never used.
+- The `source-order` sort ordering now considers package names / package relative paths instead of using the absolute paths to a file.
+- File name references in `intentionallyNotExported` now use a package name/package relative path instead of an absolute path for matching.
+- Introduced `packagesRequiringDocumentation` option for `validation.notDocumented`, TypeDoc will expect comments to be present for symbols in the specified packages.
+- TypeDoc's `--entryPointStrategy merge` mode now requires JSON from at least version 0.28.0.
 
 TODO:
 

eslint.config.mjs

@@ -34,7 +34,7 @@ const config = {
         ],
 
         // This can probably be turned back on in 0.27, when the component hierarchy goes away
-        "@typescript-eslint/no-unsafe-function-type": "off",
+        // "@typescript-eslint/no-unsafe-function-type": "off", GERRIT
 
         // This one is just annoying since it complains at incomplete code
         "no-empty": "off",
@@ -196,29 +196,21 @@ export default tslint.config(
             ],
         },
     },
-    // Down to 14 issues!
-    // {
-    //     files: ["src/lib/models/**/*.ts"],
-    //     rules: {
-    //         "no-restricted-imports": [
-    //             "error",
-    //             {
-    //                 paths: nodeModules,
-    //                 patterns: [
-    //                     "node:*",
-    //                     "\\#*",
-    //                     "!\\#utils",
-    //                     "!\\#serialization",
-    //                     "../*",
-    //                     "!../FileRegistry.js",
-    //                     "!../types.js",
-    //                     "!../comments/index.js",
-    //                     "!../sources/file.js",
-    //                 ],
-    //             },
-    //         ],
-    //     },
-    // },
+    {
+        files: ["src/lib/models/**/*.ts"],
+        rules: {
+            "no-restricted-imports": [
+                "error",
+                {
+                    paths: nodeModules,
+                    patterns: [{
+                        regex: "^(?!\./|#utils|#serialization).*",
+                        message: "models may only import within this directory or #utils/#serialization",
+                    }],
+                },
+            ],
+        },
+    },
     {
         files: ["src/lib/serialization/**/*.ts"],
         rules: {

scripts/generate_options_schema.js

@@ -17,15 +17,13 @@ const schema = {
     allowTrailingCommas: true,
 };
 
-const i18n = new Internationalization.Internationalization(null).proxy;
-
 addTypeDocOptions({
     /** @param {import("../dist/index.js").DeclarationOption} option */
     addDeclaration(option) {
         if (IGNORED_OPTIONS.has(option.name)) return;
 
         const data = {
-            description: option.help(i18n),
+            description: option.help(),
         };
 
         const type = option.type ?? ParameterType.String;
@@ -42,6 +40,7 @@ addTypeDocOptions({
                 break;
             case ParameterType.String:
             case ParameterType.Path:
+            case ParameterType.UrlOrPath:
                 data.type = "string";
                 if (!IGNORED_DEFAULT_OPTIONS.has(option.name)) {
                     data.default = /** @type {import("../dist/index.js").StringDeclarationOption} */ (

scripts/rebuild_specs.js

@@ -9,6 +9,7 @@ import * as td from "../dist/index.js";
 import { getExpandedEntryPointsForPaths } from "../dist/lib/utils/index.js";
 import { ok } from "assert";
 import { fileURLToPath } from "url";
+import { diagnostics } from "../dist/lib/utils/loggers.js";
 
 const base = path.join(
     fileURLToPath(import.meta.url),
@@ -101,7 +102,7 @@ function rebuildConverterTests(app, dirs) {
 
     const errors = ts.getPreEmitDiagnostics(program);
     if (errors.length) {
-        app.logger.diagnostics(errors);
+        diagnostics(app.logger, errors);
         return;
     }
 
@@ -124,7 +125,7 @@ function rebuildConverterTests(app, dirs) {
                 result.name = basename(fullPath);
                 const serialized = app.serializer.projectToObject(
                     result,
-                    process.cwd(),
+                    td.normalizePath(process.cwd()),
                 );
 
                 const data = JSON.stringify(serialized, null, 4) + "\n";

site/options/package-options.md

@@ -83,8 +83,8 @@ at the root level. The following tables indicate where an option should be set.
 | [`favicon`](output.md#favicon)                                                         | Root     |                                                            |
 | [`sourceLinkExternal`](output.md#sourcelinkexternal)                                   | Root     |                                                            |
 | [`markdownLinkExternal`](output.md#markdownlinkexternal)                               | Root     |                                                            |
-| [`lang`](output.md#lang)                                                               | Both     | Will move to Root in TypeDoc 0.28                          |
-| [`locales`](output.md#locales)                                                         | Both     | Will move to Root in TypeDoc 0.28                          |
+| [`lang`](output.md#lang)                                                               | Root     |                                                            |
+| [`locales`](output.md#locales)                                                         | Root     |                                                            |
 | [`githubPages`](output.md#githubpages)                                                 | Root     |                                                            |
 | [`cacheBust`](output.md#cachebust)                                                     | Root     |                                                            |
 | [`hideGenerator`](output.md#hidegenerator)                                             | Root     |                                                            |
@@ -144,6 +144,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`treatValidationWarningsAsErrors`](validation.md#treatvalidationwarningsaserrors) | Root     |                                                                                                                                        |
 | [`intentionallyNotExported`](validation.md#intentionallynotexported)               | Both     |                                                                                                                                        |
 | [`requiredToBeDocumented`](validation.md#requiredtobedocumented)                   | Both     |                                                                                                                                        |
+| [`packagesRequiringDocumentation`](validation.md#packagesrequiringdocumentation)   | Both     |                                                                                                                                        |
 | [`intentionallyNotDocumented`](validation.md#intentionallynotdocumented)           | Both     |                                                                                                                                        |
 
 ## Other Options

site/options/validation.md

@@ -67,13 +67,16 @@ This option cannot be used to turn `treatWarningsAsErrors` off for validation wa
 ## intentionallyNotExported
 
 Lists symbols which are intentionally excluded from the documentation output and should not produce warnings.
-Entries may optionally specify a file name before a colon to only suppress warnings for symbols declared in a specific file.
+Entries may optionally specify a package name / package relative file name before a colon to only suppress warnings for symbols declared in a specific file.
 
 typedoc.json:
 
 ```json
 {
-    "intentionallyNotExported": ["InternalClass", "src/other.ts:OtherInternal"]
+    "intentionallyNotExported": [
+        "InternalClass",
+        "typedoc/src/other.ts:OtherInternal"
+    ]
 }
 ```
 
@@ -124,6 +127,17 @@ typedoc.json:
 }
 ```
 
+## packagesRequiringDocumentation
+
+Specifies which packages TypeDoc should expect to have documentation.
+Defaults to the name of your package from `package.json`.
+
+```json
+{
+    "packagesRequiringDocumentation": ["typedoc", "typedoc-plugin-mdn-links"]
+}
+```
+
 ## intentionallyNotDocumented
 
 Used to selectively ignore undocumented fields, used by `validation.notDocumented`.

site/overview.md

@@ -19,8 +19,9 @@ the supported version range will generally not include versions not supported by
 
 | TypeDoc Version | TypeScript Version | Status             |
 | --------------- | ------------------ | ------------------ |
-| 0.27            | 5.0 through 5.7    | ✅ Maintained      |
-| 0.26            | 4.6 through 5.6    | ⚠️ Security Updates |
+| 0.28            | 5.1 through 5.8    | ✅ Maintained      |
+| 0.27            | 5.0 through 5.7    | ⚠️ Security Updates |
+| 0.26            | 4.6 through 5.6    | ❌ Unmaintained    |
 | 0.25            | 4.6 through 5.4    | ❌ Unmaintained    |
 | 0.24            | 4.6 through 5.1    | ❌ Unmaintained    |
 | 0.23            | 4.6 through 5.0    | ❌ Unmaintained    |

src/index.ts

@@ -8,7 +8,7 @@
  */
 export { Application, type ApplicationEvents } from "./lib/application.js";
 
-export { resetReflectionID } from "./lib/models/reflections/abstract.js";
+export { resetReflectionID } from "./lib/models/Reflection.js";
 /**
  * All symbols documented under the Models namespace are also available in the root import.
  * @primaryExport
@@ -87,6 +87,7 @@ export {
     ParameterType,
     TSConfigReader,
     TypeDocReader,
+    ValidatingFileRegistry,
 } from "./lib/utils/index.js";
 
 export type {

src/lib/application.ts

@@ -4,7 +4,7 @@ import ts from "typescript";
 import { Deserializer, type JSONOutput, Serializer } from "./serialization/index.js";
 import { Converter } from "./converter/index.js";
 import { Renderer } from "./output/renderer.js";
-import type { ProjectReflection } from "./models/index.js";
+import { type ProjectReflection, ReflectionSymbolId } from "./models/index.js";
 import {
     AbstractComponent,
     FancyConsoleLogger,
@@ -35,7 +35,6 @@ import { validateDocumentation } from "./validation/documentation.js";
 import { validateLinks } from "./validation/links.js";
 import { ApplicationEvents } from "./application-events.js";
 import { deriveRootDir, findTsConfigFile, glob, readFile } from "#node-utils";
-import { addInferredDeclarationMapPaths } from "./models/ReflectionSymbolId.js";
 import { Internationalization } from "./internationalization/internationalization.js";
 import { FileRegistry } from "./models/FileRegistry.js";
 import { readFileSync } from "fs";
@@ -45,6 +44,7 @@ import { Outputs } from "./output/output.js";
 import { validateMergeModuleWith } from "./validation/unusedMergeModuleWith.js";
 import { diagnostic, diagnostics } from "./utils/loggers.js";
 import { ValidatingFileRegistry } from "./utils/ValidatingFileRegistry.js";
+import { addInferredDeclarationMapPaths } from "./converter/factories/symbol-id.js";
 
 const packageInfo = JSON.parse(
     readFileSync(
@@ -670,11 +670,16 @@ export class Application extends AbstractComponent<
         }
 
         if (checks.notDocumented) {
+            const packagesRequiringDocumentation = this.options.isSet("packagesRequiringDocumentation")
+                ? this.options.getValue("packagesRequiringDocumentation")
+                : [project.packageName ?? ReflectionSymbolId.UNKNOWN_PACKAGE];
+
             validateDocumentation(
                 project,
                 this.logger,
                 this.options.getValue("requiredToBeDocumented"),
                 this.options.getValue("intentionallyNotDocumented"),
+                packagesRequiringDocumentation,
             );
         }
 

src/lib/converter/comments/blockLexer.ts

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { type Token, TokenSyntaxKind } from "./lexer.js";
-import { ReflectionSymbolId } from "../../models/ReflectionSymbolId.js";
 import { resolveAliasedSymbol } from "../utils/symbols.js";
+import { createSymbolId } from "../factories/symbol-id.js";
 
 export function* lexBlockComment(
     file: string,
@@ -356,7 +356,7 @@ function* lexBlockComment2(
                     getRightmostName(link.name),
                 );
                 if (tsTarget) {
-                    token.tsLinkTarget = new ReflectionSymbolId(
+                    token.tsLinkTarget = createSymbolId(
                         resolveAliasedSymbol(tsTarget, checker!),
                     );
                     token.tsLinkText = link.text.replace(/^\s*\|\s*/, "");

src/lib/converter/context.ts

@@ -18,6 +18,8 @@ import { resolveAliasedSymbol } from "./utils/symbols.js";
 import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment } from "./comments/index.js";
 import { getHumanName } from "../utils/tsutils.js";
 import { normalizePath } from "#node-utils";
+import { createSymbolId } from "./factories/symbol-id.js";
+import { type NormalizedPath, removeIf } from "#utils";
 
 /**
  * The context describes the current state the converter is in.
@@ -67,6 +69,8 @@ export class Context {
     convertingClassOrInterface = false; // Not inherited
     shouldBeStatic = false; // Not inherited
 
+    private reflectionIdToSymbolMap = new Map<number, ts.Symbol>();
+
     /**
      * Create a new Context instance.
      *
@@ -77,7 +81,7 @@ export class Context {
         converter: Converter,
         programs: readonly ts.Program[],
         project: ProjectReflection,
-        scope: Context["scope"] = project,
+        scope: Reflection = project,
     ) {
         this.converter = converter;
         this.programs = programs;
@@ -197,15 +201,15 @@ export class Context {
         }
 
         if (reflection instanceof DeclarationReflection) {
-            reflection.escapedName = symbol?.escapedName;
+            reflection.escapedName = symbol?.escapedName ? String(symbol.escapedName) : undefined;
             this.addChild(reflection);
         }
 
         if (symbol && this.converter.isExternal(symbol)) {
             reflection.setFlag(ReflectionFlag.External);
         }
         if (exportSymbol) {
-            this.registerReflection(reflection, exportSymbol);
+            this.registerReflection(reflection, exportSymbol, void 0);
         }
 
         const path = reflection.kindOf(
@@ -215,9 +219,9 @@ export class Context {
             : undefined;
 
         if (path) {
-            this.project.registerReflection(reflection, symbol, normalizePath(path));
+            this.registerReflection(reflection, symbol, normalizePath(path));
         } else {
-            this.project.registerReflection(reflection, symbol, undefined);
+            this.registerReflection(reflection, symbol, undefined);
         }
     }
 
@@ -250,8 +254,51 @@ export class Context {
      * @param reflection  The reflection that should be registered.
      * @param symbol  The symbol the given reflection was resolved from.
      */
-    registerReflection(reflection: Reflection, symbol: ts.Symbol | undefined) {
-        this.project.registerReflection(reflection, symbol, void 0);
+    registerReflection(reflection: Reflection, symbol: ts.Symbol | undefined, filePath?: NormalizedPath) {
+        if (symbol) {
+            this.reflectionIdToSymbolMap.set(reflection.id, symbol);
+            const id = createSymbolId(symbol);
+
+            // #2466
+            // If we just registered a member of a class or interface, then we need to check if
+            // we've registered this symbol before under the wrong parent reflection.
+            // This can happen because the compiler API will use non-dependently-typed symbols
+            // for properties of classes/interfaces which inherit them, so we can't rely on the
+            // property being unique for each class.
+            if (
+                reflection.parent?.kindOf(ReflectionKind.ClassOrInterface) &&
+                reflection.kindOf(ReflectionKind.SomeMember)
+            ) {
+                const saved = this.project["symbolToReflectionIdMap"].get(id);
+                const parentSymbolReflection = symbol.parent &&
+                    this.getReflectionFromSymbol(symbol.parent);
+
+                if (
+                    typeof saved === "object" &&
+                    saved.length > 1 &&
+                    parentSymbolReflection
+                ) {
+                    removeIf(
+                        saved,
+                        (item) =>
+                            this.project.getReflectionById(item)?.parent !==
+                                parentSymbolReflection,
+                    );
+                }
+            }
+
+            this.project.registerReflection(reflection, id, filePath);
+        } else {
+            this.project.registerReflection(reflection, void 0, filePath);
+        }
+    }
+
+    getReflectionFromSymbol(symbol: ts.Symbol) {
+        return this.project.getReflectionFromSymbolId(createSymbolId(symbol));
+    }
+
+    getSymbolFromReflection(reflection: Reflection) {
+        return this.reflectionIdToSymbolMap.get(reflection.id);
     }
 
     /** @internal */
@@ -321,6 +368,9 @@ export class Context {
     }
 
     public withScope(scope: Reflection): Context {
+        // TODO: This will be important for #2862
+        // assert(scope.parent === this.scope, "Incorrect context used for withScope");
+
         const context = new Context(
             this.converter,
             this.programs,
@@ -329,6 +379,7 @@ export class Context {
         );
         context.convertingTypeNode = this.convertingTypeNode;
         context.setActiveProgram(this._program);
+        context.reflectionIdToSymbolMap = this.reflectionIdToSymbolMap;
         return context;
     }
 }