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

package/generator/kernel/footprint.d.ts

@@ -0,0 +1,88 @@
+import type { Dependency } from '../contracts.js';
+export { contentDigest } from './canonical.js';
+export { readText } from './observations.js';
+/**
+ * Recorded footprints: the one recorder of every cross-file read a phase call makes. This leaf
+ * module holds the stage-neutral part (scopes, footprints and the files channel) that the semantic
+ * service and the content compiler share; file reads and their digests come from
+ * `observations.ts`, and the TypeScript channels live in `semantic/recorder.ts`.
+ *
+ * Footprints are attached to phase results out of band (a WeakMap keyed by the result object).
+ * In a scoped development generation the semantic service turns each query's footprint into its
+ * `semantic-closure` dependency (`semantic/semantic-closure.ts`); nothing else reads them.
+ */
+/** The phase calls that each get one recorder scope. */
+export type FootprintScopeKind = 'enumerateApi' | 'describeGuide' | 'renderFragment' | 'entry-doc' | 'content-describe' | 'content-compile' | 'link' | 'capture';
+/** How a file entered `R(scope)`; kept only in verify mode (attribution for tests and gaps). */
+export type FootprintChannel = 'checker' | 'symbol-docs' | 'language-service' | 'lookup' | 'node-factory' | 'merge';
+export interface Footprint {
+    readonly scope: FootprintScopeKind;
+    /** The unit/IR the scope ran for (entry id, declaration id or path, content id). */
+    readonly key: string;
+    /** `R(scope)`: the source files the semantic channels touched, sorted. */
+    readonly files: readonly string[];
+    /** The files channel: every read, probe and glob, as read identities, sorted. */
+    readonly reads: readonly string[];
+    /**
+     * False when part of the call's semantic side recorded nothing (recording off or unavailable for
+     * a query it made, or a nested footprint that is itself incomplete). An incomplete footprint
+     * states no dependency set at all: `files` is then a lower bound, never "depends on nothing".
+     * Scoped semantic invalidation treats it like a unit without a recorded `R`.
+     */
+    readonly complete: boolean;
+    /**
+     * The classes whose derived-class list (the API "See Also" section) the scope read, as
+     * `path#start` identities, sorted. The list depends on heritage clauses anywhere in the program,
+     * which `files` cannot state, so it is part of the scope's semantic closure. Present only when
+     * the scope read one.
+     */
+    readonly derived?: readonly string[];
+    /** Verify mode only: the files each channel recorded. */
+    readonly channels?: Readonly<Partial<Record<FootprintChannel, readonly string[]>>>;
+}
+/** `NGDOC_SEMANTIC_RECORDER`: `0`/`off`/`false`/`no` turns recording off, `verify` adds the gap assertion. */
+export declare const SEMANTIC_RECORDER_ENV = "NGDOC_SEMANTIC_RECORDER";
+export type RecorderMode = 'off' | 'on' | 'verify';
+/** The recorder mode from an explicit value or the environment; recording is on by default. */
+export declare function recorderMode(value?: string | undefined): RecorderMode;
+/** The files-channel identity of a physical dependency; undefined for non-physical kinds. */
+export declare function readIdentity(dependency: Dependency): string | undefined;
+/** One open recorder scope: `R` (files), the files channel (reads) and, in verify mode, gaps. */
+export declare class FootprintScope {
+    readonly kind: FootprintScopeKind;
+    readonly key: string;
+    readonly verify: boolean;
+    readonly files: Set<string>;
+    readonly reads: Set<string>;
+    /** Classes whose derived-class list was read (see {@link Footprint.derived}). */
+    readonly derived: Set<string>;
+    /** Verify mode: per-channel attribution. */
+    readonly channels?: Map<FootprintChannel, Set<string>>;
+    /** Verify mode: hooked reads on nodes whose file was not in `R` when read. */
+    readonly gaps: string[];
+    private incomplete;
+    constructor(kind: FootprintScopeKind, key: string, verify?: boolean);
+    /** Adds a file to `R`. */
+    record(file: string, channel: FootprintChannel): void;
+    /** Adds a class whose derived-class list the scope read. */
+    recordDerived(identity: string): void;
+    /**
+     * Marks the footprint incomplete: the scope made a read whose answer depends on files it cannot
+     * name (a whole-program reference search), so its files are only a lower bound.
+     */
+    unscoped(): void;
+    /** Adds one files-channel observation. */
+    observe(dependency: Dependency): void;
+    /** Adds every files-channel observation of a dependency list. */
+    observeAll(dependencies: readonly Dependency[]): void;
+    /**
+     * Replays a nested or cached footprint into this scope. A missing (`undefined`) or incomplete one
+     * makes this scope incomplete: the call it stands for recorded nothing, or not everything.
+     */
+    merge(footprint: Footprint | undefined): void;
+    seal(): Footprint;
+}
+/** Attaches a footprint to a phase result out of band; the result object is returned unchanged. */
+export declare function attachFootprint<T extends object>(result: T, footprint: Footprint): T;
+/** The footprint recorded for a phase result, if it was produced with recording on. */
+export declare function footprintOf(result: object | undefined): Footprint | undefined;

package/generator/kernel/observations.d.ts

@@ -0,0 +1,68 @@
+import type { Dependency } from '../contracts.js';
+/**
+ * The files recorder shared by discovery and the semantic service: every read, existence probe and
+ * glob a phase makes, recorded as dependencies in the one digest domain (`kernel/canonical.ts`).
+ * The content compiler and the semantic footprints record through {@link readText} as well, so a
+ * path read by several phases always has one digest for the same bytes.
+ */
+/**
+ * The digest recorded for a path that one recorder saw with two different contents: no single
+ * digest describes what was used, so it never verifies and every consumer is recomputed.
+ */
+export declare const CONFLICTING_CONTENT_DIGEST = "conflicting-reads";
+export interface ObservationRecorderOptions {
+    /**
+     * A recorder that also receives everything this one records; this one then keeps its own subset
+     * (for example the configuration's inputs) and shares the parent's bytes.
+     */
+    readonly parent?: ObservationRecorder;
+    /**
+     * Read each file once: every later read returns the same bytes, so all consumers use, and the
+     * recorded digest describes, exactly those bytes. Only for a recorder that lives for one phase
+     * call; a long-lived one would keep serving old bytes.
+     */
+    readonly cacheBytes?: boolean;
+    /** Turns a path into its recorded form; the identity by default. */
+    readonly normalize?: (file: string) => string;
+    /** Receives every observation added after construction (a footprint's files channel). */
+    readonly observer?: (dependency: Dependency) => void;
+}
+/**
+ * A set of dependencies with at most one per identity, listed in code-unit order of the identity.
+ * A later observation of an identity replaces the earlier one, except that two contents of one
+ * path record {@link CONFLICTING_CONTENT_DIGEST}.
+ */
+export declare class ObservationRecorder {
+    private readonly values;
+    private ordered?;
+    private readonly parent?;
+    private readonly bytes?;
+    private readonly normalize;
+    private readonly observer?;
+    constructor(initial?: readonly Dependency[], options?: ObservationRecorderOptions);
+    add(dependency: Dependency): void;
+    /** Records whether the file exists and, when it does, its content. */
+    observeFile(file: string): boolean;
+    /**
+     * Records the file's existence and the digest of exactly the bytes returned. Undefined when the
+     * file does not exist; a read error propagates.
+     */
+    readFile(file: string): Buffer | undefined;
+    /** {@link readFile} decoded as UTF-8; a missing file throws like `readFileSync`. */
+    readText(file: string): string;
+    /** The recorded dependencies, in code-unit order of their identities. */
+    all(): Dependency[];
+}
+/**
+ * A synchronous read decoded as UTF-8 (as `readFileSync(path, 'utf8')`), with the content digest
+ * of its bytes; throws what `readFileSync` throws.
+ */
+export declare function readText(path: string): {
+    text: string;
+    digest: string;
+};
+/** The asynchronous {@link readText}; rejects with what `readFile` rejects with. */
+export declare function readTextFile(path: string): Promise<{
+    text: string;
+    digest: string;
+}>;

package/generator/kernel/paths.d.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+/**
+ * The path rules of the platform a path belongs to. Production code always uses the running
+ * platform's (`node:path`); tests pass `path.win32` to check Windows spellings on any host.
+ */
+export type PathRules = Pick<typeof path, 'resolve'>;
+/**
+ * The engine's spelling of a host path: absolute, resolved and with forward slashes, so
+ * `D:\a\docs\page.md` is recorded as `D:/a/docs/page.md` and a POSIX path is unchanged.
+ *
+ * Every path a dependency, a watch input or another DTO carries takes this form, whatever produced
+ * it (`session/watch-inputs.ts` rejects any other), so the paths a generation records, and the
+ * outputs derived from them, are the same on every operating system. A path built with `node:path`
+ * (`resolve`, `join`, `fileURLToPath`) has native separators and must pass through here before it
+ * is recorded.
+ */
+export declare function hostPath(file: string, rules?: PathRules): string;
+/**
+ * A relative path (an output path, a glob or a path inside a root) with forward slashes. Unlike
+ * {@link hostPath} it does not resolve the path.
+ */
+export declare function forwardSlashes(value: string): string;

package/generator/kernel/runtime-identity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The resolved version of every package in {@link RUNTIME_PACKAGES} (`null` when it does not
+ * resolve), in that order. Read once per process: a package upgraded while it runs is not the code
+ * it loaded, and the next process reads the new versions.
+ */
+export declare function runtimePackages(): Readonly<Record<string, string | null>>;
+/**
+ * The version of each package of `list` as Node's resolution finds it from `from` upwards, or from
+ * the directory of the package named second (`null` when it does not resolve or names none).
+ */
+export declare function packageVersions(list: ReadonlyArray<readonly [string, string?]>, from: string): Record<string, string | null>;

package/generator/outputs/index.d.ts

@@ -0,0 +1,67 @@
+import type { ApiDescriptor, ApiListRecord, ContentDescriptor, DeclarationDescriptor, Dependency, Diagnostic, EntryDescriptor, FileOutput, GeneratorConfiguration, GuideDescriptor, GuideSemantics, KeywordExport, LinkedContent, PageArtifact, RouteRecord, ServiceResult } from '../contracts.js';
+export interface PageAssemblyRequest {
+    /** Authoritative compiler artifact ID, required when a descriptor plan is supplied. */
+    ownerId?: string;
+    configuration: GeneratorConfiguration;
+    entry: GuideDescriptor | ApiDescriptor;
+    declaration?: DeclarationDescriptor;
+    content: LinkedContent[];
+    /**
+     * The compiler's descriptor plan; assembly without a plan may omit it. Every descriptor must
+     * have its linked content in `content`.
+     */
+    contentDescriptors?: ContentDescriptor[];
+    semantics?: GuideSemantics;
+    metadata?: RouteRecord['metadata'];
+}
+/**
+ * A digest of every page-assembly input except the linked content, which callers compare
+ * directly, plus the structural template observations. `assemblePage` is a pure function of
+ * its request and the template files, so equal keys and equal content assemble identically.
+ * Returns undefined when an input has no exact JSON identity; callers must then assemble.
+ */
+export declare function pageAssemblyKey(request: Omit<PageAssemblyRequest, 'content'>, templates: Dependency[]): string | undefined;
+export interface PageAssembly {
+    outputs: FileOutput[];
+    routes: RouteRecord[];
+    apiList: ApiListRecord[];
+    diagnostics: Diagnostic[];
+}
+export interface AggregateRequest {
+    configuration: GeneratorConfiguration;
+    artifacts: PageArtifact[];
+    entries: EntryDescriptor[];
+    keywords: KeywordExport[];
+}
+export interface AggregateAssembly {
+    outputs: FileOutput[];
+    diagnostics: Diagnostic[];
+}
+export interface OutputAssembler {
+    templateDependencies(): Promise<ServiceResult<null>>;
+    assemblePage(request: PageAssemblyRequest): PageAssembly;
+    aggregate(request: AggregateRequest): AggregateAssembly;
+}
+/**
+ * The kind the API list and the search palette show for a declaration, such as `Component`.
+ * @param declaration - The declaration.
+ */
+export declare function apiListType(declaration: DeclarationDescriptor): string;
+export declare class OutputAssemblerImpl implements OutputAssembler {
+    private readonly templateRoot;
+    constructor(options?: {
+        templateRoot?: string;
+    });
+    templateDependencies(): Promise<ServiceResult<null>>;
+    assemblePage(request: PageAssemblyRequest): PageAssembly;
+    aggregate(request: AggregateRequest): AggregateAssembly;
+    private guide;
+    private apiEntry;
+    private apiDeclaration;
+    private apiLists;
+    private addContentSource;
+    private renderOutput;
+}
+export declare function createOutputAssembler(options?: {
+    templateRoot?: string;
+}): OutputAssembler;

package/generator/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/generator/progress/ci.d.ts

@@ -0,0 +1,22 @@
+import type { CiVendor } from './detect.js';
+/**
+ * CI vendor extras. None of them changes the text of a line.
+ * - Azure `##vso[task.setprogress]` and TeamCity `progressMessage` are hidden progress signals and
+ *   are on by default (decided); they follow the LINES cadence.
+ * - GitHub groups, GitLab sections and the GitHub step summary are opt-in with
+ *   `NGDOC_PROGRESS_SECTIONS=1` (decided).
+ */
+/** TeamCity service-message escaping. */
+export declare function escapeTeamCity(text: string): string;
+/**
+ * Free text (routes, reasons, project names) must never start a CI service message: Azure and
+ * TeamCity act on `##vso[`, `##[` and `##teamcity[` in any log line.
+ */
+export declare const neutralizeServiceMessages: (text: string) => string;
+/** The hidden progress line for `vendor`, or `undefined` when the vendor has none. */
+export declare function ciProgressMessage(vendor: CiVendor | undefined, text: string, percent: number | undefined): string | undefined;
+/** Opens a collapsible group; the summary line is printed after `sectionEnd`, so it stays visible. */
+export declare function sectionStart(vendor: CiVendor | undefined, title: string, nowMs: number): string | undefined;
+export declare function sectionEnd(vendor: CiVendor | undefined, nowMs: number): string | undefined;
+/** Appends one markdown line to `$GITHUB_STEP_SUMMARY`. Failures are ignored: it is decoration. */
+export declare function appendStepSummary(env: NodeJS.ProcessEnv, text: string, append?: (file: string, data: string) => void): boolean;

package/generator/progress/detect.d.ts

@@ -0,0 +1,60 @@
+import type { ProgressSetting } from './settings.js';
+/** CI vendors the reporter distinguishes (same set as Nx `isCI()`). */
+export type CiVendor = 'github' | 'gitlab' | 'azure' | 'teamcity' | 'buildkite' | 'jenkins' | 'circleci' | 'generic';
+/**
+ * `live`: one line redrawn in place. `lines`: append-only ASCII lines. `summary`: final lines only.
+ * `json`: the events themselves, one JSON line each. `off`: nothing.
+ */
+export type ProgressStyle = 'live' | 'lines' | 'summary' | 'json' | 'off';
+/** The terminal the live line would draw on (normally `process.stderr`). */
+export interface ProgressStream {
+    isTTY?: boolean;
+    columns?: number;
+    hasColors?: () => boolean;
+}
+export interface DetectOptions {
+    setting: ProgressSetting;
+    env?: NodeJS.ProcessEnv;
+    stream?: ProgressStream;
+    platform?: NodeJS.Platform;
+    /**
+     * Another writer shares the terminal: the Vite dev server after it listens, the CLI after it
+     * spawns a host.
+     */
+    foreign?: boolean;
+}
+export interface ProgressEnvironment {
+    setting: ProgressSetting;
+    style: ProgressStyle;
+    /** `verbose`: LINES plus phase timings, the FULL-pass reason and background notices. */
+    verbose: boolean;
+    ci?: CiVendor;
+    tty: boolean;
+    dumb: boolean;
+    color: boolean;
+    unicode: boolean;
+    /** Live text is cut to `columns - 1`. */
+    columns: number;
+    /** Running as an Nx task. */
+    nxTask: boolean;
+    /** Nx TUI or `--output-style=stream*`: several tasks share the screen; no in-place redraw. */
+    nxShared: boolean;
+    /** Nx prefixes every line (`project: …`), which breaks CI commands. */
+    nxPrefix: boolean;
+    /** Invisible Azure/TeamCity progress service messages. */
+    ciAssist: boolean;
+    /** Opt-in GitHub/GitLab groups and step summary. */
+    sections: boolean;
+    /** LINES heartbeat: 15 s on CI, 5 s under Nx shared output, 10 s otherwise. */
+    heartbeatMs: number;
+    foreign: boolean;
+}
+/** The Nx 23 task PTY reports the whole terminal, not the pane: keep live text short under Nx. */
+export declare const NX_TASK_COLUMNS = 56;
+export declare function detectCi(env: NodeJS.ProcessEnv): CiVendor | undefined;
+/**
+ * Chooses the output style. In-place redraw needs a TTY that NgDoc owns: not CI (Buildkite runs a
+ * PTY), not Nx shared output (the task PTY reports the whole terminal width, so redrawn lines
+ * pile up in a pane), and no foreign writer. A single Nx task on a TTY does get the live line.
+ */
+export declare function detectProgressEnvironment(options: DetectOptions): ProgressEnvironment;

package/generator/progress/events.d.ts

@@ -0,0 +1,126 @@
+import type { CompilationProgressUpdate, Diagnostic, Generation } from '../contracts.js';
+export type { CompilationPhase } from '../contracts.js';
+/** Every phase a generation can report: the compilation's (compiler and worker) and the commit. */
+export type ProgressPhase = CompilationProgressUpdate['phase'] | 'commit';
+/** Declared execution order. A phase may be skipped but never goes backwards. */
+export declare const PROGRESS_PHASES: readonly ProgressPhase[];
+/**
+ * Phases reported outside the compiler: the worker runtime's start and result transfer, and the
+ * session's commit. Only compiler phases make the output show steps.
+ */
+export declare const SESSION_PHASES: ReadonlySet<ProgressPhase>;
+/** Why a generation runs. It selects how much the reporter prints. */
+export type ProgressTrigger = 
+/** `buildOnce`: the initial development build or a production build. Full progress. */
+'build'
+/** A filesystem generation, including the first watch generation when the baseline is not reused. */
+ | 'watch'
+/** A watcher rescan or a reconcile-origin generation. */
+ | 'rescan'
+/** A generation started by an idle sweep for missed changes. Background. */
+ | 'follow-up'
+/** The idle FULL confirmation after a targeted pass failed. Background. */
+ | 'confirmation'
+/** The idle audit that repairs generated files changed outside NgDoc. Background. */
+ | 'audit';
+export declare const PROGRESS_TRIGGERS: readonly ProgressTrigger[];
+/** Background work is hidden unless it fails, runs longer than 2 s, or clears a reported error. */
+export declare const BACKGROUND_TRIGGERS: ReadonlySet<ProgressTrigger>;
+/** `restored`: a start published its recorded candidate without compiling (the fast start). */
+export type ProgressPass = 'targeted' | 'full' | 'restored';
+export type ProgressState = 'start' | 'advance' | 'end';
+/**
+ * `superseded`: the generation committed, was adopted and a newer one follows (a `success` with
+ * `superseded: true` in `BuildResult`). `cancelled`: nothing was committed.
+ */
+export type ProgressStatus = 'success' | 'superseded' | 'failure' | 'cancelled';
+export interface ProgressCounts {
+    /** Pages (units) in the candidate. */
+    pages: number;
+    /** Unique pages rebuilt in this generation (`whyRebuilt` owners). */
+    rebuilt: number;
+    errors: number;
+    warnings: number;
+    /** Output files written, removed and left unchanged by the commit. */
+    written?: number;
+    removed?: number;
+    unchanged?: number;
+    /** At most three routes of rebuilt pages, for the per-edit line. */
+    routes?: string[];
+}
+export interface ProgressStartedEvent {
+    kind: 'progress-started';
+    generation: Generation;
+    seq: 0;
+    trigger: ProgressTrigger;
+    mode: 'development' | 'production';
+    /** File changes (or requested ids) behind the generation. */
+    changes: number;
+    elapsedMs: 0;
+}
+export interface ProgressUpdateEvent {
+    kind: 'progress';
+    generation: Generation;
+    /** Strictly increasing within the generation; assigned by the session. */
+    seq: number;
+    phase: ProgressPhase;
+    state: ProgressState;
+    /** Non-decreasing within `(pass, phase)`; never above `total`. */
+    completed?: number;
+    /** Fixed at `start`. */
+    total?: number;
+    /** Render: units reused from the previous IR or the cache. */
+    reused?: number;
+    /** A change to `full` may restart the phase sequence once per generation. */
+    pass?: ProgressPass;
+    /** On a pass change to `full`: a short, user-safe reason. */
+    reason?: string;
+    /** Session clock (`performance.now()`), milliseconds since `progress-started`. */
+    elapsedMs: number;
+}
+export interface ProgressSettledEvent {
+    kind: 'progress-settled';
+    generation: Generation;
+    seq: number;
+    status: ProgressStatus;
+    elapsedMs: number;
+    /** Milliseconds per phase that ran (last pass). */
+    phases: Partial<Record<ProgressPhase, number>>;
+    pass?: ProgressPass;
+    reason?: string;
+    counts: ProgressCounts;
+}
+/** Work outside a generation: the input check after start (`reobserve`) and the warm-up (`prime`). */
+export interface ProgressActivityEvent {
+    kind: 'progress-activity';
+    activity: 'checking-inputs' | 'warming-up';
+    state: 'start' | 'end';
+    /** Only on `end`: the activity failed. */
+    failed?: boolean;
+    /** Only on `end`: other work stopped the activity before it finished. */
+    stopped?: boolean;
+    elapsedMs: number;
+}
+/** Advisory only: never influences results, commits, retention, watch inputs or caching. */
+export type ProgressEvent = ProgressStartedEvent | ProgressUpdateEvent | ProgressSettledEvent | ProgressActivityEvent;
+/**
+ * Free text from the session (routes, reasons) and hosts (project names) as one safe line: C0 and
+ * C1 controls (newlines, escape sequences) and the Unicode line separators become spaces, so the
+ * text can neither start a new log line (`::error::`) nor drive the terminal (OSC, cursor moves).
+ */
+export declare const plainText: (text: string) => string;
+/** A consumer of progress events (`SessionOptions.onProgress`). */
+export type ProgressSink = (event: ProgressEvent) => void | Promise<void>;
+/**
+ * Warning code for a progress consumer that threw or rejected. Reported once per session and never
+ * stops the watch: progress is advisory and must never change a build's outcome.
+ */
+export declare const SESSION_PROGRESS_FAILED = "SESSION_PROGRESS_FAILED";
+/** The `SESSION_PROGRESS_FAILED` diagnostic. Its severity is always `warning`. */
+export declare function progressFailure(error: unknown): Diagnostic;
+/**
+ * Wraps a progress consumer so that it can never throw into its caller. The first synchronous
+ * exception or rejection is reported once through `report` (as `SESSION_PROGRESS_FAILED`); later
+ * failures are swallowed. Events keep flowing to the consumer, and nothing else changes.
+ */
+export declare function guardProgressSink(sink: ProgressSink, report: (diagnostic: Diagnostic) => void): (event: ProgressEvent) => void;

package/generator/progress/format.d.ts

@@ -0,0 +1,83 @@
+import type { ProgressActivityEvent, ProgressSettledEvent, ProgressTrigger } from './events.js';
+import type { GenerationView } from './model.js';
+/**
+ * All user-facing text. Lines are ASCII-only; the live line may use a spinner and a
+ * bar. Colour is decoration only and is applied by `paint`.
+ */
+export declare const PREFIX = "NgDoc:";
+/**
+ * `0.9s`, `9.8s`, `21s`, `1m 05s`. `coarse` drops the tenths, so a redrawn line changes at most
+ * once per second because of the clock.
+ */
+export declare function formatDuration(ms: number, coarse?: boolean): string;
+export declare const plural: (n: number, noun: string) => string;
+export declare const paint: (text: string, code: number, enabled: boolean) => string;
+export interface StepTextOptions {
+    /** Live line: `preparing: detail` and no percentage parentheses change. */
+    live?: boolean;
+    /**
+     * Totals only (`rendering 664 pages`): for the one line printed when a step starts, where a
+     * count of zero would only say the step began. Live lines and heartbeats show `312/664`.
+     */
+    totals?: boolean;
+    /** `false` leaves out the percentage, for consumers that show it on their own. */
+    percent?: boolean;
+}
+/** The step and its counts, without prefix or timing: `[2/4] rendering 312/664 pages (48%)`. */
+export declare function stepText(view: GenerationView, options?: StepTextOptions): string;
+/** Compact text for the Nx TUI and stream styles, where a pane may be about 46 columns wide. */
+export declare function compactText(view: GenerationView, elapsedMs: number, totals?: boolean): string;
+/**
+ * LINES mode: `NgDoc: [2/4] rendering 664 pages (35%), 6.9s elapsed` when a step starts (`totals`),
+ * `NgDoc: [2/4] rendering 312/664 pages (48%), 16s elapsed` on a heartbeat.
+ */
+export declare function stepLine(view: GenerationView, elapsedMs: number, totals?: boolean): string;
+/** The first line of a LINES build: `NgDoc: generating documentation for docs (production)`. */
+export declare function startLine(view: GenerationView, project?: string, compact?: boolean): string;
+export interface LiveTextOptions {
+    frame: number;
+    unicode: boolean;
+    /** Terminal columns; the text never exceeds `columns - 1`, so it never wraps. */
+    columns: number;
+    /** Draw the bar when it fits (not under Nx). */
+    bar: boolean;
+}
+/** `⠼ NgDoc [2/4] rendering 312/664 pages (48%) · 9.4s ━━━━━━━━──────────`. */
+export declare function liveText(body: string, elapsedMs: number, fraction: number | undefined, options: LiveTextOptions): string;
+/** Cuts `text` to at most `width` code points. */
+export declare function truncate(text: string, width: number, unicode: boolean): string;
+/** `analyze 4.7s, render 5.1s, link 2.0s, write 4.4s`, for the groups that ran. */
+export declare function timingText(phases: ProgressSettledEvent['phases']): string;
+/** The build summary: every build ends with exactly one line, `OK` or `FAILED`. */
+export declare function buildSummary(event: ProgressSettledEvent, color: boolean): string;
+/** The work an edit did: `1 of 664 pages (/route, +2)`, `664 pages`, `3 files`; `undefined` when nothing changed. */
+export declare function editWork(event: ProgressSettledEvent): string | undefined;
+/** `NgDoc: updated 1 of 664 pages in 0.9s (/getting-started/installation)`; `undefined` for an unchanged save. */
+export declare function editLine(event: ProgressSettledEvent): string | undefined;
+/** A build that succeeded after a reported failure: one line that says both. */
+export declare const resolvedBuildLine: (event: ProgressSettledEvent, color: boolean) => string;
+/** An edit or background run that printed a notice and was then cancelled (nothing committed). */
+export declare const cancelledLine: (what: string, event: ProgressSettledEvent) => string;
+/** An edit that completed without changing a page or a file. */
+export declare const noChangesLine: (event: ProgressSettledEvent) => string;
+/** The first success after a reported failure: `NgDoc: error resolved; updated 1 of 664 pages …`. */
+export declare function resolvedLine(event: ProgressSettledEvent): string;
+/** `NgDoc: update failed (1 error above); the site keeps the last good version`. */
+export declare function editFailureLine(event: ProgressSettledEvent, what?: string): string;
+/** The notice for an edit still running after 2 s. */
+export declare function slowEditLine(view: GenerationView): string;
+export declare const backgroundLabel: (trigger: ProgressTrigger) => string;
+export declare const backgroundNotice: (trigger: ProgressTrigger) => string;
+/** `NgDoc: checking generated files finished in 3.4s; updated 2 files`. */
+export declare function backgroundDone(trigger: ProgressTrigger, event: ProgressSettledEvent): string;
+export declare const activityLabel: (activity: ProgressActivityEvent["activity"]) => string;
+export declare const activityNotice: (activity: ProgressActivityEvent["activity"]) => string;
+export declare function activityDone(event: ProgressActivityEvent, durationMs: number): string;
+export declare const SUPERSEDED_LINE = "NgDoc: superseded by newer changes";
+export declare const RESTARTING_LINE = "NgDoc: inputs changed, restarting";
+/** Verbose: `NgDoc: phases (full pass: tsconfig.json changed): boot 0.8s, discovery 0.3s, …`. */
+export declare function phasesLine(event: ProgressSettledEvent): string | undefined;
+/** Verbose, on a targeted → FULL restart. */
+export declare const restartLine: (view: GenerationView) => string;
+/** One line naming the engine switches that are set. */
+export declare const switchesLine: (switches: readonly string[]) => string;

package/generator/progress/gate.d.ts

@@ -0,0 +1,49 @@
+import type { Generation } from '../contracts.js';
+import type { ProgressEvent } from './events.js';
+import type { ProgressClock } from './reporter.js';
+/**
+ * How long a settled generation waits for its host at most. Hosts release every generation whose
+ * result they handled; this bound only keeps a host that missed one from silencing progress.
+ */
+export declare const SETTLE_HOLD_MS = 10000;
+export interface SettleGateOptions {
+    clock?: ProgressClock;
+    holdMs?: number;
+}
+/**
+ * Keeps a generation's result line behind the host's own output for that generation.
+ *
+ * The session reports `progress-settled` before it hands the result to the host, and the host
+ * prints the result's diagnostics after that. The gate holds each `progress-settled` event, and
+ * every event after it in order, until the host calls `release(generation)` once it has printed
+ * what it prints for that result. So `FAILED … (2 errors, see above)` follows the errors, and an
+ * edit line follows the host's own log. Order is never changed. A generation that the host
+ * released before its settle arrived passes through at once, and after `holdMs` held events are
+ * forwarded anyway. A host that could not publish a committed result releases it as failed, and
+ * its line becomes the failure line.
+ */
+export declare class SettleGate {
+    private readonly target;
+    private readonly queue;
+    /** Released generations, and whether the host failed to publish each. */
+    private readonly released;
+    private readonly clock;
+    private readonly holdMs;
+    private timer;
+    private disposed;
+    constructor(target: (event: ProgressEvent) => void, options?: SettleGateOptions);
+    /** The session's `onProgress`. */
+    readonly sink: (event: ProgressEvent) => void;
+    /**
+     * The host has printed its output for `generation`'s result; `failed` when it could not publish
+     * a committed result. Releasing a generation that never settles (a reused result, a generation
+     * without progress) is harmless.
+     */
+    release(generation: Generation, failed?: boolean): void;
+    /** Forwards everything still held, then stops. */
+    dispose(): void;
+    private flush;
+    private expire;
+    private forward;
+    private cancelTimer;
+}

package/generator/progress/host.d.ts

@@ -0,0 +1,29 @@
+import type { Generation } from '../contracts.js';
+import type { ProgressEvent, ProgressSink } from './events.js';
+import type { ForeignMode, ProgressReporter, ProgressReporterOptions } from './reporter.js';
+export interface HostProgressOptions extends ProgressReporterOptions {
+    /** Another consumer the host was given (`SessionOptions.onProgress`); it receives every event. */
+    forward?: ProgressSink;
+    /**
+     * The host's warning channel. When the writer throws, progress stops and this receives one
+     * `[SESSION_PROGRESS_FAILED] …` line; its own failures are contained.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * A host's progress: the reporter behind a {@link SettleGate}. The host passes `sink` as the
+ * session's `onProgress`, calls `release(generation)` once it has printed a result's own output
+ * (its diagnostics), and `setForeign` once another writer shares the terminal.
+ */
+export interface HostProgress {
+    readonly reporter: ProgressReporter;
+    readonly sink: (event: ProgressEvent) => void;
+    /** `failed`: the host could not publish the result; its line becomes the failure line. */
+    release(generation: Generation, failed?: boolean): void;
+    /** Clears the live line before the host prints its own output (see `ProgressReporter.interrupt`). */
+    interrupt(): void;
+    setForeign(mode?: ForeignMode): void;
+    /** Prints what is still held, then clears the live line and stops. */
+    dispose(): void;
+}
+export declare function createHostProgress(options: HostProgressOptions): HostProgress;