Require input globs to have posix path sep

Resolves #2825

Hopefully this works on Windows without too many more changes...

Author: Gerrit0

.config/mocha.fast.json

@@ -5,5 +5,5 @@
     "spec": ["src/test/**/*.test.ts", "src/test/**/*.test.tsx"],
     "timeout": 5000,
     "watch-files": ["src/**/*.ts", "src/**/*.tsx"],
-    "node-option": ["import=tsx"]
+    "node-option": ["import=tsx", "conditions=typedoc-ts"]
 }

.config/mocha.full.json

@@ -3,5 +3,5 @@
     "timeout": 0,
     "spec": ["src/test/**/*.test.ts", "src/test/**/*.test.tsx"],
     "exclude": ["src/test/packages/**"],
-    "node-option": ["import=tsx"]
+    "node-option": ["import=tsx", "conditions=typedoc-ts"]
 }

.config/mocha.test-explorer.json

@@ -3,7 +3,7 @@
     "extension": ["ts"],
     "ignore": ["src/test/slow/**", "src/test/packages/**"],
     "package": "./package.json",
-    "node-option": ["import=tsx"],
+    "node-option": ["import=tsx", "conditions=typedoc-ts"],
     "slow": 500,
     "spec": ["src/**/*.test.ts", "src/**/*.test.tsx"],
     "timeout": 0,

.vscode/settings.json

@@ -33,7 +33,7 @@
         "editor.tabSize": 4
     },
 
-    "mochaExplorer.nodeArgv": ["--import=tsx"],
+    "mochaExplorer.nodeArgv": ["--import=tsx", "--conditions=typedoc-ts"],
 
     "eslint.workingDirectories": [".", "./example"],
     "mochaExplorer.configFile": ".config/mocha.test-explorer.json",

CHANGELOG.md

@@ -4,9 +4,11 @@ title: Changelog
 
 ## Beta
 
+- TypeDoc now expects all input globs paths to be specified with `/` path separators, #2825.
 - Added a `--router` option which can be used to modify TypeDoc's output folder
   structure. This can be extended with plugins, #2111.
 - TypeDoc will now only create references for symbols re-exported from modules.
+- API: `Path` and `PathArray` parameter types now always contain normalized paths.
 - API: Introduced a `Router` which is used for URL creation. `Reflection.url`,
   `Reflection.anchor`, and `Reflection.hasOwnDocument` have been removed.
 - Removed `jp` translations from `lang`, to migrate switch to `ja`.

package.json

@@ -105,6 +105,13 @@
         ]
     },
     "imports": {
-        "#utils": "./dist/lib/utils-common/index.js"
+        "#utils": {
+            "typedoc-ts": "./src/lib/utils-common/index.ts",
+            "default": "./dist/lib/utils-common/index.js"
+        },
+        "#node-utils": {
+            "typedoc-ts": "./src/lib/utils/index.ts",
+            "default": "./dist/lib/utils/index.js"
+        }
     }
 }

src/lib/application.ts

@@ -19,7 +19,7 @@ import {
 
 import { Option, Options } from "./utils/index.js";
 import type { TypeDocOptions } from "./utils/options/declaration.js";
-import { unique } from "#utils";
+import { type GlobString, unique } from "#utils";
 import { ok } from "assert";
 import {
     type DocumentationEntryPoint,
@@ -35,8 +35,7 @@ import { validateExports } from "./validation/exports.js";
 import { validateDocumentation } from "./validation/documentation.js";
 import { validateLinks } from "./validation/links.js";
 import { ApplicationEvents } from "./application-events.js";
-import { findTsConfigFile } from "./utils/tsconfig.js";
-import { deriveRootDir, glob, readFile } from "./utils/fs.js";
+import { deriveRootDir, findTsConfigFile, glob, readFile } from "#node-utils";
 import { addInferredDeclarationMapPaths } from "./models/reflections/ReflectionSymbolId.js";
 import { Internationalization, type TranslatedString } from "./internationalization/internationalization.js";
 import { FileRegistry, ValidatingFileRegistry } from "./models/FileRegistry.js";
@@ -162,7 +161,7 @@ export class Application extends AbstractComponent<
 
     /** @internal */
     @Option("entryPoints")
-    accessor entryPoints!: string[];
+    accessor entryPoints!: GlobString[];
 
     /**
      * The version number of TypeDoc.

src/lib/converter/converter.ts

@@ -22,9 +22,8 @@ import { getDocumentEntryPoints, MinimalSourceFile, Option, readFile } from "../
 import { convertType } from "./types.js";
 import { ConverterEvents } from "./converter-events.js";
 import { convertSymbol } from "./symbols.js";
-import { createMinimatch, matchesAny, nicePath } from "../utils/paths.js";
-import type { Minimatch } from "minimatch";
-import { hasAllFlags, hasAnyFlag, unique } from "#utils";
+import { MinimatchSet, nicePath } from "../utils/paths.js";
+import { type GlobString, hasAllFlags, hasAnyFlag, unique } from "#utils";
 import type { DocumentationEntryPoint } from "../utils/entry-point.js";
 import type { CommentParserConfig } from "./comments/index.js";
 import type { CommentStyle, ValidationOptions } from "../utils/options/declaration.js";
@@ -88,9 +87,9 @@ export interface ConverterEvents {
 export class Converter extends AbstractComponent<Application, ConverterEvents> {
     /** @internal */
     @Option("externalPattern")
-    accessor externalPattern!: string[];
-    private externalPatternCache?: Minimatch[];
-    private excludeCache?: Minimatch[];
+    accessor externalPattern!: GlobString[];
+    private externalPatternCache?: MinimatchSet;
+    private excludeCache?: MinimatchSet;
 
     /** @internal */
     @Option("excludeExternals")
@@ -588,17 +587,17 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
     }
 
     private isExcluded(symbol: ts.Symbol) {
-        this.excludeCache ??= createMinimatch(
+        this.excludeCache ??= new MinimatchSet(
             this.application.options.getValue("exclude"),
         );
         const cache = this.excludeCache;
 
-        return (symbol.getDeclarations() ?? []).some((node) => matchesAny(cache, node.getSourceFile().fileName));
+        return (symbol.getDeclarations() ?? []).some((node) => cache.matchesAny(node.getSourceFile().fileName));
     }
 
     /** @internal */
     isExternal(symbol: ts.Symbol) {
-        this.externalPatternCache ??= createMinimatch(this.externalPattern);
+        this.externalPatternCache ??= new MinimatchSet(this.externalPattern);
         const cache = this.externalPatternCache;
 
         const declarations = symbol.getDeclarations();
@@ -613,7 +612,7 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
         // If there are any non-external declarations, treat it as non-external
         // This is possible with declaration merging against external namespaces
         // (e.g. merging with HTMLElementTagNameMap)
-        return declarations.every((node) => matchesAny(cache, node.getSourceFile().fileName));
+        return declarations.every((node) => cache.matchesAny(node.getSourceFile().fileName));
     }
 
     processDocumentTags(reflection: Reflection, parent: ContainerReflection) {

src/lib/converter/plugins/PackagePlugin.ts

@@ -2,15 +2,21 @@ import * as Path from "path";
 
 import { ConverterComponent } from "../components.js";
 import type { Context } from "../context.js";
-import { EntryPointStrategy, Option, readFile } from "../../utils/index.js";
-import { deriveRootDir, discoverInParentDir, discoverPackageJson } from "../../utils/fs.js";
-import { nicePath } from "../../utils/paths.js";
-import { MinimalSourceFile } from "../../utils/minimalSourceFile.js";
 import type { ProjectReflection } from "../../models/index.js";
 import { ApplicationEvents } from "../../application-events.js";
-import { join } from "path";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
+import type { GlobString } from "#utils";
+import {
+    discoverInParentDir,
+    discoverPackageJson,
+    type EntryPointStrategy,
+    getCommonDirectory,
+    MinimalSourceFile,
+    nicePath,
+    Option,
+    readFile,
+} from "#node-utils";
 
 /**
  * A handler that tries to find the package.json and readme.md files of the
@@ -24,7 +30,7 @@ export class PackagePlugin extends ConverterComponent {
     accessor entryPointStrategy!: EntryPointStrategy;
 
     @Option("entryPoints")
-    accessor entryPoints!: string[];
+    accessor entryPoints!: GlobString[];
 
     @Option("includeVersion")
     accessor includeVersion!: boolean;
@@ -72,12 +78,8 @@ export class PackagePlugin extends ConverterComponent {
         this.readmeContents = undefined;
         this.packageJson = undefined;
 
-        const entryFiles = this.entryPointStrategy === EntryPointStrategy.Packages
-            ? this.entryPoints.map((d) => join(d, "package.json"))
-            : this.entryPoints;
-
         const dirName = this.application.options.packageDir ??
-            Path.resolve(deriveRootDir(entryFiles));
+            Path.resolve(getCommonDirectory(this.entryPoints.map(g => `${g}/`)));
 
         this.application.logger.verbose(
             `Begin readme.md/package.json search at ${nicePath(dirName)}`,

src/lib/converter/plugins/SourcePlugin.ts

@@ -10,6 +10,7 @@ import { SourceReference } from "../../models/index.js";
 import { gitIsInstalled, RepositoryManager } from "../utils/repository.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
+import type { NormalizedPath } from "#utils";
 
 /**
  * A handler that attaches source file information to reflections.
@@ -31,7 +32,7 @@ export class SourcePlugin extends ConverterComponent {
     accessor sourceLinkTemplate!: string;
 
     @Option("basePath")
-    accessor basePath!: string;
+    accessor basePath!: NormalizedPath;
 
     /**
      * All file names to find the base path from.