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

package/generator/bootstrap/constants.d.ts

@@ -0,0 +1,4 @@
+/** Replaced from release metadata by the package build. Kept immutable at runtime. */
+export declare const GENERATOR_COMPILER_VERSION: "0.0.1-t11";
+/** Cache provenance for the initial ESM generator toolchain. */
+export declare const GENERATOR_TOOLCHAIN_DIGEST: "generator-esm-node24-v1";

package/generator/bootstrap/index.d.ts

@@ -0,0 +1,111 @@
+import type { BuildSession, DiscoveryRequest, PublishedGeneratorConfiguration } from '../contracts.js';
+import type { DiscoveryOptions } from '../discovery/index.js';
+import { type SessionOptions } from '../session/build-session.js';
+import { type PersistentWorkerOptions } from '../worker/index.js';
+export type { CandidateOutputCommitterHostOptions, CandidateOutputCommitterOptions, } from './candidate-output-committer.js';
+export { createCandidateOutputCommitter } from './candidate-output-committer.js';
+export { GENERATOR_COMPILER_VERSION, GENERATOR_TOOLCHAIN_DIGEST } from './constants.js';
+export interface GeneratorBootstrapOptions {
+    projectId: string;
+    workspaceRoot: string;
+    configFile?: string;
+    defaults: DiscoveryRequest['defaults'];
+    discovery?: DiscoveryOptions;
+    templateRoot?: string;
+    compilerVersion?: string;
+    toolchainDigest?: string;
+    /**
+     * Development content is always committed as physical files, so `'file'` is the only accepted
+     * value and the option can be omitted. The former virtual content mode (`'virtual'`) was removed
+     * and is rejected with `NGDOC_DEVELOPMENT_CONTENT_REMOVED`.
+     */
+    developmentContent?: 'file';
+    worker?: {
+        moduleUrl?: string | URL;
+        workerEntryUrl?: URL;
+        startupTimeoutMs?: number;
+        compileTimeoutMs?: number;
+        maxPendingRequests?: number;
+        /**
+         * Development watch generations share one long-lived compiler worker per watch session;
+         * production and a development buildOnce during or after a watch fork a fresh one-shot worker
+         * (a development buildOnce before the first watch runs in the long-lived one while priming is
+         * on, see below). `false`, or the environment variable `NGDOC_PERSISTENT_WORKER=0` (also
+         * `false`, `off`, `no`), forces a fresh worker for every development generation too. Defaults
+         * to enabled with the `PersistentWorkerOptions` defaults (1.5 s abort grace, recycle after 50
+         * generations or above 3 GiB resident).
+         *
+         * Priming (`PersistentWorkerOptions.prime`, default on): the development buildOnce before the
+         * first watch runs in the long-lived worker, and when the watch reuses it as its verified
+         * baseline, the session asks that worker to warm up while idle, so the first edit already finds
+         * a retained TypeScript program. A worker that compiled the baseline returns at once; otherwise
+         * it compiles the baseline once more (about one generation of CPU; a real change supersedes
+         * it).
+         * It never runs without the persistent worker, so the kill switch above also turns it off.
+         * `persistent: { prime: false }`, or `NGDOC_PERSISTENT_WORKER_PRIME=0` (also `false`, `off`,
+         * `no`), turns off only the priming.
+         *
+         * Delta transport (`PersistentWorkerOptions.delta`, default on): the long-lived worker keeps
+         * the committed snapshot, so a watch generation sends only its changes and base revision and
+         * receives only the changed artifacts, which the session applies to its snapshot without full
+         * copies; the worker promotes a candidate to its base only after the session committed it. Any
+         * disagreement falls back to a resync with the full snapshot. It needs the persistent worker.
+         * `persistent: { delta: false }`, or `NGDOC_DELTA_TRANSPORT=0` (also `false`, `off`, `no`),
+         * keeps the full transport; `NGDOC_DELTA_TRANSPORT=verify` checks every delta against the full
+         * candidate (diagnosis only).
+         */
+        persistent?: boolean | PersistentWorkerOptions;
+    };
+    session?: SessionOptions;
+}
+/** Environment kill switch for the persistent development worker (see `worker.persistent`). */
+export declare const PERSISTENT_WORKER_ENV = "NGDOC_PERSISTENT_WORKER";
+/** Environment opt-out of priming the persistent development worker (see `worker.persistent`). */
+export declare const PERSISTENT_WORKER_PRIME_ENV = "NGDOC_PERSISTENT_WORKER_PRIME";
+/** Environment kill switch (and `verify` mode) of the delta transport (see `worker.persistent`). */
+export declare const DELTA_TRANSPORT_ENV = "NGDOC_DELTA_TRANSPORT";
+/**
+ * Environment kill switch of the targeted rebuild: `0`/`false`/`off`/`no` turn it off;
+ * `1`/`true`/`on`/`yes`, `verify` and unset leave it on; any other value is reported once
+ * (`NGDOC_TARGETED_REBUILD_VALUE`) and leaves it on.
+ *
+ * - On: a development watch generation whose changes are all content edits compiles only the
+ *   units they reach (the compiler's `targetedRebuild` option, passed as a factory option), and
+ *   only such a generation's commit is a delta commit. Every other commit is the full commit.
+ * - Off: every generation is the full generation and every commit the full commit
+ *   (`targetedRebuild: false`, `OutputCommitterOptions.delta: false`).
+ * - `verify`: as on, and every targeted generation is also compiled in full; the two results are
+ *   compared byte for byte (`targetedRebuild: 'verify'`). On a difference the full result is
+ *   published and the difference is reported as a `COMPILATION_TARGETED_MISMATCH` process warning
+ *   (`WorkerCompilationService.targetedDryRun()` counts them), since the worker's output is not
+ *   forwarded: it returns each generation's record with its reply.
+ *   `NGDOC_TARGETED_REBUILD_TRACE=<file>` also appends every record to that file.
+ *
+ * The targeted rebuild needs a retained program, so it runs only in the long-lived development
+ * worker: with `NGDOC_PERSISTENT_WORKER=0` every generation is one-shot and full.
+ */
+export declare const TARGETED_REBUILD_ENV = "NGDOC_TARGETED_REBUILD";
+/**
+ * Environment kill switch of parallel output writes: `0`/`false`/`off`/`no` turn them off;
+ * `1`/`true`/`on`/`yes` and unset leave them on; any other value is reported once
+ * (`NGDOC_PARALLEL_WRITES_VALUE`) and leaves them on.
+ *
+ * - On: a commit stages its changed outputs and takes the backup copies of the outputs it
+ *   replaces concurrently, then publishes them one rename at a time in the sequential order, the
+ *   manifest last (`OutputCommitterOptions.parallelWrites`).
+ * - Off: every staging write, backup and publication runs one output at a time, as before
+ *   (`parallelWrites: false`). The published files and manifest are the same either way.
+ */
+export declare const PARALLEL_WRITES_ENV = "NGDOC_PARALLEL_WRITES";
+/** In-process policy hooks. These values are intentionally excluded from worker options. */
+export interface GeneratorHostOptions {
+    admitConfiguration?: (configuration: Readonly<PublishedGeneratorConfiguration>) => void;
+}
+/**
+ * Rejects every `developmentContent` value except `'file'` or none. The removed virtual content
+ * mode gets the coded `NGDOC_DEVELOPMENT_CONTENT_REMOVED` migration error. Hosts call it while
+ * they resolve their options, so the error is reported before any generator work starts.
+ */
+export declare function assertDevelopmentContent(value: unknown): void;
+/** Composes the existing worker, BuildSession, and transactional publication authority. */
+export declare function createGeneratorBuildSession(options: GeneratorBootstrapOptions, host?: GeneratorHostOptions): BuildSession;