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

package/generator/bootstrap/prerender-command.d.ts

@@ -0,0 +1,31 @@
+import type { GeneratorCliIO } from './cli.js';
+/** The part of the Vite entry (`vite/index.js`) the command uses. */
+export interface PrerenderViteModule {
+    buildNgDocViteApplication(options: {
+        configFile: string;
+        outputPath: string;
+        mode?: string;
+        routes?: readonly string[];
+        routeTimeoutMs?: number;
+        discoverRoutes?: boolean;
+        skipBuild?: boolean;
+        prerender?: boolean;
+        log?: (message: string) => void;
+        signal?: AbortSignal;
+    }): Promise<{
+        prerendered?: {
+            routes: readonly unknown[];
+        };
+    }>;
+}
+type CliRunner = (argv: readonly string[], io?: GeneratorCliIO, signal?: AbortSignal) => Promise<number>;
+export declare const PRERENDER_USAGE = "Usage:\n  ng-doc prerender --vite-config <path> --output-path <path> [options]\n\nBuilds a Vite + NgDoc application for production (the browser and server bundles) and prerenders\nevery route into <output-path>/browser. The Vite configuration must use\ncreateNgDocApplicationPlugin with a server entry. Requires vite and @analogjs/vite-plugin-angular.\n\nOptions:\n  --vite-config <path>   The Vite configuration file\n  --output-path <path>   Output: browser/, server/server.mjs and prerendered-routes.json\n  --mode <mode>          The Vite mode (default: production)\n  --routes <a,b,...>     Routes prerendered in addition to the discovered ones\n  --route-timeout <ms>   Fail a route that takes longer to render (default: no limit)\n  --no-discover          Prerender only the --routes, without enumerating the router configuration\n  --skip-build           Prerender an existing output without building it again\n";
+/**
+ * `ng-doc prerender`: the Vite engine's production build with prerendering.
+ */
+export declare function runPrerenderCommand(argv: readonly string[], io?: GeneratorCliIO, signal?: AbortSignal, load?: () => Promise<PrerenderViteModule>): Promise<number>;
+/**
+ * The `ng-doc` executable's commands: `prerender`, then everything the generator CLI runs.
+ */
+export declare function withPrerenderCommand(run: CliRunner): CliRunner;
+export {};

package/generator/bootstrap/process-tree.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Process supervision on Windows, which has no POSIX process groups: a process is ended together
+ * with every process it started (`taskkill /T`, which follows parent links while they exist), and
+ * a command is resolved the way `cmd.exe` resolves it, because `spawn` without a shell finds only
+ * `.exe` files and Node refuses to start a `.cmd` or `.bat` file without one.
+ */
+/** How `spawn` starts a command on Windows. */
+export interface WindowsSpawnPlan {
+    readonly file: string;
+    readonly args: readonly string[];
+    /** The arguments are one command line for `cmd.exe`, already quoted. */
+    readonly verbatim: boolean;
+}
+export interface WindowsCommandOptions {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    /** The Node that starts `ng`, `npm` and `npx` directly; `process.execPath` by default. */
+    readonly execPath?: string;
+    /** @internal Test port. */
+    readonly isFile?: (file: string) => boolean;
+}
+/**
+ * The file `cmd.exe` would run for `command`: a path is resolved against `cwd`, a bare name
+ * against the working directory and then `PATH`; without an extension, each `PATHEXT` extension is
+ * tried in order. Undefined when nothing matches.
+ */
+export declare function resolveWindowsCommand(command: string, options: WindowsCommandOptions): string | undefined;
+/**
+ * Quotes one argument for `cmd.exe /s /c "…"` and for the program's own command-line parser
+ * (backslashes before a quote doubled, the argument quoted, metacharacters escaped). A batch file
+ * that forwards its arguments to another program (the `node_modules/.bin` shims) parses the line
+ * twice, so its metacharacters are escaped twice. The same rules as the `cross-spawn` package.
+ */
+export declare function quoteWindowsArgument(value: string, twice?: boolean): string;
+/**
+ * The JavaScript entry of `ng`, `npm` or `npx` given as a bare name: the Angular CLI of the
+ * project (the nearest `node_modules/@angular/cli` above `cwd`), and the npm beside `execPath`
+ * (the Windows Node layout). Undefined for any other command, or when the entry is missing.
+ */
+export declare function nodeEntry(command: string, options: WindowsCommandOptions): string | undefined;
+export declare function windowsSpawnPlan(command: string, args: readonly string[], options: WindowsCommandOptions): WindowsSpawnPlan;
+export type ExecFile = (file: string, args: readonly string[], options: {
+    windowsHide: boolean;
+}, callback: (error: Error | null) => void) => unknown;
+/**
+ * Ends `pid` and every process it started (`taskkill /PID <pid> /T /F`). Resolves once taskkill
+ * has finished; a process that is already gone is not an error, the caller checks the exit.
+ */
+export declare function killWindowsProcessTree(pid: number, run?: ExecFile): Promise<void>;