Improve validation for packageOptions

Ref: #2878

Author: Gerrit0

CHANGELOG.md

@@ -41,6 +41,7 @@ title: Changelog
 - Introduced `packagesRequiringDocumentation` option for `validation.notDocumented`, TypeDoc will expect comments to be present for symbols in the specified packages.
 - TypeDoc now exports a `typedoc/browser` entrypoint for parsing and using serialized JSON files, #2528.
 - Type `packageOptions` as `Partial<TypeDocOptions>`, #2878.
+- TypeDoc will now warn if an option which should only be set at the root level is set in `packageOptions`, #2878.
 
 ### Bug Fixes
 

src/lib/application.ts

@@ -17,7 +17,7 @@ import {
 } from "./utils/index.js";
 
 import { Option, Options } from "./utils/index.js";
-import type { TypeDocOptions } from "./utils/options/declaration.js";
+import { rootPackageOptions, type TypeDocOptions } from "./utils/options/declaration.js";
 import { type GlobString, i18n, Logger, LogLevel, type TranslatedString, unique } from "#utils";
 import { ok } from "assert";
 import {
@@ -776,6 +776,16 @@ export class Application extends AbstractComponent<
         const origOptions = this.options;
         const projects: JSONOutput.ProjectReflection[] = [];
 
+        for (const opt of Object.keys(this.options.getValue("packageOptions"))) {
+            if (rootPackageOptions.includes(opt as never)) {
+                this.logger.warn(
+                    i18n.package_option_0_should_be_specified_at_root(
+                        opt,
+                    ),
+                );
+            }
+        }
+
         const projectsToConvert: { dir: string; options: Options }[] = [];
         // Generate a json file for each package
         for (const dir of packageDirs) {

src/lib/internationalization/locales/en.cts

@@ -26,6 +26,8 @@ export = {
         "Failed to find any packages, ensure you have provided at least one directory as an entry point containing package.json",
     nested_packages_unsupported_0:
         "Project at {0} has entryPointStrategy set to packages, but nested packages are not supported",
+    package_option_0_should_be_specified_at_root:
+        "The packageOptions option sets option {0}, which only has an affect at the root level",
     previous_error_occurred_when_reading_options_for_0:
         "The previous error occurred when reading options for the package at {0}",
     converting_project_at_0: "Converting project at {0}",

src/lib/utils/options/declaration.ts

@@ -42,6 +42,77 @@ export type OutputSpecification = {
     options?: Partial<TypeDocOptions>;
 };
 
+/**
+ * List of option names which, with `entryPointStrategy` set to `packages`
+ * should only be set at the root level.
+ */
+export const rootPackageOptions = [
+    // Configuration Options
+    "plugin",
+    // Input Options
+    "packageOptions",
+    "includeHierarchySummary", // GERRIT: Move to output options
+    // Output Options
+    "outputs",
+    "out",
+    "html",
+    "json",
+    "pretty",
+    // emit
+    "theme",
+    "router",
+    "lightHighlightTheme",
+    "darkHighlightTheme",
+    "highlightLanguages",
+    "ignoredHighlightLanguages",
+    "typePrintWidth",
+    "customCss",
+    "customJs",
+    "customFooterHtml",
+    "customFooterHtmlDisableWrapper",
+    "markdownItOptions",
+    "markdownItLoader",
+    // basePath
+    "cname",
+    "favicon",
+    "sourceLinkExternal",
+    "markdownLinkExternal",
+    "lang",
+    "locales",
+    "githubPages",
+    "cacheBust",
+    "hideGenerator",
+    "searchInComments",
+    "searchInDocuments",
+    "cleanOutputDir",
+    "titleLink",
+    "navigationLinks",
+    "sidebarLinks",
+    "navigation",
+    "headings",
+    "sluggerConfiguration",
+    "navigationLeaves",
+    "visibilityFilters",
+    "searchCategoryBoosts",
+    "searchGroupBoosts",
+    "hostedBaseUrl",
+    "useHostedBaseUrlForAbsoluteLinks",
+    "useFirstParagraphOfCommentAsSummary",
+    // Comment Options
+    "notRenderedTags",
+    // Organization Options
+    // Validation Options
+    "treatWarningsAsErrors",
+    "treatValidationWarningsAsErrors",
+    // Other Options
+    "watch",
+    "preserveWatchOutput",
+    "help",
+    "version",
+    "showConfig",
+    "logLevel",
+] as const satisfies ReadonlyArray<keyof TypeDocOptionMap>;
+
 /**
  * An interface describing all TypeDoc specific options. Generated from a
  * map which contains more information about each option for better types when
@@ -86,6 +157,13 @@ export type TypeDocOptionValues = {
         TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 
+/**
+ * Describes TypeDoc options suitable for setting within the `packageOptions` setting.
+ *
+ * This is a subset of all options specified in {@link TypeDocOptions}.
+ */
+export interface TypeDocPackageOptions extends Omit<TypeDocOptions, typeof rootPackageOptions[number]> {}
+
 /**
  * Describes all TypeDoc options. Used internally to provide better types when fetching options.
  * External consumers should likely use {@link TypeDocOptions} instead.
@@ -109,7 +187,9 @@ export interface TypeDocOptionMap {
     plugin: NormalizedPathOrModule[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
-    packageOptions: ManuallyValidatedOption<Partial<TypeDocOptions>>;
+    packageOptions: ManuallyValidatedOption<
+        Partial<TypeDocPackageOptions>
+    >;
 
     // Input
     entryPoints: GlobString[];

src/lib/utils/options/index.ts

@@ -24,6 +24,7 @@ export type {
     TypeDocOptionMap,
     TypeDocOptions,
     TypeDocOptionValues,
+    TypeDocPackageOptions,
     ValidationOptions,
 } from "./declaration.js";
 

src/test/utils/options/default-options.test.ts

@@ -1,6 +1,7 @@
 import { deepStrictEqual as equal, doesNotThrow, ok, throws } from "assert";
 import { Options, TYPEDOC_ROOT } from "../../../lib/utils/index.js";
 import { readFileSync } from "fs";
+import { rootPackageOptions } from "../../../lib/utils/options/declaration.js";
 
 describe("Default Options", () => {
     const opts = new Options();
@@ -143,7 +144,7 @@ describe("Default Options", () => {
                 "utf-8",
             ).split("\n")
         ) {
-            const match = line.match(/\[`(.*)`\]\(/);
+            const match = line.match(/\[`(.*?)`\]\(/);
             if (match) {
                 linkedOptions.push(match[1]);
             }
@@ -158,6 +159,27 @@ describe("Default Options", () => {
         );
     });
 
+    it("Root package option documentation matches", () => {
+        const rootOptions: string[] = [];
+        for (
+            const line of readFileSync(
+                `${TYPEDOC_ROOT}/site/options/package-options.md`,
+                "utf-8",
+            ).split("\n")
+        ) {
+            const match = line.match(/\[`(.*?)`\]\(.*?\)\s*\| Root/);
+            if (match) {
+                rootOptions.push(match[1]);
+            }
+        }
+
+        equal(
+            rootOptions,
+            rootPackageOptions,
+            "Documented root options to not match internal list of root options",
+        );
+    });
+
     it("Option documentation", () => {
         const allOptions = opts
             .getDeclarations()