@ng-doc/builder 22.0.0-beta.1 → 22.0.0

package/generator/vite/lease.d.ts

@@ -0,0 +1,6 @@
+export interface OutputLease {
+    admit(outputRoot: string): void;
+    seal(outputRoot: string): void;
+    dispose(): void;
+}
+export declare function acquireOutputLease(identity: string, defaultOutputRoot: string): OutputLease;

package/generator/vite/lifecycle.d.ts

@@ -0,0 +1,119 @@
+import type { ViteDevServer } from 'vite';
+import type { BuildEvent, BuildResult, BuildSession, PublishedGeneratorConfiguration, WatchHandle } from '../contracts.js';
+import { GeneratedAssetInventory } from './assets.js';
+import { type HostUpdateTicket } from './host-updates.js';
+import type { OutputLease } from './lease.js';
+import { type ViteFileEventSource } from './vite-event-source.js';
+export declare class ViteAdapterLifecycle {
+    private readonly lease;
+    private readonly progress?;
+    readonly assets: GeneratedAssetInventory;
+    configuration?: PublishedGeneratorConfiguration;
+    private generationFailure?;
+    get failure(): Error | undefined;
+    private session?;
+    private watch?;
+    private source?;
+    private server?;
+    private registration;
+    private disposal?;
+    private hostFailure?;
+    private disposed;
+    private latestStarted;
+    private readonly hostUpdates;
+    /**
+     * The snapshot of the newest committed success: the generated modules on disk import the
+     * description modules it read. `read` is computed on demand, once per snapshot.
+     */
+    private committed?;
+    /**
+     * @param progress NgDoc's terminal progress: `interrupt` clears its live line before the adapter
+     *   logs, and `release` follows each watch result the adapter has logged (or skipped), so the
+     *   result's progress line comes after the diagnostics it counts. A result the adapter failed to
+     *   publish or reconcile is released as failed, so its line is the failure line.
+     */
+    constructor(lease: OutputLease, progress?: {
+        interrupt(): void;
+        release(generation: number, failed?: boolean): void;
+    } | undefined);
+    attachSession(session: BuildSession): void;
+    attachServer(server: ViteDevServer, source: ViteFileEventSource): void;
+    attachWatch(watch: WatchHandle): void;
+    acceptInitial(result: BuildResult): Extract<BuildResult, {
+        status: 'success';
+    }>;
+    /** Runs synchronously inside the candidate committer, before it mutates published output. */
+    admit(configuration: Readonly<PublishedGeneratorConfiguration>): void;
+    publish(result: Extract<BuildResult, {
+        status: 'success';
+    }>, configuration: PublishedGeneratorConfiguration): void;
+    /**
+     * Records a committed success (published or not), unless a newer one is recorded already.
+     * @param result The committed result.
+     */
+    private committedResult;
+    /**
+     * Whether the newest committed generation read the description module `file`, so that a
+     * generated module (its page shell, `routes.ts`) may import it.
+     * @param file An absolute path.
+     */
+    private committedDescriptionModule;
+    hostUpdateStarted(file: string, type: 'create' | 'update' | 'delete', read: () => string | Promise<string>): HostUpdateTicket;
+    hostUpdateCompleted(ticket: HostUpdateTicket): Promise<void>;
+    /** The adapter reloads for this settled hot update itself. */
+    hostUpdateAnnounced(read: object): boolean;
+    /** See {@link HostUpdateCoordinator.compilerCompanions}. */
+    hostUpdateCompanions(ticket: HostUpdateTicket): string[];
+    /**
+     * Whether the Angular compiler leaves the add or unlink event of `file` to the pass of the
+     * generation it belongs to (see `composeAngularPlugins`):
+     *
+     * - a generated output: a commit creates or deletes it, and rewrites the module that imports it
+     *   (`routes.ts`, a page shell) in the same commit, whose update takes the generation's pass;
+     * - a description module (`ng-doc.page.ts`, `ng-doc.category.ts`, `ng-doc.api.ts`) the
+     *   generator watches, unless the newest committed generation read it and it exists. A new one
+     *   is imported by no generated module before its generation commits, and that commit rewrites
+     *   `routes.ts`; a deleted one cannot be compiled, and the commit that drops it rewrites the
+     *   modules that imported it. An existing one the committed generation read is in the program:
+     *   its page shell imports it (`page.ts.nunj`), and an add event that replaced it (an editor's
+     *   atomic save, a checkout) may change it without changing any generated module, so its own
+     *   pass compiles it as before. The file is checked when the event arrives: a file deleted
+     *   again since is claimed, and one restored since compiles, either way from its current bytes.
+     *
+     * A claimed file is not compiled on its own: it joins the next pass, which would otherwise
+     * follow the one its event starts. If its generation fails or rewrites no generated module, the
+     * file still waits for that next pass: a new one is imported by no generated module, and a
+     * deleted one has no bytes left to serve.
+     * @param file The added or deleted file, as Vite's watcher reports it.
+     */
+    hostClaimsFilesystemChange(file: string): boolean;
+    /** See {@link HostUpdateCoordinator.diagnosticMark}. */
+    hostDiagnosticMark(): number;
+    initialCompilationInventory(): import("./host-updates.js").InitialCompilationInventory;
+    hostUpdateAcknowledged(ticket: HostUpdateTicket, resourceWitness?: boolean, compilerPass?: boolean, recoverBefore?: number): Promise<void>;
+    hostUpdateDiagnostic(ticket: HostUpdateTicket, error: Error): void;
+    hostUpdateSettled(ticket: HostUpdateTicket): Promise<void>;
+    hostUpdateCommitted(ticket: HostUpdateTicket): Promise<void>;
+    hostUpdateFailed(error: Error): void;
+    observer(configurationOf: (result: BuildResult) => PublishedGeneratorConfiguration | undefined): (event: BuildEvent) => void;
+    settled(): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * The generation just published recorded inputs that the watcher did not cover while it read
+     * them. Once their watches are attached, only those paths are re-observed against what the
+     * session last observed, and a difference becomes an ordinary filesystem change. So the
+     * retained program is kept, and no generation, which would also hold back this generation's
+     * reload, runs when nothing changed. After a rejection overflow the rejected paths are unknown,
+     * so the session rescans: its next generation re-observes every committed input, as after a
+     * lossy watcher, and takes the full commit. Neither call waits for a generation; its result
+     * arrives through the observer like any other.
+     */
+    private reconcile;
+    private fail;
+    private report;
+    private isCurrent;
+    private log;
+    private interrupt;
+    private logAll;
+    private disposeAll;
+}

package/generator/vite/mime.d.ts

@@ -0,0 +1,2 @@
+/** The content type of a file by its extension; `application/octet-stream` when unknown. */
+export declare function contentType(file: string): string;

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

@@ -0,0 +1,44 @@
+import { type FSWatcher } from 'node:fs';
+import type { FileChange } from '../contracts.js';
+/**
+ * At most this many directories are watched for missing inputs. The inputs are grouped by their
+ * nearest existing directory, so thousands of missing paths (module resolution and configuration
+ * lookups) cost one watch per directory. Inputs beyond it are reported to the owner, which keeps
+ * them native and warns.
+ */
+export declare const MAX_MISSING_PATH_DIRECTORIES = 1024;
+type Watch = (directory: string, listener: (event: string, name: string | null) => void) => FSWatcher;
+/**
+ * Reports the creation, change and removal of inputs that chokidar's `fs.watch` backend cannot
+ * report (see `watchesMissingPaths` in `vite-event-source.ts`). Each input is watched through a
+ * non-recursive watch of its nearest existing directory, which one watch shares among all the
+ * inputs below it. An event there re-reads the state of the inputs it names (all of them when the
+ * platform names none) and reports each one whose state changed. A new directory on an input's
+ * path moves the input to it; a removed one moves it back up.
+ */
+export declare class MissingPathWatcher {
+    private readonly emit;
+    private readonly maxDirectories;
+    private readonly watch;
+    private readonly states;
+    private readonly anchors;
+    private readonly members;
+    private readonly handles;
+    private disposed;
+    constructor(emit: (change: FileChange) => void, maxDirectories?: number, watch?: Watch);
+    get size(): number;
+    /** The number of watched directories. */
+    get directories(): number;
+    has(target: string): boolean;
+    /**
+     * Starts watching `targets` and returns the ones that did not fit in the directory budget. The
+     * state of each is taken now, so a change after this call is reported.
+     */
+    add(targets: readonly string[]): string[];
+    dispose(): void;
+    private attach;
+    private detach;
+    private changed;
+    private refresh;
+}
+export {};

package/generator/vite/options.d.ts

@@ -0,0 +1,87 @@
+import type { Alias, Plugin, UserConfig } from 'vite';
+import { type GeneratorBootstrapOptions } from '../bootstrap/index.js';
+import type { PublishedGeneratorConfiguration } from '../contracts.js';
+import { type ProgressOptionSetting } from '../progress/settings.js';
+export declare const DEFAULT_GENERATED_ALIAS = "@ng-doc/generated";
+export declare const GENERATED_STAGE_IGNORE = "**/.ng-doc-stage-*/**";
+export interface NgDocVitePluginOptions {
+    generator: GeneratorBootstrapOptions;
+    /**
+     * Confirms that the following Analog Angular plugin is configured with `liveReload: true`.
+     * The completion companion relies on Analog awaiting TypeScript compilation in that mode.
+     */
+    analogLiveReload: true;
+    /** The complete array from createNgDocAngularPlugins in the built generator/vite/angular entry. */
+    angularPlugins: readonly Plugin[];
+    /** Absolute path to a real, always-present Angular application component. */
+    angularComponentProbe: string;
+    generatedAlias?: string;
+    maxExternalWatchTargets?: number;
+    /** Explicit browser module specifiers for non-default published theme names. */
+    themeModules?: Readonly<Record<string, string>>;
+    /**
+     * Generation progress in the terminal: `auto` (default), `live`, `plain`, `verbose`, `summary`
+     * or `off`. `NGDOC_PROGRESS` overrides it; Vite `logLevel` `warn`, `error` or `silent` turns
+     * progress off unless it or the environment variable asks for it.
+     */
+    progress?: ProgressOptionSetting;
+}
+export interface ResolvedNgDocViteOptions {
+    generator: GeneratorBootstrapOptions;
+    generatedAlias: string;
+    maxExternalWatchTargets: number;
+    themeModules: Readonly<Record<string, string>>;
+    leaseIdentity: string;
+    angularPlugins: readonly Plugin[];
+    angularComponentProbe: string;
+    progress?: ProgressOptionSetting;
+}
+export declare function resolveOptions(options: NgDocVitePluginOptions): ResolvedNgDocViteOptions;
+/**
+ * The generator options of one session with its build tags (`onlyForTags` of pages and
+ * categories). Explicit `generator.discovery.tags` win; otherwise the only tag is the Vite mode:
+ * `development` for the dev server and `production` for `vite build`, unless `--mode` names
+ * another one.
+ */
+export declare function generatorWithTags(generator: GeneratorBootstrapOptions, viteMode: string): GeneratorBootstrapOptions;
+export declare function generatedAlias(options: ResolvedNgDocViteOptions, configuration: PublishedGeneratorConfiguration): Alias;
+export declare function themeImports(options: ResolvedNgDocViteOptions, configuration?: PublishedGeneratorConfiguration): string[];
+/**
+ * The generator cache is written only by the committer and read only by the compiler; Vite never
+ * serves or imports it, and the event source already drops owned-root events. Watching it only
+ * costs a filesystem event, a directory scan and hot-update hooks per cache write.
+ *
+ * It is ignored only while it cannot contain anything Vite must observe: not the Vite root, the
+ * workspace, the docs or tsconfig directory, and not the output root. The config-time defaults
+ * are checked first; the resolved Vite root (`confirmRoot`) and the published configuration
+ * (`admit`, before the committer writes) are re-checked later. A failed check fails open: the
+ * matcher stops ignoring anything, and the caller re-adds the cache root to the watcher.
+ */
+export declare class CacheRootWatchIgnore {
+    private readonly options;
+    readonly cacheRoot?: string;
+    private active;
+    constructor(options: ResolvedNgDocViteOptions);
+    get ignoring(): boolean;
+    /** The watcher matcher for a Vite root, or undefined when the cache must stay watched. */
+    matcher(viteRoot: string): ((file: string) => boolean) | undefined;
+    /** Re-checks the finally resolved Vite root (a later plugin can change `root`). */
+    confirmRoot(viteRoot: unknown): boolean;
+    /**
+     * Re-checks the published configuration before its first physical write. Returns true when
+     * this call stopped ignoring the cache root.
+     */
+    admit(configuration: Readonly<PublishedGeneratorConfiguration>): boolean;
+    private guard;
+}
+/**
+ * IDE and OS metadata that NgDoc never reads but editors rewrite constantly: the workspace root's
+ * JetBrains `.idea/` directory and macOS Finder `.DS_Store` files. NgDoc's recorded inputs are
+ * TypeScript sources, `ng-doc.{page,category,api}.ts` descriptions and the files they include,
+ * never these. It stays off when a configured root (Vite root, docs, output, tsconfig directory)
+ * lies inside that `.idea/` directory. `.vscode/` is not ignored: VS Code keeps its frequently
+ * written state outside the workspace, so ignoring it would save nothing.
+ */
+export declare function metadataWatchIgnore(options: ResolvedNgDocViteOptions, viteRoot: string): ((file: string) => boolean) | undefined;
+export declare function staticViteConfig(options: ResolvedNgDocViteOptions, viteRoot?: string, cacheWatch?: CacheRootWatchIgnore): UserConfig;
+export declare function assertThemeModules(options: ResolvedNgDocViteOptions, configuration: PublishedGeneratorConfiguration): void;

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

@@ -0,0 +1,41 @@
+import type { FSWatcher } from 'vite';
+/**
+ * How long the development host waits for the watcher to list every directory of the output root
+ * before its watch starts. After this the watch starts anyway, with a warning: an output the
+ * watcher does not list is never reported.
+ */
+export declare const OUTPUT_WATCH_ATTACH_TIMEOUT_MS = 10000;
+/**
+ * Makes the Vite watcher report every change of the generated output.
+ *
+ * The host update coordinator expects a Vite hot update for every generated module a commit
+ * creates, rewrites or deletes, and settles an edit only once they all arrived. Vite watches its
+ * root recursively, but a file outside it only once Vite has served it. An output root outside
+ * the Vite root (the documentation site's `apps/ng-doc/src` root with its output in `ng-doc/`)
+ * therefore reported only the modules the browser had loaded: a new page
+ * tab, a new page or an edit of a page nobody opened never produced its hot update, and the edit
+ * failed with `NGDOC_VITE_HOST_TIMEOUT`. Such a root is added to the watcher here, and startup
+ * waits until the output is watched, because chokidar ignores initial files: a file written while
+ * it still scans a directory would be taken as initial and never reported.
+ *
+ * chokidar lists a directory in `getWatched()` before it has read it, and its `fs.watch` backend
+ * (Linux, Windows) attaches the directory's native watch only after that read. So the output
+ * counts as watched once every directory of the published output (`files`, relative to the root)
+ * lists each of its published entries (the read is done), and `WATCH_ATTACH_GRACE_MS` later.
+ *
+ * An output root inside the Vite root is watched by Vite's recursive watch, but the initial commit
+ * ran while chokidar still scanned that root. With the `fs.watch` backend a file published between
+ * a directory's read and its watch is neither listed nor ever reported (only FSEvents, on macOS,
+ * watches the whole tree at once). Each published directory whose entries the watcher does not all
+ * list yet is therefore added again: chokidar reads it once more and takes what it finds as
+ * initial (or, while a read of it still runs, reads it again after that one), and the same wait
+ * follows.
+ *
+ * Resolves `watched` once the output is watched (at once when the watcher cannot list what it
+ * watches), `timeout` after `timeoutMs` (the caller warns), and `disposed` as soon as `disposed()`
+ * is true.
+ */
+export declare function watchOutputRoot(watcher: FSWatcher, viteRoot: string, outputRoot: string, files: readonly string[], options?: {
+    timeoutMs?: number;
+    disposed?: () => boolean;
+}): Promise<'watched' | 'timeout' | 'disposed'>;

package/generator/vite/paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A Windows path with an upper-case drive letter. The drive letter is case-insensitive, and its
+ * spellings meet in the Vite host: the engine publishes realpaths (`C:/…`), while Vite's root and
+ * watcher follow the working directory as the shell reported it (a terminal may give `c:\…`).
+ * Other paths are returned unchanged, so this is a no-op outside Windows.
+ */
+export declare function canonicalDrive(file: string): string;

package/generator/vite/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+import { type NgDocVitePluginOptions } from './options.js';
+export declare function createPlugin(options: NgDocVitePluginOptions): Plugin[];