@ng-doc/builder 22.0.0-beta.2 → 22.1.0

package/generator/vite/tsconfig-paths.d.ts

@@ -0,0 +1,64 @@
+import ts from 'typescript';
+import type { Plugin } from 'vite';
+/** The name of the plugin that resolves the `paths` of the application's tsconfig. */
+export declare const NG_DOC_TSCONFIG_PATHS_PLUGIN = "@ng-doc/vite:tsconfig-paths";
+/** The `tsconfig` option of the Analog Angular plugin. */
+export type AngularTsconfigOption = string | (() => string) | undefined;
+interface Pattern {
+    readonly prefix: string;
+    readonly suffix: string;
+}
+/** The `paths` of one tsconfig, with everything a resolution needs. */
+export interface TsconfigPathMappings {
+    readonly options: ts.CompilerOptions;
+    /** The directory `paths` targets are relative to: `baseUrl`, else the declaring tsconfig's. */
+    readonly base: string;
+    readonly exact: ReadonlySet<string>;
+    readonly patterns: readonly Pattern[];
+}
+/** A parsed tsconfig: its mappings (none without `paths`) and every file the parse read. */
+export interface TsconfigPaths {
+    readonly file: string;
+    readonly mappings?: TsconfigPathMappings;
+    /** The tsconfig and the configurations it extends, as canonical paths. */
+    readonly inputs: ReadonlySet<string>;
+}
+/**
+ * The tsconfig the Analog Angular plugin compiles with, resolved as Analog resolves it: an
+ * absolute path as is, anything else against the Vite root, and by default `tsconfig.app.json`
+ * (`tsconfig.lib.json`, or `tsconfig.lib.prod.json` in production, for a library build).
+ */
+export declare function angularTsconfigPath(root: string, tsconfig: AngularTsconfigOption, isProd: boolean, isLib: boolean): string;
+/**
+ * Reads the `paths` of a tsconfig with TypeScript's own parser, so `extends` (files and packages),
+ * `baseUrl` and the base directory of inherited `paths` mean what they mean to the compiler. The
+ * parse never lists the program's files: only the compiler options are used.
+ */
+export declare function readTsconfigPaths(file: string): TsconfigPaths;
+/** Whether a specifier is a bare module name that a `paths` key of the mappings matches. */
+export declare function matchesPathMapping(mappings: TsconfigPathMappings, source: string): boolean;
+/**
+ * The locations a specifier maps to, in order, as TypeScript substitutes them: an exact key wins,
+ * otherwise the wildcard pattern with the longest prefix.
+ */
+export declare function pathMappingTargets(mappings: TsconfigPathMappings, source: string): string[];
+/**
+ * Resolves the `compilerOptions.paths` of the application's tsconfig, as the Angular CLI does: a
+ * bare specifier that a `paths` key matches is resolved by TypeScript's module resolution with the
+ * tsconfig's options, then handed to Vite as the file path, so it gets the same module id as a
+ * relative import of that file. A mapping TypeScript resolves to a declaration file (a built
+ * library in `dist`, for example) is resolved as Vite resolves the installed package, or else its
+ * mapped locations, which reads the package's `package.json`. What TypeScript does not resolve, or
+ * finds in `node_modules`, is
+ * left to Vite. Modules in `node_modules` never use the application's mappings, and an alias of
+ * the Vite configuration wins over a mapping, since Vite applies aliases first.
+ *
+ * In development, the tsconfig and the configurations it extends are watched, and an edit of one
+ * is read again at the next resolution.
+ * @param tsconfig - The `tsconfig` option of the Analog Angular plugin.
+ * @param compilerTsconfig - The tsconfig the Analog compiler itself resolved (its
+ *   `api.getTsConfigPath`, Analog 2.8 and later), read once the configuration is resolved, so
+ *   both always read the same file; without it, the plugin resolves the option as Analog does.
+ */
+export declare function createTsconfigPathsPlugin(tsconfig: AngularTsconfigOption, compilerTsconfig?: () => string | undefined): Plugin;
+export {};

package/generator/vite/vite-event-source.d.ts

@@ -0,0 +1,198 @@
+import type { FSWatcher } from 'vite';
+import type { BuildResult, Diagnostic, FileChange, FileEventSource, WatchInputs } from '../contracts.js';
+type Listener = (events: FileChange[]) => void;
+type ErrorListener = (diagnostic: Diagnostic) => void;
+export interface WatchObservation {
+    accepted: boolean;
+    reconcile: boolean;
+    /**
+     * With `reconcile`: exactly what may have changed unseen, namely the new physical targets and
+     * the rejected changes that the new inputs now match. Absent when the rejections overflowed
+     * their bound: then every input is reconciled.
+     */
+    paths?: string[];
+}
+/**
+ * Distinct paths rejected while a generation is in flight that are kept to be checked against
+ * its newly recorded inputs. Beyond this the check is replaced by an unconditional reconcile.
+ */
+export declare const MAX_RETAINED_REJECTIONS = 1024;
+/** Recoverable watcher errors are reported together, at most once per this many milliseconds. */
+export declare const WATCHER_ERROR_COALESCE_MS = 100;
+/**
+ * The code of a watcher failure that cannot recover while Vite runs. The lifecycle keeps it until
+ * restart.
+ */
+export declare const NGDOC_VITE_WATCHER = "NGDOC_VITE_WATCHER";
+/**
+ * Distinct paths outside the recorded inputs whose native watch was lost, kept because a later
+ * generation can record an input there. More than this is fatal.
+ */
+export declare const MAX_LOST_WATCHES = 1024;
+/**
+ * How long the re-observation of new inputs waits for chokidar to attach their watches. chokidar
+ * attaches after asynchronous `stat`/`realpath` calls and signals nothing per path; after this the
+ * re-observation runs anyway (a slower attach leaves the same window as before it existed).
+ */
+export declare const WATCH_ATTACH_TIMEOUT_MS = 1000;
+/**
+ * chokidar lists a path in `getWatched()` just before it registers the path's native listener
+ * (FSEvents: one `realpath` later; `fs.watch`: after the directory read that lists its entries).
+ * A watch is taken as attached this long after it is listed.
+ */
+export declare const WATCH_ATTACH_GRACE_MS = 10;
+/**
+ * chokidar (as bundled by Vite) reports no `change` of a path within 50 ms of the last one it
+ * reported, and reports nothing for it afterwards either. An in-place save can then be reported
+ * at its truncation only, and the generation it starts may read the half-written file. So each
+ * forwarded change of a file is checked again this long after it was forwarded: a file whose
+ * stat moved since is reported once more. Longer than chokidar's window, so a write inside it is
+ * seen; a write after it is reported by chokidar itself.
+ */
+export declare const TRAILING_RESTAT_MS = 100;
+/** Where the native watcher may be attached. */
+export interface WatchScopeOptions {
+    /**
+     * The workspace root. Recorded files outside it are polled instead of natively watched; without
+     * it every target goes to the native watcher.
+     */
+    workspaceRoot?: string;
+    /** The poll interval for files outside the workspace (tests use a short one). */
+    probeIntervalMs?: number;
+    /**
+     * Directories the watcher itself watches recursively (Vite's root). Its directory watches there
+     * report every new file, so missing inputs below them stay with it.
+     */
+    watchedRoots?: readonly string[];
+    /**
+     * Whether missing inputs that the watcher cannot report get their own directory watches (see
+     * `watchesMissingPaths`). Default true; false when the host does not watch at all.
+     */
+    watchMissingPaths?: boolean;
+}
+export declare class ViteFileEventSource implements FileEventSource {
+    private readonly watcher;
+    private readonly registry;
+    private listener?;
+    private errorListener?;
+    private disposed;
+    private registration;
+    private ownedRoots;
+    private buffered;
+    private seeded;
+    /** Paths rejected since the newest generation started, until its result is observed. */
+    private retained;
+    private retainedOverflow;
+    /** Recoverable failures outside the inputs since the newest generation started. */
+    private retainedErrors;
+    private retainedErrorsOverflow;
+    /** Lost native watches outside the inputs; chokidar never re-creates them. */
+    private lostWatches;
+    private lostWatchesOverflow;
+    /**
+     * Incremented whenever an observation installs different effective inputs in the registry,
+     * current or not; `checkedInputs` is the version whose inputs the retained failures were last
+     * re-checked against.
+     */
+    private inputsVersion;
+    private checkedInputs;
+    private inFlight;
+    private recoverable?;
+    private unrelated?;
+    private errorFlush?;
+    private readonly workspace;
+    /** Whether missing inputs outside `watchedRoots` get the directory watches of `missing`. */
+    private readonly groupsMissingPaths;
+    private readonly watchedRoots;
+    private readonly missing;
+    /** Warnings raised before `subscribe` gave them a listener. */
+    private readonly pendingWarnings;
+    private readonly probes;
+    /** Targets handed to the native watcher (the ones whose attachment can be awaited). */
+    private readonly native;
+    /** The trailing re-stat of each recently forwarded file (see `TRAILING_RESTAT_MS`). */
+    private readonly trailing;
+    private readonly onAddDirectory;
+    private readonly onDeleteDirectory;
+    /**
+     * chokidar keeps watching after every `error` it emits; each one is an `fs` failure for a single
+     * path (see `_handleError` and its callers in the chokidar that Vite bundles):
+     *
+     * - `syscall: 'watch'`: the native `fs.watch` handle for the path could not be created (for
+     *   example ENOSPC at the inotify limit, or EMFILE) or failed later. chokidar never re-creates
+     *   it, so later changes there are never reported. Fatal when it can hide a recorded input.
+     * - any other `fs` failure (stat, lstat, realpath, scandir, open, including awaitWriteFinish):
+     *   the path is still watched or is re-read on its directory's next change, but an event may
+     *   have been missed. Like a lossy FSEvents signal of the session's own watcher, this is a
+     *   `WATCHER_RESCAN` warning, and the session re-observes every committed input.
+     *
+     * A failure for a path that cannot hide a recorded input (outside the inputs, or below a
+     * generator-owned root the generator itself rewrites) is only a warning. A value that is not
+     * an `fs` failure was not raised by chokidar and stays fatal.
+     */
+    private readonly onError;
+    constructor(watcher: FSWatcher, capacity: number, scope?: WatchScopeOptions);
+    seed(generation: number, watchInputs?: WatchInputs): Promise<WatchObservation>;
+    started(generation: number): void;
+    isCurrent(generation: number): boolean;
+    /**
+     * Whether a host change is a generator input. A change rejected while a generation is in flight
+     * is retained: if that generation records the path as a new input (it may have read the old
+     * bytes), its observation requests a reconcile.
+     */
+    matches(change: FileChange): boolean;
+    /**
+     * A change the host watcher reported. An input that has a directory watch of its own is reported
+     * by that watch only, so one change never reaches the session twice.
+     */
+    forward(change: FileChange): boolean;
+    /**
+     * Reports `file` again if its stat moves within `TRAILING_RESTAT_MS` of now: a write chokidar's
+     * change throttle dropped. A later forward of the same file restarts the check from its state.
+     */
+    private restatLater;
+    private deliver;
+    excludeOwned(...roots: string[]): void;
+    observe(result: BuildResult): Promise<WatchObservation>;
+    subscribe(listener: Listener, onError: ErrorListener): Promise<{
+        dispose(): Promise<void>;
+    }>;
+    dispose(): Promise<void>;
+    /**
+     * Splits new physical targets between the native watcher and the external probe poller.
+     *
+     * Native: everything inside the workspace (missing files included: chokidar watches such a
+     * path through its nearest directory and reports its creation), every glob base, and any file
+     * at or below a glob base, whose native directory watch already covers it. Polled: the other
+     * recorded files outside the workspace, which are the configuration lookups the compiler makes
+     * in every directory up to the filesystem root. Adding those natively attached chokidar's
+     * FSEvents streams to `/` and the home directory's parents. Beyond
+     * `MAX_EXTERNAL_PROBES` the rest stays native, as before. Missing: with a watcher that cannot
+     * report every missing path (see `watchesMissingPaths`), a missing file inside the workspace
+     * that neither a glob base nor a recursively watched root covers is watched through its nearest
+     * existing directory (`MissingPathWatcher`); one below such a root is left to the root's watch.
+     */
+    private placeTargets;
+    private warn;
+    /**
+     * Resolves once chokidar lists every given native target as watched, `false` after `timeoutMs`.
+     * A new input is re-observed only after this: a change made after the re-observation is then
+     * reported by the watch. chokidar's FSEvents handler records a path just before it registers the
+     * path's listener (one `realpath` later), so a short grace follows. A watcher without
+     * `getWatched()` (a test double) counts as attached.
+     */
+    attached(paths: readonly string[], timeoutMs?: number): Promise<boolean>;
+    private owned;
+    /** Whether a watcher failure at `target` can hide a change to a recorded input. */
+    private covers;
+    private lostWatch;
+    private pend;
+    /**
+     * The inputs just changed: a failure recorded while a path was not an input can now hide one.
+     * A lost watch there is fatal; a recoverable failure during this generation requests a rescan.
+     */
+    private recheckErrors;
+    private flushErrors;
+    private emitDirectory;
+}
+export {};

package/generator/vite/vite-version.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The Vite releases the Vite engine supports: Vite 8 from 8.3.0, the release `@angular/build` 22.2
+ * itself runs on. The engine bundles a patched Analog 2.8.0 and relies on Vite's hot-update,
+ * watcher, optimizer and module-runner APIs, which are tested on this major; Vite 7 and earlier
+ * are refused.
+ *
+ * `ng-doc.viteEngine.vite` in `libs/builder/package.json`, which the setup schematics install, must
+ * equal it (a test compares them). The builder's optional `vite` peer dependency is wider, Analog's
+ * own peer range: before the migration adds `vite`, the Vite at the application's root is the one
+ * its `@angular/build` brings (7.3 for Angular 22.0, 8.1 for 22.1), and npm refuses to install a
+ * package whose peer range excludes it, even an optional one and even for the legacy engine, which
+ * never loads Vite. The check below enforces the range where it matters, when the Vite engine
+ * starts.
+ */
+export declare const SUPPORTED_VITE_RANGE = "^8.3.0";
+/**
+ * Whether a Vite version is inside {@link SUPPORTED_VITE_RANGE}. A prerelease of a supported
+ * release (8.4.0-beta.1) is accepted; one of 8.3.0 itself is not.
+ * @param version - The Vite version.
+ */
+export declare function isSupportedViteVersion(version: string): boolean;
+/**
+ * Fails when the Vite engine runs on a Vite outside {@link SUPPORTED_VITE_RANGE}.
+ * @param found - The running Vite's version; by default the one NgDoc resolves.
+ */
+export declare function assertSupportedViteVersion(found?: string | undefined): void;

package/generator/vite/watch-inputs.d.ts

@@ -0,0 +1,39 @@
+import type { BuildResult, FileChange, WatchInputs } from '../contracts.js';
+export declare class WatchInputRegistry {
+    private readonly capacity;
+    private success?;
+    private failure?;
+    private effective;
+    private index;
+    private newestGeneration;
+    private readonly physical;
+    constructor(capacity: number);
+    started(generation: number): void;
+    isCurrent(generation: number): boolean;
+    /**
+     * `directories` lists the physical targets added for glob bases (existing directories); every
+     * other added target is a recorded file, present or missing.
+     */
+    observe(result: BuildResult): Promise<{
+        changed: boolean;
+        physicalAdded: string[];
+        directories: string[];
+        accepted: boolean;
+    }>;
+    /**
+     * A change matches a recorded file or glob base, an ancestor directory of one, or a glob member
+     * that is not excluded.
+     */
+    matches(change: FileChange): boolean;
+    /**
+     * True when a watcher problem at `target` can hide a change to a recorded input: the target
+     * matches like a change would, or lies below a glob base (a directory whose members can become
+     * inputs, whose own events do not match until a member does).
+     */
+    covers(target: string): boolean;
+    /** True when `target` lies at or below a recorded glob base (a watched input directory). */
+    underGlobBase(target: string): boolean;
+    snapshot(): WatchInputs;
+    physicalCount(): number;
+    confirmPhysical(targets: readonly string[]): void;
+}

package/generator/worker/entry.d.ts

@@ -0,0 +1 @@
+export {};