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

package/generator/artifacts/index.d.ts

@@ -0,0 +1,317 @@
+import { rename, writeFile } from 'node:fs/promises';
+import type { ArtifactCache, CacheKey, CommitGuard, CommitRequest, CommitResult, OutputCommitter, OutputManifest, PageArtifact, PublishedGeneratorConfiguration } from '../contracts.js';
+/** Bounded backoff for transient Windows rename failures: at most about 3.5 s per rename. */
+export declare const RENAME_RETRY: Readonly<{
+    attempts: 8;
+    delayMs: 50;
+    maxDelayMs: 1000;
+}>;
+export interface RenameRetryOptions {
+    /** @internal Test port; `process.platform` by default. */
+    platform?: NodeJS.Platform;
+    /** @internal Test port. */
+    sleep?: (milliseconds: number) => Promise<void>;
+    retry?: {
+        attempts: number;
+        delayMs: number;
+        maxDelayMs: number;
+    };
+}
+/**
+ * `rename`, retried on win32 while it fails with EPERM, EBUSY or EACCES, with a bounded
+ * exponential backoff; the last failure is thrown. Each call still renames exactly once when it
+ * succeeds, so callers keep their order (the committer publishes the manifest last). Other
+ * platforms get `rename` itself.
+ */
+export declare function retryingRename(renameFile?: typeof rename, options?: RenameRetryOptions): typeof rename;
+export interface ArtifactCacheOptions {
+    root: string;
+}
+/**
+ * Identity of one published cache entry file (device, inode, size, mtime, ctime) and the clock
+ * reading taken before that lstat. Only a settled stamp (mtime and ctime at least the racy
+ * window older than `observedNs`) is trusted without reading the file.
+ */
+export interface FileStamp {
+    dev: string;
+    ino: string;
+    size: string;
+    mtimeNs: string;
+    ctimeNs: string;
+    observedNs: string;
+}
+export declare class JsonArtifactCache implements ArtifactCache {
+    private readonly root;
+    constructor(options: ArtifactCacheOptions);
+    read(key: CacheKey): ReturnType<ArtifactCache['read']>;
+    write(artifact: PageArtifact): Promise<void>;
+    /**
+     * Writes exactly like `write` and returns the stamp of the entry file it published, or
+     * undefined when the published path is no longer the inode this call wrote.
+     */
+    writeStamped(artifact: PageArtifact): Promise<FileStamp | undefined>;
+    /**
+     * Confirms that the entry file for `artifact` still holds exactly the bytes `write` would
+     * publish, given the stamp recorded when it was written or last confirmed. A settled
+     * matching stamp is trusted; a racy one (changed within the racy window of its stat) is
+     * confirmed by reading and comparing the bytes. Returns the stamp to keep, or undefined when
+     * the entry must be written.
+     */
+    confirm(artifact: PageArtifact, stamp: FileStamp): Promise<FileStamp | undefined>;
+    /**
+     * Stamps `file` if it is a regular file whose `fields` equal `expected`. `observedNs` must be
+     * a clock reading taken before the bytes being vouched for were written or compared. A file
+     * that cannot be observed (for example removed after the rename) gets no stamp; the write
+     * itself has already succeeded.
+     */
+    private stamp;
+    private fileFor;
+}
+export type CommitMutation = 'stage-write' | 'backup-output' | 'publish-output' | 'remove-output' | 'backup-manifest' | 'publish-manifest';
+export interface OutputCommitterOptions {
+    outputRoot: string;
+    /** Fault-injection/telemetry port. The real filesystem operation still follows this hook. */
+    beforeMutation?: (operation: CommitMutation, target: string) => void | Promise<void>;
+    fileSystem?: {
+        rename?: typeof rename;
+        /** @internal Test port: the copy that backs a published file up (see `backUp`). */
+        copyFile?: (from: string, to: string) => Promise<void>;
+        writeFile?: typeof writeFile;
+        /**
+         * @internal Test port: the platform whose rename behaviour applies (win32 retries transient
+         * rename failures, see {@link retryingRename}); `process.platform` by default.
+         */
+        platform?: NodeJS.Platform;
+        /** @internal Test port: the wait between rename retries. */
+        sleep?: (milliseconds: number) => Promise<void>;
+    };
+    /**
+     * Delta commit; on unless `false`. A request whose `base` is the manifest this committer
+     * published in its previous call prepares, probes and compares only the artifacts that changed
+     * against it, and the outputs a commit publishes stay verified after publication. `false` (the
+     * `NGDOC_TARGETED_REBUILD=0` kill switch, resolved in bootstrap) ignores `base`: every commit is
+     * the full commit, with no publication recorded.
+     */
+    delta?: boolean;
+    /**
+     * Parallel writes; on unless `false`. A commit stages its changed outputs and takes the backup
+     * copies of the outputs it replaces concurrently, at most {@link WRITE_CONCURRENCY} at a time,
+     * and still publishes them one rename at a time in the sequential order, the manifest last.
+     * `false` (the `NGDOC_PARALLEL_WRITES=0` kill switch, resolved in bootstrap) writes, copies and
+     * publishes one output at a time, as before.
+     */
+    parallelWrites?: boolean;
+}
+/**
+ * Why a commit ran the full path while delta commits are on. `untrusted`: this committer has no
+ * publication that the previous call left it (its first commit, or the previous call did not end
+ * `committed`); `base-identity`: `base`/`previous` do not name that publication;
+ * `manifest-stamp`: the published manifest file changed on disk; `configuration`: the candidate's
+ * configuration differs; `candidate`: a check of the changed artifacts would fail (the full commit
+ * reports it); `targets`: a target of a changed artifact or orphan cannot be committed as probed,
+ * or planning the delta commit failed.
+ */
+export type FullCommitReason = 'no-base' | 'untrusted' | 'base-identity' | 'manifest-stamp' | 'configuration' | 'candidate' | 'targets';
+/** How the last commit call ran; for tests and diagnostics only. */
+export interface CommitTelemetry {
+    mode: 'full' | 'delta';
+    /** Set when delta commits are on and this commit ran the full path. */
+    reason?: FullCommitReason;
+    /** Candidate artifacts prepared and validated: all of them (full) or the changed ones. */
+    artifacts: number;
+    /** Outputs probed and compared with the disk. */
+    outputs: number;
+}
+/**
+ * The most staging writes, directory creations or backup copies one commit has in flight (parallel
+ * writes). Node runs them on its libuv thread pool (four threads unless `UV_THREADPOOL_SIZE` says
+ * otherwise), so a few more than its threads keep it busy, and the bound keeps a commit of
+ * thousands of outputs from queueing them all ahead of the host's own file reads.
+ */
+export declare const WRITE_CONCURRENCY = 16;
+export declare class TransactionalOutputCommitter implements OutputCommitter {
+    private readonly outputRoot;
+    private readonly hook?;
+    private readonly renameFile;
+    private readonly copyBackup;
+    /** The rollback's rename: the real one, never the injected port, with the same retries. */
+    private readonly restoreFile;
+    private readonly platform;
+    private readonly write;
+    private readonly delta;
+    private readonly parallel;
+    private active?;
+    private disposed;
+    /**
+     * Outputs whose on-disk bytes were compared equal to their digest. A later commit skips
+     * reading an output whose digest is unchanged while its lstat identity (device, inode,
+     * size, mtime, ctime) still matches; any other output is read and compared as before.
+     */
+    private readonly verified;
+    /** The publication of the previous call, if it ended `committed` (delta commits only). */
+    private published?;
+    /** Commit calls so far; a publication is recorded only by the newest call. */
+    private calls;
+    private telemetry?;
+    constructor(options: OutputCommitterOptions);
+    commit(request: CommitRequest, guard: CommitGuard, signal: AbortSignal): Promise<CommitResult>;
+    /** How the last commit call ran, if it reached a plan (tests and diagnostics). */
+    inspect(): CommitTelemetry | undefined;
+    dispose(): Promise<void>;
+    private runCommit;
+    /**
+     * The probe of a plan's targets: every segment is checked as `assertSafeTarget` would, and an
+     * existing target that the previous manifest does not own is an unowned collision.
+     */
+    private checkTargets;
+    private prepare;
+    private ensureSafeRoot;
+    private assertSafeTarget;
+    /**
+     * The read-only half of the full commit's per-output loop, concurrently: whether each output is
+     * unchanged since it was verified, else its safety check (`assertSafeTarget`) and the comparison
+     * of its bytes. A large site has thousands of outputs, and one at a time those lstat, realpath
+     * and read calls made a restart that writes nothing wait on the filesystem for seconds.
+     *
+     * Nothing here writes or records anything: the caller applies the outcomes in plan order, so
+     * staging, the verified stats and the first failure are exactly those of the sequential loop (a
+     * later output's failure is never reported before an earlier output's). An output whose check
+     * did not run (the generation stopped being current) is checked by the caller as before.
+     */
+    private checkOutputs;
+    /**
+     * Observes every path segment under the root once, concurrently.
+     */
+    private probe;
+    /** `assertSafeTarget` over probed segments: the same checks, order and messages. */
+    private checkProbedTarget;
+    private unchangedSinceVerified;
+    private rememberVerified;
+    private readManifest;
+    /**
+     * The delta commit's plan, or why the full commit runs instead. It mutates nothing, and it
+     * returns a plan only when the full commit would reach the same transaction: the base is the
+     * publication this committer made in its previous call and still on disk (manifest stamp); the
+     * configuration is unchanged; the changed artifacts and the top level pass the full path's
+     * checks; and every target of a changed artifact and every orphan passes the probe. Anything
+     * else, including an error, runs the full commit, which then reports any failure exactly as
+     * before.
+     */
+    private deltaAttempt;
+    /**
+     * `prepare` for the changed artifacts only, or undefined when the full commit must decide.
+     * Unchanged artifacts (the same id and revision, and outputs equal to the published ones) keep
+     * their published manifest entries; the manifest is the published one minus the entries of
+     * removed or changed artifacts plus the changed artifacts' outputs, in the full path's order.
+     */
+    private prepareDelta;
+    /**
+     * Post-publish verification: the stat of each file this commit published is recorded instead of
+     * forgotten, but only while the target is provably still the file this commit wrote:
+     * - the target right after the rename had the staged file's device, inode, size and mtime (a
+     *   rename keeps them; a replacement changes the inode);
+     * - the target now has that same stat, including the ctime taken right after the rename (an
+     *   in-place rewrite changes the ctime even when it restores the mtime, as `touch -r` does);
+     * - the timestamps are finer than whole seconds (on a coarse filesystem a rewrite within the
+     *   same tick leaves every timestamp unchanged, so nothing is recorded there).
+     * `rememberVerified` keeps its racy-window rule, so a file is trusted only when it was
+     * published at least that window before its stat; a file published later would be dropped by
+     * that rule anyway and is not observed at all.
+     */
+    private rememberPublished;
+    /**
+     * The stamp of `file` if it is still the file whose staged stat is `staged`. None on a
+     * filesystem with whole-second timestamps: there an in-place rewrite of the manifest within the
+     * same tick would keep the stamp, so such a committer always takes the full path.
+     */
+    private publishedStamp;
+    /** What the next call may use as its delta base: this commit's manifest, as published. */
+    private publication;
+    private manifestStamp;
+    /**
+     * For each output below a directory that does not exist yet, the outermost such directory
+     * (relative to the output root), unless one of its outputs is published late (routes, context,
+     * search): the directory would publish it early. Those outputs, and every other, are published
+     * one by one.
+     * @param order The changed outputs, in publication order.
+     */
+    private newDirectories;
+    /**
+     * Parallel writes: stages the changed outputs concurrently, first the directories they need in
+     * the stage, then their files, at most {@link WRITE_CONCURRENCY} at a time. Every write lands
+     * inside the stage, which hosts do not watch (`GENERATED_STAGE_IGNORE`) and which nothing reads
+     * before its publish renames, so the order of the writes is not observable. A failure, a stale
+     * guard or an abort starts no further write and waits for the writes in flight (`runBounded`),
+     * so nothing is still writing when the rollback removes the stage.
+     * @param changed The changed outputs, in plan order.
+     * @param stagedOutputs The stage's output tree.
+     * @param generation The generation the guard must still accept.
+     * @param guard The commit guard.
+     * @param signal The commit's signal.
+     */
+    private stage;
+    /**
+     * Parallel writes: the backups of the outputs published one by one, taken concurrently (at most
+     * {@link WRITE_CONCURRENCY} at a time) before the first publish rename, keyed by output.
+     *
+     * A backup copies its output and leaves it untouched (see `backUp`), so taking it early changes
+     * nothing a reader or watcher of the output root sees, and the publish renames that follow keep
+     * their order. Until an output is published, the rollback has no record of it, so a failure here
+     * or before its turn leaves it in place and its copy goes with the stage. Where the copy fails
+     * with a file system error, its partial file is removed and the output gets no identity: its
+     * publication moves it away right before its rename, as `backUp` does, so the gap of that
+     * fallback is as short as without parallel writes. A copy error without a code is thrown.
+     * @param items The outputs published one by one, in publication order.
+     * @param backups The stage's backup tree.
+     * @param generation The generation the guard must still accept.
+     * @param guard The commit guard.
+     * @param signal The commit's signal.
+     */
+    private backUpAll;
+    /**
+     * Parallel writes: publishes the new directory `directory` whole, as the sequential loop does
+     * (one rename of its staged copy, each member's `publish-output` hook first, in order), with the
+     * stats of delta commits taken concurrently: every staged file's before the rename, then the
+     * clock, which the rename follows, then every published file's right after it.
+     * @param members The outputs below the directory, in publication order.
+     * @param stagedOutputs The stage's output tree.
+     * @param directory The directory, relative to the output root.
+     * @param published The delta commit's record of published outputs.
+     * @param signal The commit's signal.
+     */
+    private publishDirectory;
+    /**
+     * Keeps the published file `target` at `backup` for the rollback, leaving `target` in place and
+     * untouched: a copy, so the publish rename that follows replaces `target` in one step and it never
+     * goes missing. Had it been moved away first, a reader between the two renames (a transform
+     * request) would find no file, and a watcher that stats a file whose inode moved (chokidar's
+     * `fs.watch` backend, the default on Linux) would report the rewrite as a deletion and a creation;
+     * a host waiting for that output's change would wait in vain. Not a hard link either: a link
+     * changes the file's link count, which inotify reports (`IN_ATTRIB`) as a change of the old
+     * bytes, and chokidar then drops the publish's own change within its 50 ms throttle, so the host
+     * never sees the new bytes.
+     *
+     * The copy records the identity of the file it copied: a rollback leaves that very file in place
+     * while the target still is it, and restores the copy's bytes otherwise. Where the copy fails, the
+     * file is moved away instead, which is the protocol without the copy: the rollback restores that
+     * backup by moving it back, so only the gap differs. Any system error falls back, not a list of
+     * codes, because file systems do not agree on them (a full volume, a file another process holds
+     * on Windows, network and FUSE mounts). A copy that took effect although it reported an error is
+     * replaced by the move. Only an error without a code, which no file system call raises, is
+     * rethrown.
+     * @param target A published output or the manifest.
+     * @param backup Its path in the stage's backups.
+     * @param record The target's rollback record, which learns how the backup was taken.
+     */
+    private backUp;
+    private mutate;
+}
+/**
+ * Whether `outputRoot` still publishes exactly `manifest`: its manifest file holds the bytes the
+ * commit of `manifest` wrote. A later commit of any generation or project replaces it.
+ */
+export declare function publishesManifest(outputRoot: string, manifest: OutputManifest): Promise<boolean>;
+export declare function createArtifactCache(root: string): ArtifactCache;
+export declare function createOutputCommitter(options: OutputCommitterOptions): OutputCommitter;
+/** Shared strict boundary for host-visible candidate configuration. */
+export declare function isPublishedGeneratorConfiguration(value: unknown): value is PublishedGeneratorConfiguration;

package/generator/bootstrap/bin.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { runGeneratorCli } from './cli.js';
+/** @internal Process boundary used by the executable and its signal tests. */
+export interface GeneratorBinProcess {
+    argv: string[];
+    exitCode?: string | number;
+    stderr: {
+        write(text: string): unknown;
+    };
+    once(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+type CliRunner = typeof runGeneratorCli;
+export declare function runGeneratorBin(processPort?: GeneratorBinProcess, run?: CliRunner): Promise<number>;
+export declare function isGeneratorBinMain(argv1: string | undefined, moduleUrl: string): boolean;
+/** @internal Converts an unexpected executable-boundary rejection to a joined exit. */
+export declare function runGeneratorBinMain(processPort?: GeneratorBinProcess, run?: CliRunner): Promise<void>;
+export {};