Improve error reporting for Windows path separators

Resolves #2938

Author: Gerrit0

CHANGELOG.md

@@ -10,6 +10,7 @@ title: Changelog
 - `@link` links to the current page are now rendered, #2934.
 - `@includeCode` now supports regions in TypeScript files with `.mts` and `.cts` file extensions, #2935.
 - Aliased symbols (re-exports) are now resolved before checking if they are excluded/external, #2937.
+- Improved error reporting when paths including Windows separators are provided as globs, #2938.
 
 ## v0.28.2 (2025-04-07)
 

src/lib/cli.ts

@@ -26,7 +26,7 @@ async function main() {
             new td.TypeDocReader(),
             new td.PackageJsonReader(),
             new td.TSConfigReader(),
-            new td.ArgumentsReader(300),
+            new td.ArgumentsReader(300).ignoreErrors(),
         ]);
 
         const exitCode = await run(app);

src/lib/internationalization/locales/en.cts

@@ -200,7 +200,6 @@ export = {
     use_expand_or_glob_for_files_in_dir:
         `If you wanted to include files inside this directory, set --entryPointStrategy to expand or specify a glob`,
     glob_0_did_not_match_any_files: `The glob {0} did not match any files`,
-    glob_should_use_posix_slash: `Try replacing Windows path separators (\\) with posix path separators (/)`,
     entry_point_0_did_not_match_any_files_after_exclude:
         `The glob {0} did not match any files after applying exclude patterns`,
     entry_point_0_did_not_exist: `Provided entry point {0} does not exist`,
@@ -218,6 +217,8 @@ export = {
     circular_reference_extends_0: `Circular reference encountered for "extends" field of {0}`,
     failed_resolve_0_to_file_in_1: `Failed to resolve {0} to a file in {1}`,
 
+    glob_0_should_use_posix_slash:
+        `The glob "{0}" escapes a non-special character. Glob inputs to TypeDoc may not use Windows path separators (\\), try replacing with posix path separators (/)`,
     option_0_can_only_be_specified_by_config_file: `The '{0}' option can only be specified via a config file`,
     option_0_expected_a_value_but_none_provided: `--{0} expected a value, but none was given as an argument`,
     unknown_option_0_may_have_meant_1: `Unknown option: {0}, you may have meant:\n\t{1}`,

src/lib/internationalization/locales/ja.cts

@@ -138,7 +138,6 @@ export = localeUtils.buildIncompleteTranslation({
     use_expand_or_glob_for_files_in_dir:
         "このディレクトリ内のファイルを含める場合は、--entryPointStrategyを設定して展開するか、globを指定します。",
     glob_0_did_not_match_any_files: "グロブ {0} はどのファイルにも一致しませんでした",
-    // glob_should_use_posix_slash
     entry_point_0_did_not_match_any_files_after_exclude:
         "除外パターンを適用した後、グロブ {0} はどのファイルにも一致しませんでした",
     entry_point_0_did_not_exist: "指定されたエントリ ポイント {0} は存在しません",

src/lib/internationalization/locales/zh.cts

@@ -174,7 +174,6 @@ export = localeUtils.buildIncompleteTranslation({
     failed_to_resolve_0_to_ts_path: "无法将 package.json 中的入口点 {0} 解析至 TypeScript 源文件",
     use_expand_or_glob_for_files_in_dir: "如果要包含此目录中的文件，请设置 --entryPointStrategy 以展开或指定 glob",
     glob_0_did_not_match_any_files: "glob {0} 与任何文件均不匹配",
-    glob_should_use_posix_slash: `请将 Windows 路径分隔符（\\）替换为 POSIX 路径分隔符（/）`,
     entry_point_0_did_not_match_any_files_after_exclude: "应用排除模式后，glob {0} 没有匹配任何文件",
     entry_point_0_did_not_exist: "提供的入口点 {0} 不存在",
     entry_point_0_did_not_match_any_packages: "入口点 glob {0} 与任何包含 package.json 的目录不匹配",

src/lib/utils/entry-point.ts

@@ -372,9 +372,6 @@ function expandGlobs(globs: GlobString[], exclude: GlobString[], logger: Logger)
             logger.warn(
                 i18n.glob_0_did_not_match_any_files(entry),
             );
-            if (entry.includes("\\") && !entry.includes("/")) {
-                logger.info(i18n.glob_should_use_posix_slash());
-            }
         } else if (filtered.length === 0) {
             logger.warn(
                 i18n.entry_point_0_did_not_match_any_files_after_exclude(

src/lib/utils/options/declaration.ts

@@ -769,7 +769,19 @@ const converters: {
         return resolved;
     },
     [ParameterType.GlobArray](value, option, configPath) {
-        const toGlobString = (v: unknown) => createGlobString(configPath, String(v));
+        const toGlobString = (v: unknown) => {
+            const s = String(v);
+
+            // If the string tries to escape a character which isn't a special
+            // glob character, the user probably provided a Windows style path
+            // by accident due to shell completion, tell them to either remove
+            // the useless escape or switch to Unix path separators.
+            if (/\\[^?*()[\]\\{}]/.test(s)) {
+                throw new Error(i18n.glob_0_should_use_posix_slash(s));
+            }
+
+            return createGlobString(configPath, s);
+        };
         const globs = Array.isArray(value) ? value.map(toGlobString) : [toGlobString(value)];
         option.validate?.(globs);
         return globs;

src/lib/utils/options/readers/arguments.ts

@@ -18,12 +18,18 @@ export class ArgumentsReader implements OptionsReader {
     readonly order: number;
     readonly supportsPackages = false;
     private args: string[];
+    private skipErrorReporting = false;
 
     constructor(priority: number, args = process.argv.slice(2)) {
         this.order = priority;
         this.args = args;
     }
 
+    ignoreErrors() {
+        this.skipErrorReporting = true;
+        return this;
+    }
+
     read(container: Options, logger: Logger): void {
         // Make container's type more lax, we do the appropriate checks manually.
         const options = container as Options & {
@@ -38,7 +44,9 @@ export class ArgumentsReader implements OptionsReader {
                 options.setValue(name, value);
             } catch (err) {
                 ok(err instanceof Error);
-                logger.error(err.message as TranslatedString);
+                if (!this.skipErrorReporting) {
+                    logger.error(err.message as TranslatedString);
+                }
             }
         };
 
@@ -50,11 +58,13 @@ export class ArgumentsReader implements OptionsReader {
 
             if (decl) {
                 if (decl.configFileOnly) {
-                    logger.error(
-                        i18n.option_0_can_only_be_specified_by_config_file(
-                            decl.name,
-                        ),
-                    );
+                    if (!this.skipErrorReporting) {
+                        logger.error(
+                            i18n.option_0_can_only_be_specified_by_config_file(
+                                decl.name,
+                            ),
+                        );
+                    }
                     continue;
                 }
 
@@ -81,11 +91,13 @@ export class ArgumentsReader implements OptionsReader {
                 } else {
                     if (index === this.args.length) {
                         // Only boolean values have optional values.
-                        logger.warn(
-                            i18n.option_0_expected_a_value_but_none_provided(
-                                decl.name,
-                            ),
-                        );
+                        if (!this.skipErrorReporting) {
+                            logger.warn(
+                                i18n.option_0_expected_a_value_but_none_provided(
+                                    decl.name,
+                                ),
+                            );
+                        }
                     }
                     trySet(decl.name, this.args[index]);
                 }
@@ -115,12 +127,14 @@ export class ArgumentsReader implements OptionsReader {
                 }
             }
 
-            logger.error(
-                i18n.unknown_option_0_may_have_meant_1(
-                    name,
-                    options.getSimilarOptions(name).join("\n\t"),
-                ),
-            );
+            if (!this.skipErrorReporting) {
+                logger.error(
+                    i18n.unknown_option_0_may_have_meant_1(
+                        name,
+                        options.getSimilarOptions(name).join("\n\t"),
+                    ),
+                );
+            }
             index++;
         }
     }

src/test/programs.ts

@@ -15,7 +15,7 @@ import { createAppForTesting } from "../lib/application.js";
 import { existsSync } from "fs";
 import { clearCommentCache } from "../lib/converter/comments/index.js";
 import { diagnostics } from "../lib/utils/loggers.js";
-import { readFile } from "#node-utils";
+import { normalizePath, readFile } from "#node-utils";
 
 let converterApp: Application | undefined;
 let converterProgram: ts.Program | undefined;
@@ -163,7 +163,8 @@ export function getConverter2Project(entries: string[], folder: string) {
                 join(base, folder, entry),
             ].find(existsSync)
         )
-        .filter((x) => x !== undefined);
+        .filter((x) => x !== undefined)
+        .map(normalizePath);
 
     const files = entryPoints.map((e) => program.getSourceFile(e));
     for (const [index, file] of files.entries()) {