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

package/generator/compiler/link.d.ts

@@ -0,0 +1,38 @@
+import type { Dependency, KeywordExport, PageArtifact } from '../contracts.js';
+import { type Unit } from './common.js';
+import type { GenerationPlan } from './plan.js';
+import type { ReplayScope } from './targeted.js';
+/** The keyword set every link of this generation reads. */
+export interface KeywordPlan {
+    keywords: KeywordExport[];
+    keywordSetDigest: string;
+}
+/** What the link phase leaves for assembly. */
+export interface LinkOutcome {
+    linkedByUnit: Map<Unit, PageArtifact['content']>;
+    keywordDependenciesByUnit: Map<Unit, Dependency[]>;
+}
+/**
+ * Keywords phase: the combined keyword set (remote, configured, then local exports) and the
+ * index completeness check: every current descriptor must have its IR, or the generation fails
+ * (`undefined`).
+ */
+export declare function combineUnitKeywords(plan: GenerationPlan, units: Unit[]): KeywordPlan | undefined;
+/**
+ * Link phase: per unit its keyword dependencies, then each IR linked against the keyword set,
+ * or reused when linking again provably yields the previous document (see `createLinkReuse`).
+ *
+ * On the targeted path (`scope`), a replayed unit outside the link set keeps its previous linked
+ * content and its retained link record: none of the keys it uses changed binding, and linking
+ * reads nothing else, so linking it again would yield exactly those.
+ *
+ * `done`, when progress is reported, hears how many units are done: the kept ones at once, then
+ * each linked unit.
+ *
+ * With render threads (`content/html-pool`), the back half of each link that will not be reused is
+ * dispatched a window of units ahead (`prepareLink`); the loop below still takes every result,
+ * records it and reports it in unit order, exactly as when it links each one in its turn. Linking
+ * is a pure function of the IR and the keyword set, so the result does not depend on when or where
+ * it ran.
+ */
+export declare function linkUnits(plan: GenerationPlan, units: Unit[], keywordPlan: KeywordPlan, scope?: ReplayScope, done?: (count: number) => void): Promise<LinkOutcome>;

package/generator/compiler/memo.d.ts

@@ -0,0 +1,44 @@
+import { type FileStamp } from '../artifacts/index.js';
+import type { CompilationOptions } from './index.js';
+export interface LinkMemo {
+    /** SHA-256 of the IR HTML that was linked. */
+    input: string;
+    /** SHA-256 of the linked HTML it produced. */
+    output: string;
+    /** Every keyword key the link pass looked up, sorted and unique. */
+    keys: string[];
+    /** Digest of those keys' bindings when it linked. */
+    bindings: string;
+}
+export interface AssemblyMemo {
+    key: string;
+    revision: string;
+}
+export interface CacheMemo {
+    revision: string;
+    stamp: FileStamp;
+}
+/**
+ * Per-project reuse facts kept beside the artifact cache. Every entry states a fact about a
+ * pure computation or a file identity ("linking this HTML with these consulted bindings
+ * produced that HTML", "this assembly key produced the page of that revision", "this cache
+ * file with this stamp holds that revision"), and every use re-checks the fact against the
+ * current inputs, so a stale, missing or corrupt memo only disables reuse.
+ */
+export interface MemoState {
+    enabled: boolean;
+    link(id: string): LinkMemo | undefined;
+    recordLink(id: string, entry: LinkMemo | undefined): void;
+    assembly(id: string): AssemblyMemo | undefined;
+    recordAssembly(id: string, entry: AssemblyMemo): void;
+    cacheEntry(id: string): CacheMemo | undefined;
+    recordCache(id: string, entry: CacheMemo): void;
+    /**
+     * Keeps the recorded facts of a unit the targeted path did not link, assemble or write again
+     * (its assembly and cache entries, and the link entries of its content): the full path would
+     * record the same facts for it, since each still holds for its unchanged inputs.
+     */
+    carry(unitId: string, contentIds: readonly string[]): void;
+    save(projectId: string): Promise<void>;
+}
+export declare function createMemoState(enabled: boolean, root: string, options: Pick<CompilationOptions, 'projectId' | 'compilerVersion' | 'toolchainDigest'>): MemoState;

package/generator/compiler/plan.d.ts

@@ -0,0 +1,116 @@
+import { JsonArtifactCache } from '../artifacts/index.js';
+import { GeneratorContentCompiler } from '../content/content-compiler.js';
+import { type FormatSession } from '../content/format-cache.js';
+import { type HighlightSession } from '../content/highlight-cache.js';
+import { type RenderBack } from '../content/html-pool.js';
+import type { CompilationRequest, Dependency, Diagnostic, DiscoverySnapshot, PageArtifact, RebuildReason } from '../contracts.js';
+import type { createDiscoveryServices } from '../discovery/index.js';
+import { type DependencyRefresher } from '../graph/index.js';
+import type { OutputAssembler } from '../outputs/index.js';
+import type { SemanticServiceImpl } from '../semantic/semantic-service.js';
+import { type Unit } from './common.js';
+import type { GenerationRecords } from './fold.js';
+import type { CompilationOptions } from './index.js';
+import { type MemoState } from './memo.js';
+import type { ScopedSemanticMode } from './semantic-closure.js';
+/** The services one compile runs its phases with. */
+export interface CompilationServices {
+    options: CompilationOptions;
+    discovery: ReturnType<typeof createDiscoveryServices>;
+    semantic: SemanticServiceImpl;
+    assembler: OutputAssembler;
+}
+/**
+ * Everything the unit phases of one generation share: the request and its services, the discovered
+ * site, and the previous artifacts and what may be reused from them. Built once by
+ * `planGeneration`.
+ */
+export interface GenerationPlan extends CompilationServices {
+    request: CompilationRequest;
+    signal: AbortSignal;
+    records: GenerationRecords;
+    refresher: DependencyRefresher;
+    found: DiscoverySnapshot;
+    configuration: DiscoverySnapshot['configuration'];
+    /**
+     * Turns semantic scopes into references and, unless semantic invalidation is scoped, drops the
+     * program inputs the aggregate owns (a scoped unit keeps the program files it read).
+     */
+    compact(values: Dependency[]): Dependency[];
+    /** The global `semantic-reference` every unit records; empty when semantic invalidation is scoped. */
+    semanticReferences: Dependency[];
+    /** Scoped semantic invalidation in this generation (`./semantic-closure`). */
+    scopedSemantic: ScopedSemanticMode;
+    outputDependencies: Dependency[];
+    /** The program's own dependencies, owned once by the aggregate artifact. */
+    programDependencies: Dependency[];
+    cache: JsonArtifactCache;
+    hadCacheIndex: boolean;
+    previous: PageArtifact[];
+    previousById: Map<string, PageArtifact>;
+    /** Index-derived `whyRebuilt` reasons of these (removed or rebuilt) owners. */
+    affectedFor(ownerIds: string[]): RebuildReason[];
+    /**
+     * The previous artifacts are reused beyond their IRs (links, assemblies, revisions): the
+     * session's snapshot, or the cache index of a start (`restoredReuse`).
+     */
+    sessionPrevious: boolean;
+    memo: MemoState;
+    compiler: GeneratorContentCompiler;
+    /** The cache of highlighted code blocks, when this generation uses one (`content/highlight-cache`). */
+    highlight?: HighlightSession;
+    /** The cache of formatted signatures and snippets, when this generation uses one (`content/format-cache`). */
+    format?: FormatSession;
+    /** Where the content's HTML pipeline runs, when it may run on threads (`content/html-pool`). */
+    back?: RenderBack;
+}
+/**
+ * Setup phase: previous artifacts (session snapshot or cache index), reuse switches and the output
+ * templates. Its diagnostics are recorded as the `setup` phase.
+ * @param services
+ * @param input
+ * @param input.request
+ * @param input.signal
+ * @param input.records
+ * @param input.refresher
+ * @param input.found
+ * @param input.programDependencies
+ * @param input.scopedSemantic
+ * @param input.scratch
+ */
+export declare function planGeneration(services: CompilationServices, input: {
+    request: CompilationRequest;
+    signal: AbortSignal;
+    records: GenerationRecords;
+    refresher: DependencyRefresher;
+    found: DiscoverySnapshot;
+    programDependencies: Dependency[];
+    scopedSemantic?: ScopedSemanticMode;
+    /**
+     * No previous artifacts at all, not even the cache index's: with the reference path's options
+     * (`incrementalReuse: false`), a compile from scratch (the fast start's `verify`).
+     */
+    scratch?: boolean;
+}): Promise<GenerationPlan>;
+/**
+ * Plan phase, after describe: the current descriptor plan, in which a duplicate descriptor fails
+ * the generation. Every descriptor of the plan is rendered.
+ * @param plan
+ * @param units
+ */
+export declare function planContent(plan: GenerationPlan, units: Unit[]): void;
+/**
+ * The artifacts the cache index names, in its order. An entry that cannot be read is left out
+ * with its diagnostics; an index of another schema version restores nothing.
+ * @param root
+ * @param projectId
+ * @param diagnostics
+ */
+export declare function restoreIndex(root: string, projectId: string, diagnostics: Diagnostic[]): Promise<PageArtifact[]>;
+/**
+ *
+ * @param root
+ * @param projectId
+ * @param artifacts
+ */
+export declare function saveIndex(root: string, projectId: string, artifacts: PageArtifact[]): Promise<void>;

package/generator/compiler/progress.d.ts

@@ -0,0 +1,54 @@
+import type { CompilationContext, CompilationPhase } from '../contracts.js';
+/**
+ * The compiler's side of progress reporting (`CompilationContext.progress`). Advisory only:
+ * nothing here reads or changes what a generation compiles, and a sink that throws is ignored.
+ *
+ * It exists only when the context carries a sink, so a compile without a consumer does no
+ * progress work at all (every call site is an optional call). It reads no clock: throttling is
+ * the transport's job (a worker runtime coalesces advances before they cross the process
+ * boundary), and the session stamps every event with its own clock.
+ *
+ * Phases are reported in execution order. Starting a phase ends the open one, so each call site
+ * marks only where its phase begins. Per-unit loops report through `unit`, which counts the units
+ * the open phase finished.
+ */
+export declare class CompilationProgress {
+    private readonly sink;
+    private open?;
+    private completed;
+    private reused;
+    private total?;
+    private pass?;
+    /** A reason waiting for the first update of the `full` pass. */
+    private reason?;
+    private constructor();
+    /** The reporter for a compile, or `undefined` when nobody listens. */
+    static of(context: CompilationContext | undefined): CompilationProgress | undefined;
+    /**
+     * The generation's first pass: `targeted` when it may compile only what its changes reach;
+     * `full` with the reason when the targeted rebuild considered the generation and decided before
+     * compiling that it rebuilds every page. A generation the targeted rebuild never considers (it
+     * is off, or the generation retains nothing) reports no pass.
+     */
+    begin(pass: 'targeted' | 'full', reason?: string): void;
+    /**
+     * The fast start published the recorded candidate: the open phase (`restore`) ends with the
+     * `restored` pass, which the host's result line reports, and nothing else runs.
+     */
+    restored(): void;
+    /** The generation is still on its targeted pass. */
+    get targeted(): boolean;
+    /**
+     * The targeted pass fell back to the full one. The next phase start carries `full` and the
+     * reason, and the phases may start again from the beginning. Only the first fall back counts.
+     */
+    full(reason?: string): void;
+    /** `phase` starts (ending the open one). `total` is fixed for the phase. */
+    phase(phase: CompilationPhase, total?: number): void;
+    /** Units of the open phase finished; `reused` of them were reused rather than computed again. */
+    unit(count?: number, reused?: boolean): void;
+    /** The open phase ends. Nothing when no phase is open. */
+    end(): void;
+    private passFields;
+    private emit;
+}

package/generator/compiler/render.d.ts

@@ -0,0 +1,27 @@
+import { type Unit } from './common.js';
+import type { GenerationPlan } from './plan.js';
+import type { ReplayScope } from './targeted.js';
+/**
+ * Render phase: per unit, each descriptor reuses the previous IR when the full path's predicate
+ * holds (equal descriptor, matching IR, refreshed dependencies unchanged) and is rendered
+ * otherwise; a guide with demos then reuses or compiles its demo-assets IR (reused
+ * only for an unchanged descriptor plan). Each step records its projection on the unit's record.
+ *
+ * On the targeted path (`scope`), a unit it replays keeps its retained render record when that
+ * record already holds the reuse projection, and otherwise runs the same predicate without
+ * refreshing its dependencies: the classifier and the sweep established that none of its paths
+ * changed, and the admission that none of its non-physical dependencies did, which is what the
+ * refresh would find.
+ *
+ * Each unit has a front (`renderFront`: the reuse predicates and the fronts of its compiles, which
+ * read files, evaluate templates and query the program) and a settle (its records, IRs,
+ * dependencies, input digest and progress). Fronts run strictly one after the other in plan order,
+ * so the semantic queries and their order are those of a sequential render. Settles run in plan
+ * order too, each once its unit's back halves are done. With render threads
+ * (`content/html-pool`), up to `window()` units may wait for their back halves while the next
+ * fronts run; without them, each unit settles before the next front starts, as it always did.
+ *
+ * `rendered`, when progress is reported, hears of each unit as it finishes, and whether all of its
+ * content was reused.
+ */
+export declare function renderUnits(plan: GenerationPlan, units: Unit[], scope?: ReplayScope, rendered?: (reused: boolean) => void): Promise<void>;

package/generator/compiler/retention.d.ts

@@ -0,0 +1,181 @@
+import type { CompilationContext, CompilationRequest, CompilationRetention, FileChange, RetainedCompilation, RetainedSemanticState, SemanticProgramRetention, SemanticProgramSynchronization, SemanticRetentionRequest } from '../contracts.js';
+import type { UnitIndex } from '../graph/unit-index.js';
+import type { IncrementalProgramMode, SynchronizationPath } from '../semantic/semantic-service.js';
+import type { CompilationOptions } from './index.js';
+import type { RetainedBuild } from './targeted.js';
+/**
+ * Kill switch for the retained-program skip only: `0`, `false`, `off` or `no` in the compiler
+ * runtime's environment (the worker inherits the host's) makes every development generation
+ * synchronize its program from scratch and retain nothing. Exact incremental reuse
+ * (`incrementalReuse`) is unaffected.
+ */
+export declare const INCREMENTAL_SKIP_ENV = "NGDOC_INCREMENTAL_SKIP";
+/**
+ * Kill switch of the incremental program (`NGDOC_INCREMENTAL_PROGRAM`): `0`, `false`, `off` or `no`
+ * make a development generation synchronize its program anew after any program-file edit, as
+ * before patching existed; `verify` checks every patch against a cold synchronization. Read in the
+ * compiler runtime's environment (the worker inherits the host's).
+ */
+export declare const INCREMENTAL_PROGRAM_ENV = "NGDOC_INCREMENTAL_PROGRAM";
+/** The switch as the process sets it: the option first, then `NGDOC_INCREMENTAL_PROGRAM`. */
+export declare function incrementalProgramMode(options: CompilationOptions): IncrementalProgramMode;
+/**
+ * The program a development generation retains for the next one: valid only for the base revision
+ * it produced, so the next generation may use it only when its request's previous snapshot is
+ * exactly that candidate (the caller committed it). It is keyed by the compiler options as well, so
+ * another project or configuration never reuses it.
+ */
+export interface RetainedGeneration extends RetainedCompilation {
+    key: string;
+    base: string;
+    semantic: RetainedSemanticState;
+    /**
+     * The reverse index of this base's build (graph/unit-index.ts): built at the end of a
+     * generation that returned the candidate `base`, while the targeted rebuild is on. It follows
+     * the entry's committed/working lifetime, beside the program.
+     */
+    index?: UnitIndex;
+    /** The per-unit records a targeted generation replays for the units it does not rebuild. */
+    build?: RetainedBuild;
+    /**
+     * The changes of every generation against this base that did not commit (failed, aborted or
+     * discarded). A targeted generation adds them to its own changes before it skips anything: a
+     * full generation re-reads every input, a targeted one only what its changes reach. Each
+     * restore appends to a new entry's list; the entry of the next committed candidate starts empty.
+     */
+    pending?: readonly FileChange[];
+}
+/** What a compile may use from the committed entry for its base. */
+export interface CommittedGeneration {
+    index: UnitIndex;
+    build?: RetainedBuild;
+    pending: readonly FileChange[];
+}
+export interface IncrementalRetentionReport {
+    /**
+     * Generations that reused / rebuilt the program, promoted / restored a retained program, or
+     * discarded one. `promoted` counts the offers of a candidate's program: with an in-process
+     * slot or a `compile-end` handle that commits it, with an `acknowledged` handle (a delta
+     * compile) it becomes the working entry, which the caller's acknowledgement may still drop (the
+     * runtime slot's own `promoted` counts only the promotions). `restored` counts the committed
+     * entries handed back, also those restored beside a working entry.
+     */
+    counters: {
+        reused: number;
+        rebuilt: number;
+        promoted: number;
+        restored: number;
+        discarded: number;
+    };
+    /** The retained program's base revision, if one is held. */
+    retained?: {
+        base: string;
+    };
+    /**
+     * A long-lived runtime's retained candidate program awaiting the commit's acknowledgement;
+     * never present for the in-process slot.
+     */
+    working?: {
+        base: string;
+    };
+    /**
+     * The last retaining generation: how its program was obtained, and why a retained one was
+     * discarded. When it found no committed entry because an earlier generation invalidated it,
+     * `discarded` says so (`invalidated: consumed`, `invalidated: mutated`, …) instead of looking
+     * like a cold start, so a rebuild can always be explained; a fresh slot reports no reason.
+     */
+    last?: {
+        synchronization?: SynchronizationPath;
+        discarded?: string;
+    };
+}
+/** The in-process slot of this runtime. */
+export declare const processRetention: CompilationRetention & {
+    reset(): void;
+};
+/** Instrumentation and tests: what the retained-program skip did in this runtime. */
+export declare function incrementalRetention(): IncrementalRetentionReport;
+/** Drops the in-process retained program and resets the counters (tests). */
+export declare function resetIncrementalRetention(): void;
+/**
+ * One compile's use of a retention slot (its context's, or the in-process one): takes the
+ * committed entry when the compile starts, decides whether the semantic service may reuse its
+ * program, offers the program of a returned candidate, and restores the taken entry only when its
+ * program is still intact. The slot decides where an offer goes (committed at once, or a working
+ * entry promoted on the commit's acknowledgement).
+ */
+export declare class GenerationRetention {
+    /**
+     * Retained-program skip: development generations of a long-lived runtime only. Production,
+     * one-shot builds and the reference path neither use nor keep a program.
+     */
+    readonly retaining: boolean;
+    private readonly key;
+    private readonly port;
+    private taken;
+    private takenBase;
+    /** The index, build and pending changes of the taken entry, kept to restore it with its program. */
+    private takenIndex;
+    private takenBuild;
+    private takenPending;
+    /** Whether this generation took an entry of this compiler from the slot. */
+    private tookEntry;
+    /** Why the slot held no usable entry for this generation (another compile invalidated it). */
+    private invalidated;
+    private reusedProgram;
+    /**
+     * The taken program was patched in place: it now describes this generation's tree, not the
+     * taken entry's base, so it is offered only for this generation's candidate and never restored.
+     */
+    private patched;
+    /** A `patched-failed` synchronization's taken program, restored as the same object. */
+    private handedBack;
+    private discarded;
+    constructor(options: CompilationOptions, request: CompilationRequest, context: CompilationContext | undefined);
+    /**
+     * The committed entry's index when this generation may use it: the entry was
+     * built under the same compiler options for exactly the request's previous revision. The same
+     * conditions as the program's reuse, checked before discovery.
+     */
+    committedIndex(request: CompilationRequest, projectId: string): UnitIndex | undefined;
+    /** The committed entry's index, build and pending changes, under {@link committedIndex}'s rule. */
+    committed(request: CompilationRequest, projectId: string): CommittedGeneration | undefined;
+    /** After discovery: the retention request for `synchronize`, or `undefined` when not retaining. */
+    semanticRetention(request: CompilationRequest, projectId: string): SemanticRetentionRequest | undefined;
+    /**
+     * After `synchronize`: how the program was obtained (`synchronization`, for the report) and what
+     * the retention port says happened to the taken program (`outcome`). A `reused` or `patched`
+     * program is kept through `retain()`; a `patched-failed` one is kept as the object handed back,
+     * since the failed synchronization leaves nothing to retain. A `patched` program is the
+     * candidate's only: it is never restored for the taken base.
+     */
+    synchronized(synchronization: SynchronizationPath | undefined, outcome: SemanticProgramSynchronization | undefined): void;
+    /**
+     * When the compile ends. Offers the program of a returned candidate for exactly that revision
+     * (with `index`, the reverse index of that candidate, when the dry run built one), and restores
+     * the taken entry for its unchanged base only if this generation reused its program and the
+     * program is still retainable. Every other taken entry is dropped here, which is how the
+     * slot's committed entry is invalidated (a consumed or mutated Project must never serve the
+     * next generation, whether or not this generation's commit is acknowledged); the slot is told
+     * why:
+     *
+     * - `consumed`: a full synchronize released the program and built a replacement (or
+     *   synchronize failed);
+     * - `mutated`: a query added source files, so `retain()` refuses the program, and the
+     *   generation offers no candidate entry either (the committed and working entries would share
+     *   that Project);
+     * - `patched`: the program was patched in place for this generation's tree, so it is offered
+     *   for its candidate only (and dropped when there is none): kept for the taken base as well, a
+     *   later generation against that base would take a program of another tree as its own;
+     * - `ended before synchronize`: its changes were never checked (for example a discovery error);
+     * - `not usable (…)`: it was for other compiler options or another base.
+     *
+     * The in-process slot holds the offer already, so it restores nothing when a candidate was
+     * returned; a slot that waits for the acknowledgement restores the committed entry beside its
+     * working one.
+     */
+    finish(retain: SemanticProgramRetention['retain'], promotedRevision: string | undefined, next?: {
+        index?: UnitIndex;
+        build?: RetainedBuild;
+    }, changes?: readonly FileChange[]): void;
+}

package/generator/compiler/semantic-closure.d.ts

@@ -0,0 +1,46 @@
+import type { CompilationRequest, ContentDescriptor, ContentIR, PageArtifact, RebuildReason, ServiceResult } from '../contracts.js';
+import { type Unit } from './common.js';
+import type { CompilationOptions } from './index.js';
+import type { GenerationPlan } from './plan.js';
+/**
+ * Scoped semantic invalidation (`NGDOC_SCOPED_SEMANTIC`): in a development generation, units and
+ * IRs record a `semantic-closure` per semantic query instead of the whole program's
+ * `semantic-reference`, and keep the program files they read as ordinary dependencies. An API edit
+ * then re-renders only the IRs whose recorded closure changed, on a FULL-synchronized program as
+ * well. Production generations keep the global reference, so their artifacts are unchanged.
+ *
+ * `verify` also renders every IR that its closure let the generation reuse, publishes the fresh IR
+ * and reports `COMPILATION_SCOPED_SEMANTIC_MISMATCH` when the two differ, and runs the recorder in
+ * `verify` mode (a node read outside the footprint fails the generation).
+ */
+export type ScopedSemanticMode = 'off' | 'on' | 'verify';
+export declare const SCOPED_SEMANTIC_ENV = "NGDOC_SCOPED_SEMANTIC";
+export declare const SCOPED_SEMANTIC_MISMATCH = "COMPILATION_SCOPED_SEMANTIC_MISMATCH";
+/**
+ * `NGDOC_SHAPE_CLOSURE=verify`: content reused on a closure that held only by its declaration
+ * shapes differs from a fresh render.
+ */
+export declare const SHAPE_CLOSURE_MISMATCH = "COMPILATION_SHAPE_CLOSURE_MISMATCH";
+/** The switch as the process sets it: the option first, then `NGDOC_SCOPED_SEMANTIC`. */
+export declare function scopedSemanticSwitch(options: CompilationOptions): ScopedSemanticMode;
+/**
+ * The mode of one generation: the switch, for development generations. A one-shot development
+ * generation records closures too, so its artifacts equal a long-lived runtime's; with no records
+ * to refresh from, it reuses a closure only while the program equals the previous candidate's.
+ */
+export declare function scopedSemanticMode(options: CompilationOptions, request: CompilationRequest): ScopedSemanticMode;
+/**
+ * The `whyRebuilt` fallback of a rebuilt owner the dependency index cannot explain: the first
+ * recorded closure (by key) whose digest changed, appeared or disappeared. It is derived from the
+ * two artifacts alone, so every path that rebuilds the owner reports the same reason.
+ */
+export declare function closureRebuildReason(previous: PageArtifact, current: Pick<PageArtifact, 'id' | 'dependencies' | 'content'>): RebuildReason | undefined;
+/**
+ * `verify`: renders an IR that the generation reuses on the strength of a recorded closure, and
+ * compares it with the reused one. Returns the fresh result, with a mismatch warning, when they
+ * differ (the caller publishes it); undefined when they are equal or there is nothing to check.
+ * `NGDOC_SCOPED_SEMANTIC=verify` checks every such IR; `NGDOC_SHAPE_CLOSURE=verify` the IRs one of
+ * whose closures held only by its declaration shapes, and reports them as
+ * {@link SHAPE_CLOSURE_MISMATCH}.
+ */
+export declare function verifyClosureReuse(plan: GenerationPlan, unit: Unit, descriptor: ContentDescriptor, reused: ContentIR): Promise<ServiceResult<ContentIR> | undefined>;