Merge remote-tracking branch 'origin/master' into beta

.config/.prettierignore

@@ -8,6 +8,7 @@
 ../src/test/renderer/specs
 ../src/test/renderer/testProject
 ../src/test/utils/options/readers/data/invalid2.json
+../src/test/converter2/behavior/constTypeParam.ts
 ../static/main.js
 ../example/docs/
 **/tmp

CHANGELOG.md

@@ -55,6 +55,31 @@
 
 # Unreleased
 
+## v0.23.28 (2023-03-19)
+
+### Features
+
+-   Added support for TypeScript 5.0, #2201.
+    -   `const` type parameters.
+    -   JSDoc `@overload` tag.
+    -   JSDoc `@satisfies` tag.
+
+## v0.23.27 (2023-03-16)
+
+### Features
+
+-   Added `--treatValidationWarningsAsErrors` to treat only validation warnings as errors without treating all warnings as errors, #2199.
+
+### Bug Fixes
+
+-   Fixed a bug where optional properties were not appropriately marked as optional, #2200.
+-   Fixed shifted navigation pane on devices 1024px wide, #2191.
+-   Add missing `@private` and `@protected` tags to `typedoc/tsdoc.json`, #2187.
+
+### Thanks!
+
+-   @futurGH
+
 ## v0.23.26 (2023-02-26)
 
 ### Features

package.json

@@ -30,24 +30,24 @@
     "shiki": "^0.14.1"
   },
   "peerDependencies": {
-    "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x"
+    "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x"
   },
   "devDependencies": {
     "@types/lunr": "^2.3.4",
     "@types/marked": "^4.0.8",
     "@types/mocha": "^10.0.1",
     "@types/node": "14",
-    "@typescript-eslint/eslint-plugin": "^5.51.0",
-    "@typescript-eslint/parser": "^5.51.0",
+    "@typescript-eslint/eslint-plugin": "^5.55.0",
+    "@typescript-eslint/parser": "^5.55.0",
     "@typestrong/fs-fixture-builder": "github:TypeStrong/fs-fixture-builder#8abd1494280116ff5318dde2c50ad01e1663790c",
-    "c8": "^7.12.0",
-    "esbuild": "^0.17.7",
-    "eslint": "^8.34.0",
+    "c8": "^7.13.0",
+    "esbuild": "^0.17.12",
+    "eslint": "^8.36.0",
     "mocha": "^10.2.0",
     "prettier": "2.8.4",
     "puppeteer": "^13.5.2",
     "ts-node": "^10.9.1",
-    "typescript": "4.9.5"
+    "typescript": "5.0.2"
   },
   "files": [
     "/bin",

src/lib/cli.ts

@@ -90,13 +90,17 @@ async function run(app: td.Application) {
         return ExitCodes.CompileError;
     }
 
+    const preValidationWarnCount = app.logger.warningCount;
     app.validate(project);
+    const hadValidationWarnings =
+        app.logger.warningCount !== preValidationWarnCount;
     if (app.logger.hasErrors()) {
         return ExitCodes.ValidationError;
     }
     if (
-        app.options.getValue("treatWarningsAsErrors") &&
-        app.logger.hasWarnings()
+        hadValidationWarnings &&
+        (app.options.getValue("treatWarningsAsErrors") ||
+            app.options.getValue("treatValidationWarningsAsErrors"))
     ) {
         return ExitCodes.ValidationError;
     }

src/lib/converter/comments/discovery.ts

@@ -3,6 +3,7 @@ import { ReflectionKind } from "../../models";
 import { assertNever, Logger } from "../../utils";
 import { CommentStyle } from "../../utils/options/declaration";
 import { nicePath } from "../../utils/paths";
+import { ok } from "assert";
 
 // Note: This does NOT include JSDoc syntax kinds. This is important!
 // Comments from @typedef and @callback tags are handled specially by
@@ -172,6 +173,22 @@ export function discoverSignatureComment(
         return;
     }
 
+    if (ts.isJSDocSignature(node)) {
+        const comment = node.parent.parent;
+        ok(ts.isJSDoc(comment));
+
+        return [
+            node.getSourceFile(),
+            [
+                {
+                    kind: ts.SyntaxKind.MultiLineCommentTrivia,
+                    pos: comment.pos,
+                    end: comment.end,
+                },
+            ],
+        ];
+    }
+
     const text = node.getSourceFile().text;
 
     const comments = collectCommentRanges(

src/lib/converter/factories/signature.ts

@@ -286,10 +286,10 @@ function convertTypeParameters(
 
         // There's no way to determine directly from a ts.TypeParameter what it's variance modifiers are
         // so unfortunately we have to go back to the node for this...
-        const variance = getVariance(
-            param.getSymbol()?.declarations?.find(ts.isTypeParameterDeclaration)
-                ?.modifiers
-        );
+        const declaration = param
+            .getSymbol()
+            ?.declarations?.find(ts.isTypeParameterDeclaration);
+        const variance = getVariance(declaration?.modifiers);
 
         const paramRefl = new TypeParameterReflection(
             param.symbol.name,
@@ -305,6 +305,15 @@ function convertTypeParameters(
             ? context.converter.convertType(paramCtx, defaultT)
             : void 0;
 
+        // No way to determine this from the type parameter itself, need to go back to the declaration
+        if (
+            declaration?.modifiers?.some(
+                (m) => m.kind === ts.SyntaxKind.ConstKeyword
+            )
+        ) {
+            paramRefl.flags.setFlag(ReflectionFlag.Const, true);
+        }
+
         context.registerReflection(paramRefl, param.getSymbol());
         context.trigger(ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl);
 
@@ -337,6 +346,10 @@ export function createTypeParamReflection(
     paramRefl.default = param.default
         ? context.converter.convertType(paramScope, param.default)
         : void 0;
+    if (param.modifiers?.some((m) => m.kind === ts.SyntaxKind.ConstKeyword)) {
+        paramRefl.flags.setFlag(ReflectionFlag.Const, true);
+    }
+
     context.registerReflection(paramRefl, param.symbol);
 
     if (ts.isJSDocTemplateTag(param.parent)) {

src/lib/converter/symbols.ts

@@ -420,14 +420,8 @@ function convertFunctionOrMethod(
 
     // Can't use zip here. We might have less declarations than signatures
     // or less signatures than declarations.
-    for (let i = 0; i < signatures.length; i++) {
-        createSignature(
-            scope,
-            ReflectionKind.CallSignature,
-            signatures[i],
-            symbol,
-            declarations[i]
-        );
+    for (const sig of signatures) {
+        createSignature(scope, ReflectionKind.CallSignature, sig, symbol);
     }
 }
 
@@ -634,9 +628,13 @@ function convertProperty(
         (ts.isPropertyDeclaration(declaration) ||
             ts.isPropertySignature(declaration) ||
             ts.isParameter(declaration) ||
-            ts.isPropertyAccessExpression(declaration))
+            ts.isPropertyAccessExpression(declaration) ||
+            ts.isPropertyAssignment(declaration))
     ) {
-        if (!ts.isPropertyAccessExpression(declaration)) {
+        if (
+            !ts.isPropertyAccessExpression(declaration) &&
+            !ts.isPropertyAssignment(declaration)
+        ) {
             parameterType = declaration.type;
         }
         setModifiers(symbol, declaration, reflection);
@@ -1023,8 +1021,11 @@ function setModifiers(
     );
     reflection.setFlag(
         ReflectionFlag.Readonly,
-        hasAllFlags(symbol.checkFlags ?? 0, ts.CheckFlags.Readonly) ||
-            hasAllFlags(modifiers, ts.ModifierFlags.Readonly)
+        hasAllFlags(
+            // TS 4.9: symbol.checkFlags, links was introduced in 5.0
+            symbol.checkFlags ?? symbol.links?.checkFlags ?? 0,
+            ts.CheckFlags.Readonly
+        ) || hasAllFlags(modifiers, ts.ModifierFlags.Readonly)
     );
     reflection.setFlag(
         ReflectionFlag.Abstract,

src/lib/output/themes/default/partials/typeParameters.tsx

@@ -11,6 +11,7 @@ export function typeParameters(context: DefaultThemeRenderContext, typeParameter
                     {typeParameters?.map((item) => (
                         <li>
                             <h4>
+                                {item.flags.isConst && "const "}
                                 {item.varianceModifier ? `${item.varianceModifier} ` : ""}
                                 {item.name}
                                 {!!item.type && (

src/lib/output/themes/lib.tsx

@@ -109,6 +109,7 @@ export function renderTypeParametersSignature(
                     <span class="tsd-signature-symbol">{"<"}</span>
                     {join(<span class="tsd-signature-symbol">{", "}</span>, typeParameters, (item) => (
                         <>
+                            {item.flags.isConst && "const "}
                             {item.varianceModifier ? `${item.varianceModifier} ` : ""}
                             <span class="tsd-signature-type" data-tsd-kind={ReflectionKind.singularString(item.kind)}>
                                 {item.name}

src/lib/types/ts-internal/index.d.ts

@@ -10,9 +10,16 @@ declare module "typescript" {
     }
 
     interface Symbol {
+        // TS before 5.0
         // https://github.com/microsoft/TypeScript/blob/v4.1.5/src/compiler/types.ts#L4734-L4737
         checkFlags?: CheckFlags;
 
+        // TS 5.0
+        // https://github.com/microsoft/TypeScript/blob/5.0.2/src/compiler/types.ts#L5891-L5898
+        links?: {
+            checkFlags: CheckFlags;
+        };
+
         // https://github.com/microsoft/TypeScript/blob/v4.7.4/src/compiler/types.ts#L4941
         // https://github.com/microsoft/TypeScript/issues/38344
         parent?: ts.Symbol;

src/lib/utils/entry-point.ts

@@ -441,10 +441,9 @@ function getEntryPointsForLegacyPackages(
             return;
         }
 
+        const packageName = packageJson["name"] as string;
         results.push({
-            displayName:
-                typedocPackageConfig?.displayName ??
-                (packageJson["name"] as string),
+            displayName: typedocPackageConfig?.displayName ?? packageName,
             version: includeVersion
                 ? (packageJson["version"] as string | undefined)
                 : void 0,

src/lib/utils/options/declaration.ts

@@ -167,6 +167,7 @@ export interface TypeDocOptionMap {
 
     // Validation
     treatWarningsAsErrors: boolean;
+    treatValidationWarningsAsErrors: boolean;
     intentionallyNotExported: string[];
     validation: ValidationOptions;
     requiredToBeDocumented: ReflectionKind.KindString[];

src/lib/utils/options/sources/typedoc.ts

@@ -304,7 +304,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         name: "excludeTags",
         help: "Remove the listed block/modifier tags from doc comments.",
         type: ParameterType.Array,
-        defaultValue: ["@override", "@virtual", "@privateRemarks"],
+        defaultValue: [
+            "@override",
+            "@virtual",
+            "@privateRemarks",
+            "@satisfies",
+        ],
         validate(value) {
             if (!Validation.validate([Array, Validation.isTagString], value)) {
                 throw new Error(
@@ -656,7 +661,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
 
     options.addDeclaration({
         name: "treatWarningsAsErrors",
-        help: "If set, warnings will be treated as errors.",
+        help: "If set, all warnings will be treated as errors.",
+        type: ParameterType.Boolean,
+    });
+    options.addDeclaration({
+        name: "treatValidationWarningsAsErrors",
+        help: "If set, warnings emitted during validation will be treated as errors. This option cannot be used to disable treatWarningsAsErrors for validation warnings.",
         type: ParameterType.Boolean,
     });
     options.addDeclaration({

src/lib/utils/options/tsdoc-defaults.ts

@@ -25,6 +25,7 @@ export const blockTags = [
     "@callback",
     "@prop",
     "@property",
+    "@satisfies",
 ] as const;
 
 export const tsdocInlineTags = ["@link", "@inheritDoc", "@label"] as const;
@@ -52,4 +53,5 @@ export const modifierTags = [
     "@ignore",
     "@enum",
     "@event",
+    "@overload",
 ] as const;

src/lib/utils/package-manifest.ts

@@ -63,18 +63,21 @@ export function extractTypedocConfigFromPackageManifest(
     }
     if (
         hasOwnProperty(packageJson, "typedoc") &&
-        typeof packageJson.typedoc == "object" &&
-        packageJson.typedoc
+        typeof packageJson["typedoc"] == "object" &&
+        packageJson["typedoc"]
     ) {
         if (
-            !validate(typedocPackageManifestConfigSchema, packageJson.typedoc)
+            !validate(
+                typedocPackageManifestConfigSchema,
+                packageJson["typedoc"]
+            )
         ) {
             logger.error(
                 `Typedoc config extracted from package manifest file ${packageJsonPath} is not valid`
             );
             return undefined;
         }
-        return packageJson.typedoc;
+        return packageJson["typedoc"];
     }
     return undefined;
 }

src/test/behaviorTests.ts

@@ -141,6 +141,13 @@ export const behaviorTests: {
         );
     },
 
+    constTypeParam(project) {
+        const getNamesExactly = query(project, "getNamesExactly");
+        const typeParams = getNamesExactly.signatures?.[0].typeParameters;
+        equal(typeParams?.length, 1);
+        equal(typeParams[0].flags.isConst, true);
+    },
+
     declareGlobal(project) {
         equal(
             project.children?.map((c) => c.name),
@@ -548,6 +555,25 @@ export const behaviorTests: {
         logger.expectNoOtherMessages();
     },
 
+    overloadTags(project) {
+        const printValue = query(project, "printValue");
+        equal(printValue.signatures?.length, 2);
+
+        const [first, second] = printValue.signatures;
+
+        equal(first.parameters?.length, 1);
+        equal(
+            Comment.combineDisplayParts(first.parameters[0].comment?.summary),
+            "first docs"
+        );
+
+        equal(second.parameters?.length, 2);
+        equal(
+            Comment.combineDisplayParts(second.parameters[0].comment?.summary),
+            "second docs"
+        );
+    },
+
     readonlyTag(project) {
         const title = query(project, "Book.title");
         const author = query(project, "Book.author");

src/test/converter/class/specs-with-lump-categories.json

@@ -3253,7 +3253,7 @@
               "type": {
                 "type": "reference",
                 "target": {
-                  "sourceFileName": "node_modules/typescript/lib/lib.es5.d.ts",
+                  "sourceFileName": "node_modules/typescript/lib/lib.decorators.legacy.d.ts",
                   "qualifiedName": "ClassDecorator"
                 },
                 "name": "ClassDecorator",
@@ -3323,7 +3323,7 @@
               "type": {
                 "type": "reference",
                 "target": {
-                  "sourceFileName": "node_modules/typescript/lib/lib.es5.d.ts",
+                  "sourceFileName": "node_modules/typescript/lib/lib.decorators.legacy.d.ts",
                   "qualifiedName": "MethodDecorator"
                 },
                 "name": "MethodDecorator",