Add new option to enable/disable validation checks

As discussed in #1685.

Author: Gerrit0

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Unreleased
 
+### Features
+
+-   Added new `validation` option which can be used to disable checks for non-exported symbols.
+    On the command line, this can be specified with `--validation.notExported true`, or in an options file with:
+    ```json
+    {
+        "validation": {
+            "notExported": true
+        }
+    }
+    ```
+-   Added invalidLink to `validation` option, deprecated `listInvalidSymbolLinks`, which will be removed in 0.23.
+
 ## v0.22.2 (2021-08-11)
 
 ### Bug Fixes

package.json

@@ -65,7 +65,7 @@
     "pretest": "node scripts/copy_test_files.js",
     "test": "mocha --config .config/mocha.fast.json",
     "pretest:full": "npm run pretest",
-    "test:full": "nyc --reporter=html --reporter=text-summary mocha --config .config/mocha.full.json",
+    "test:full": "nyc mocha --config .config/mocha.full.json",
     "test:visual": "node ./dist/test/capture-screenshots.js && reg-suit -c .config/regconfig.json compare",
     "test:visual:accept": "node scripts/accept_visual_regression.js",
     "prerebuild_specs": "npm run pretest",
@@ -90,8 +90,13 @@
       ".ts",
       ".tsx"
     ],
+    "reporter": [
+      "html",
+      "text-summary"
+    ],
     "exclude": [
-      "**/*.d.ts"
+      "**/*.d.ts",
+      "src/test"
     ]
   }
 }

scripts/generate_options_schema.js

@@ -28,17 +28,26 @@ addTypeDocOptions({
             case ParameterType.Array:
                 data.type = "array";
                 data.items = { type: "string" };
-                data.default = option.defaultValue ?? [];
+                data.default =
+                    /** @type {import("../dist").ArrayDeclarationOption} */ (
+                        option
+                    ).defaultValue ?? [];
                 break;
             case ParameterType.String:
                 data.type = "string";
                 if (!IGNORED_DEFAULT_OPTIONS.has(option.name)) {
-                    data.default = option.defaultValue ?? "";
+                    data.default =
+                        /** @type {import("../dist").StringDeclarationOption} */ (
+                            option
+                        ).defaultValue ?? "";
                 }
                 break;
             case ParameterType.Boolean:
                 data.type = "boolean";
-                data.default = option.defaultValue ?? false;
+                data.default =
+                    /** @type {import("../dist").BooleanDeclarationOption} */ (
+                        option
+                    ).defaultValue ?? false;
                 break;
             case ParameterType.Number: {
                 const decl =
@@ -60,9 +69,27 @@ addTypeDocOptions({
                     map instanceof Map
                         ? [...map.keys()]
                         : Object.keys(map).filter((key) => isNaN(+key));
-                data.default = option.defaultValue;
+                data.default =
+                    /** @type {import("../dist").MapDeclarationOption} */ (
+                        option
+                    ).defaultValue;
                 break;
             }
+            case ParameterType.Flags: {
+                data.properties = {};
+                const defaults =
+                    /** @type {import("../dist").FlagsDeclarationOption<Record<string, boolean>>} */ (
+                        option
+                    ).defaults;
+
+                for (const key of Object.keys(defaults)) {
+                    data[key] = {
+                        type: "boolean",
+                    };
+                }
+                data.additionalProperties = false;
+                data.default = defaults;
+            }
             case ParameterType.Mixed:
                 break; // Nothing to do... TypeDoc really shouldn't have any of these.
         }

src/index.ts

@@ -35,6 +35,7 @@ export type {
     OptionsReader,
     TypeDocOptions,
     TypeDocOptionMap,
+    ValidationOptions,
     TypeDocOptionValues,
     KeyToDeclaration,
     DeclarationOption,
@@ -45,6 +46,7 @@ export type {
     ArrayDeclarationOption,
     MixedDeclarationOption,
     MapDeclarationOption,
+    FlagsDeclarationOption,
     DeclarationOptionToOptionType,
     SortStrategy,
     ParameterTypeToOptionTypeMap,

src/lib/application.ts

@@ -368,11 +368,19 @@ export class Application extends ChildableComponent<
     }
 
     validate(project: ProjectReflection) {
-        validateExports(
-            project,
-            this.logger,
-            this.options.getValue("intentionallyNotExported")
-        );
+        const checks = this.options.getValue("validation");
+
+        if (checks.notExported) {
+            validateExports(
+                project,
+                this.logger,
+                this.options.getValue("intentionallyNotExported")
+            );
+        }
+
+        // checks.invalidLink is currently handled when rendering by the MarkedLinksPlugin.
+        // It should really move here, but I'm putting that off until done refactoring the comment
+        // parsing so that we don't have duplicate parse logic all over the place.
     }
 
     /**

src/lib/output/plugins/MarkedLinksPlugin.ts

@@ -3,7 +3,7 @@ import * as Util from "util";
 import type { Reflection } from "../../models/reflections/abstract";
 import { Component, ContextAwareRendererComponent } from "../components";
 import { MarkdownEvent, RendererEvent } from "../events";
-import { BindOption } from "../../utils";
+import { BindOption, ValidationOptions } from "../../utils";
 
 /**
  * A plugin that builds links in markdown texts.
@@ -24,6 +24,9 @@ export class MarkedLinksPlugin extends ContextAwareRendererComponent {
     @BindOption("listInvalidSymbolLinks")
     listInvalidSymbolLinks!: boolean;
 
+    @BindOption("validation")
+    validation!: ValidationOptions;
+
     private warnings: string[] = [];
 
     /**
@@ -165,7 +168,15 @@ export class MarkedLinksPlugin extends ContextAwareRendererComponent {
      * Triggered when {@link Renderer} is finished
      */
     onEndRenderer(_event: RendererEvent) {
-        if (this.listInvalidSymbolLinks && this.warnings.length > 0) {
+        const enabled =
+            this.listInvalidSymbolLinks || this.validation.invalidLink;
+        if (this.listInvalidSymbolLinks) {
+            this.application.logger.warn(
+                "listInvalidSymbolLinks is deprecated and will be removed in 0.23, set validation.invalidLink instead."
+            );
+        }
+
+        if (enabled && this.warnings.length > 0) {
             this.application.logger.warn(
                 "\n[MarkedLinksPlugin]: Found invalid symbol reference(s) in JSDocs, " +
                     "they will not render as links in the generated documentation." +

src/lib/output/themes/MarkedPlugin.ts

@@ -22,6 +22,7 @@ customMarkedRenderer.heading = (text, level, _, slugger) => {
 
 /**
  * Implements markdown and relativeURL helpers for templates.
+ * @internal
  */
 @Component({ name: "marked" })
 export class MarkedPlugin extends ContextAwareRendererComponent {
@@ -194,22 +195,13 @@ output file :
             "markedOptions"
         ) ?? {}) as Marked.MarkedOptions;
 
-        if (
-            typeof markedOptions === "object" &&
-            !Array.isArray(markedOptions)
-        ) {
-            // Set some default values if they are not specified via the TypeDoc option
-            markedOptions.highlight ??= (text: any, lang: any) =>
-                this.getHighlighted(text, lang);
-            markedOptions.renderer ??= customMarkedRenderer;
-            markedOptions.mangle ??= false; // See https://github.com/TypeStrong/typedoc/issues/1395
-
-            return markedOptions;
-        }
+        // Set some default values if they are not specified via the TypeDoc option
+        markedOptions.highlight ??= (text: any, lang: any) =>
+            this.getHighlighted(text, lang);
+        markedOptions.renderer ??= customMarkedRenderer;
+        markedOptions.mangle ??= false; // See https://github.com/TypeStrong/typedoc/issues/1395
 
-        throw new Error(
-            "The value provided via the 'markedOptions' option must be a non-array object."
-        );
+        return markedOptions;
     }
 
     /**

src/lib/utils/index.ts

@@ -39,10 +39,12 @@ export type {
     MapDeclarationOption,
     MixedDeclarationOption,
     NumberDeclarationOption,
+    FlagsDeclarationOption,
     OptionsReader,
     StringDeclarationOption,
     TypeDocOptionMap,
     TypeDocOptions,
+    ValidationOptions,
     TypeDocOptionValues,
     ParameterTypeToOptionTypeMap,
 } from "./options";