Convert compiler options before setting overrides

Resolves #3000

Author: Gerrit0

.vscode/settings.json

@@ -66,6 +66,7 @@
         "Msys",
         "nodoc",
         "shiki",
+        "srcset",
         "tsbuildinfo",
         "tsdoc",
         "typedoc",

CHANGELOG.md

@@ -7,6 +7,8 @@ title: Changelog
 ### Bug Fixes
 
 - Fixed link resolution not working correctly in first comment on the file in some cases, #2994.
+- The `compilerOptions` option now functions properly with non-boolean options, #3000.
+- Configuration errors within the `compilerOptions` option are now handled gracefully, #3000.
 
 ## v0.28.10 (2025-08-10)
 

src/lib/application.ts

@@ -496,7 +496,7 @@ export class Application extends AbstractComponent<
             );
         }
 
-        if (Object.keys(this.options.getCompilerOptions()).length === 0) {
+        if (Object.keys(this.options.getCompilerOptions(this.logger)).length === 0) {
             this.logger.warn(i18n.no_compiler_options_set());
         }
 
@@ -525,7 +525,7 @@ export class Application extends AbstractComponent<
 
         const host = ts.createWatchCompilerHost(
             tsconfigFile,
-            this.options.fixCompilerOptions({}),
+            this.options.fixCompilerOptions({}, this.logger),
             ts.sys,
             ts.createEmitAndSemanticDiagnosticsBuilderProgram,
             (d) => diagnostic(this.logger, d),

src/lib/internationalization/locales/en.cts

@@ -242,6 +242,7 @@ export = {
 
     options_file_0_does_not_exist: `The options file {0} does not exist`,
     failed_read_options_file_0: `Failed to parse {0}, ensure it exists and exports an object`,
+    failed_to_apply_compilerOptions_overrides_0: "Failed to apply compilerOptions overrides: {0}",
 
     // plugins
     invalid_plugin_0_missing_load_function: `Invalid structure in plugin {0}, no load function found`,

src/lib/utils/entry-point.ts

@@ -344,7 +344,7 @@ export function getExpandedEntryPointsForPaths(
     options: Options,
     programs = getEntryPrograms(inputFiles, logger, options),
 ): DocumentationEntryPoint[] {
-    const compilerOptions = options.getCompilerOptions();
+    const compilerOptions = options.getCompilerOptions(logger);
     const supportedFileRegex = compilerOptions.allowJs || compilerOptions.checkJs
         ? /\.([cm][tj]s|[tj]sx?)$/
         : /\.([cm]ts|tsx?)$/;
@@ -410,16 +410,16 @@ function getEntryPrograms(
     const rootProgram = noTsConfigFound
         ? ts.createProgram({
             rootNames: inputFiles,
-            options: options.getCompilerOptions(),
+            options: options.getCompilerOptions(logger),
         })
         : ts.createProgram({
             rootNames: options.getFileNames(),
-            options: options.getCompilerOptions(),
+            options: options.getCompilerOptions(logger),
             projectReferences: options.getProjectReferences(),
         });
 
     addInferredDeclarationMapPaths(
-        options.getCompilerOptions(),
+        options.getCompilerOptions(logger),
         options.getFileNames(),
     );
 
@@ -438,6 +438,7 @@ function getEntryPrograms(
                 ts.createProgram({
                     options: options.fixCompilerOptions(
                         ref.commandLine.options,
+                        logger,
                     ),
                     rootNames: ref.commandLine.fileNames,
                     projectReferences: ref.commandLine.projectReferences,

src/lib/utils/options/options.ts

@@ -1,4 +1,4 @@
-import type ts from "typescript";
+import ts from "typescript";
 import { resolve } from "path";
 import { ParameterType } from "./declaration.js";
 import type { OutputSpecification } from "../index.js";
@@ -361,19 +361,34 @@ export class Options {
     /**
      * Gets the set compiler options.
      */
-    getCompilerOptions(): ts.CompilerOptions {
-        return this.fixCompilerOptions(this._compilerOptions);
+    getCompilerOptions(logger: Logger): ts.CompilerOptions {
+        return this.fixCompilerOptions(this._compilerOptions, logger);
     }
 
     /** @internal */
     fixCompilerOptions(
         options: Readonly<ts.CompilerOptions>,
+        logger: Logger,
     ): ts.CompilerOptions {
         const overrides = this.getValue("compilerOptions");
         const result = { ...options };
 
         if (overrides) {
-            Object.assign(result, overrides);
+            const tsOptions = ts.convertCompilerOptionsFromJson(overrides, ".", "typedoc-overrides.json");
+
+            if (tsOptions.errors.length) {
+                for (const error of tsOptions.errors) {
+                    logger.error(
+                        i18n.failed_to_apply_compilerOptions_overrides_0(
+                            ts.flattenDiagnosticMessageText(error.messageText, "\n"),
+                        ),
+                    );
+                }
+            } else {
+                for (const key in overrides) {
+                    result[key] = tsOptions.options[key];
+                }
+            }
         }
 
         if (this.getValue("emit") !== "both") {

src/test/converter2/issues/gh2631/crlf.md

@@ -1,5 +1,5 @@
----
-title: "Windows Line Endings"
----
-
-This file contains CRLF line endings
+---
+title: "Windows Line Endings"
+---
+
+This file contains CRLF line endings

src/test/programs.ts

@@ -96,7 +96,7 @@ export function getConverterProgram() {
         const app = getConverterApp();
         converterProgram = ts.createProgram(
             app.options.getFileNames(),
-            app.options.getCompilerOptions(),
+            app.options.getCompilerOptions(app.logger),
         );
 
         const errors = ts.getPreEmitDiagnostics(converterProgram);
@@ -134,7 +134,7 @@ export function getConverter2Program() {
         const app = getConverter2App();
         converter2Program = ts.createProgram(
             app.options.getFileNames(),
-            app.options.getCompilerOptions(),
+            app.options.getCompilerOptions(app.logger),
         );
 
         const errors = ts.getPreEmitDiagnostics(converter2Program);

src/test/slow/internationalization-usage.test.ts

@@ -9,7 +9,8 @@ describe("Internationalization", () => {
     it("Does not include strings in translatable object which are unused", () => {
         const options = new Options();
         const tsconfigReader = new TSConfigReader();
-        tsconfigReader.read(options, new Logger(), process.cwd());
+        const logger = new Logger();
+        tsconfigReader.read(options, logger, process.cwd());
 
         const defaultLocaleTs = join(
             fileURLToPath(import.meta.url),
@@ -26,7 +27,7 @@ describe("Internationalization", () => {
                 );
             },
             getCurrentDirectory: () => process.cwd(),
-            getCompilationSettings: () => options.getCompilerOptions(),
+            getCompilationSettings: () => options.getCompilerOptions(logger),
             getDefaultLibFileName: (opts) => ts.getDefaultLibFilePath(opts),
             fileExists: ts.sys.fileExists,
             readFile: ts.sys.readFile,

src/test/utils/options/options.test.ts

@@ -3,6 +3,8 @@ import { type MapDeclarationOption, type NumberDeclarationOption, Option } from
 import { deepStrictEqual as equal, throws } from "assert";
 import type { DeclarationOption, EmitStrategy } from "../../../lib/utils/options/index.js";
 import { LogLevel } from "#utils";
+import { TestLogger } from "../../TestLogger.js";
+import ts from "typescript";
 
 describe("Options", () => {
     let options: Options & {
@@ -180,6 +182,32 @@ describe("Options", () => {
 
         throws(() => options.reset("thisOptionDoesNotExist" as never));
     });
+
+    it("Handles tsconfig overrides which aren't strings, #3000", () => {
+        const logger = new TestLogger();
+        const options = new Options();
+
+        options.setValue("compilerOptions", {
+            moduleResolution: "bundler",
+        });
+
+        const compilerOptions = options.getCompilerOptions(logger);
+        equal(compilerOptions.moduleResolution, ts.ModuleResolutionKind.Bundler);
+    });
+
+    it("Handles tsconfig overrides which are invalid, #3000", () => {
+        const logger = new TestLogger();
+        const options = new Options();
+
+        options.setValue("compilerOptions", {
+            moduleResolution: "bad",
+        });
+
+        const compilerOptions = options.getCompilerOptions(logger);
+        equal(compilerOptions.moduleResolution, undefined);
+
+        logger.expectMessage("error: Failed to apply compilerOptions overrides: *");
+    });
 });
 
 describe("Option", () => {