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

package/generator/semantic/program-state.d.ts

@@ -0,0 +1,196 @@
+import type { ClassDeclaration, EnumDeclaration, FunctionDeclaration, InterfaceDeclaration, Project, ts, TypeAliasDeclaration, VariableDeclaration } from 'ts-morph';
+import type { ApiScopeDescriptor, DeclarationDescriptor, Dependency, DiscoverySnapshot, EntryDescriptor, RetainedSemanticState, SemanticRetentionRequest } from '../contracts.js';
+import type { DirectoryListings, ObservationStamps } from '../graph/index.js';
+import { type TrackedFiles } from './dependencies.js';
+import type { OwnedRoots } from './owned-roots.js';
+import type { ProgramObservations } from './program-observations.js';
+import type { ClosureStore } from './semantic-closure.js';
+/**
+ * The typed program state of the semantic service.
+ *
+ * - {@link Snapshot}: the state one synchronization publishes to its queries.
+ * - {@link ProgramMirror}: the mutable description of a retained Project, shared by every retained
+ *   state made from it (the committed and the working entry of the retention slot).
+ * - {@link RetainedProgram}: the concrete retained program behind the opaque
+ *   {@link RetainedSemanticState}. Its published observations, semantic definition and stat stamps
+ *   are read from the mirror, never copied.
+ */
+/** The aggregate `semantic` definition of one synchronized program. */
+export type SemanticDefinition = Extract<Dependency, {
+    kind: 'semantic';
+}>;
+/**
+ * The declaration kinds an API page documents: the same union as the legacy
+ * `NgDocSupportedDeclaration` (`libs/builder/types`), spelled here so the generator's emitted
+ * declarations never reference a module outside the generator.
+ */
+export type SupportedDeclaration = ClassDeclaration | InterfaceDeclaration | EnumDeclaration | FunctionDeclaration | VariableDeclaration | TypeAliasDeclaration;
+export interface DeclarationState {
+    node: SupportedDeclaration;
+    descriptor: DeclarationDescriptor;
+    scope: ApiScopeDescriptor;
+}
+/**
+ * The program state of one successful synchronization, handed from one semantic service to the
+ * next development generation's service. Opaque to callers (the contract's
+ * `RetainedSemanticState`). It holds the TypeScript Project and the generator's own observations
+ * only; no evaluated user module.
+ */
+export type { RetainedSemanticState };
+/**
+ * What a retained program is re-verified against beyond its published observations (`files`):
+ * - `stamps`: stat stamps of every content observation (published and private);
+ * - `hidden`, `missingDirectories` and `realpaths`: private observations that are not part of the
+ *   published dependency set, the semantic digest or any revision (so cold and incremental
+ *   results, and the session's watch inputs, stay exactly as before): the file probes and reads of
+ *   the `types` directives (explicit and automatic), the directories module resolution found
+ *   missing (TypeScript probes no file inside a missing directory, so nothing else records an
+ *   install into it), and the symlinked paths resolution went through;
+ * - `listings`: the listing of every effective type root (automatic type directives enumerate its
+ *   packages) and of the directories on the way to each observed glob's members.
+ */
+export interface ProgramWatch {
+    stamps: ObservationStamps;
+    hidden: TrackedFiles;
+    /**
+     * Directories module resolution was told do not exist (`directoryExists` false; the path may
+     * be a file, which is not a directory). Verified with the same predicate, never by existence.
+     */
+    missingDirectories: string[];
+    /**
+     * Symlinked paths resolution went through, with the real path it got: a retarget
+     * between byte-identical files is otherwise invisible, because program files are observed under
+     * their real paths and the old target still exists unchanged.
+     */
+    realpaths: Array<[string, string]>;
+    listings: DirectoryListings;
+}
+/** Resolution facts a tracking host collects privately (see {@link ProgramWatch}). */
+export interface ResolutionProbes {
+    missing: Set<string>;
+    realpaths: Map<string, string>;
+}
+/**
+ * The mutable state of one retained Project, shared by reference by every {@link RetainedProgram}
+ * made from it: a reused or patched program's next retained state carries the same mirror, a FULL
+ * synchronization makes a new one. It always describes the Project as it is, not the base a
+ * retained entry names: a patch re-tracks and re-stamps what it applied.
+ */
+export interface ProgramMirror {
+    /**
+     * Paths patched into the Project that no successful synchronization has confirmed yet, with the
+     * digest of the bytes applied. Written before the Project is changed and cleared when a patched
+     * synchronization succeeds (the Project then equals its candidate's tree). It stays set only
+     * behind a failed patch, whose Project is handed back for its old base: the next synchronization
+     * of that Project re-reads and re-checks these paths and never reuses it as it is.
+     */
+    readonly appliedSinceBase: Map<string, string>;
+    /** Per-importer and global observations of the Project; the published set is their aggregate. */
+    readonly observations: ProgramObservations;
+    /** The re-verification state; a patch re-stamps the files it applied. */
+    readonly watch: ProgramWatch;
+    /**
+     * The root names of the program the FULL synchronization built. ts-morph re-creates a changed
+     * program from every file in its cache, which after `resolveSourceFileDependencies` holds the
+     * resolved dependencies too: a patch passes these roots instead, so the patched program keeps
+     * the cold file set and order (and TypeScript can reuse its structure). A root change
+     * (`restructureProgram`) replaces them with the root names a FULL synchronization of the new root
+     * membership has.
+     */
+    roots: readonly string[];
+    /** Bumped by every patch applied to the Project. */
+    version: number;
+}
+/** A new mirror for a program synchronized for retention. */
+export declare function createProgramMirror(observations: ProgramObservations, watch: ProgramWatch, roots: readonly string[]): ProgramMirror;
+/** The state one synchronization publishes to the queries of its generation. */
+export interface Snapshot {
+    project: Project;
+    discovery: DiscoverySnapshot;
+    /** The program's observations; `observations.files` is the published dependency set. */
+    observations: ProgramObservations;
+    declarations: Map<string, DeclarationState>;
+    scopes: Map<string, string[]>;
+    owned: OwnedRoots;
+    /** Present only for a synchronization made to be retained. */
+    retention?: {
+        key: string;
+        mirror: ProgramMirror;
+    };
+    /** Set when a query added source files to the Project; such a Project is never retained. */
+    mutated?: boolean;
+    /**
+     * The whole-program dependencies of `program`, tracked once for this synchronization and added
+     * to every query that depends on the whole program (`fragments.ts`, `trackWholeProgram`).
+     */
+    tracked?: {
+        program: ts.Program;
+        dependencies: readonly Dependency[];
+    };
+}
+/** The entry of the snapshot's discovery with this id. */
+export declare function entryOf(state: Snapshot, id: string): EntryDescriptor;
+interface RetainedProgramFields {
+    key: string;
+    project: Project;
+    scopes: Map<string, string[]>;
+    owned: OwnedRoots;
+    mirror: ProgramMirror;
+    closures?: ClosureStore;
+}
+/**
+ * The concrete retained program behind the opaque {@link RetainedSemanticState}: a class, so a
+ * state handed back to `synchronize` is checked with `instanceof` instead of being cast. A state
+ * this module did not make is never reused.
+ */
+export declare class RetainedProgram implements RetainedSemanticState {
+    readonly retained = true;
+    readonly key: string;
+    readonly project: Project;
+    readonly scopes: Map<string, string[]>;
+    readonly owned: OwnedRoots;
+    readonly mirror: ProgramMirror;
+    /**
+     * The closure records of the generation that retained this program, by digest. They describe
+     * digests, not this Project, so the next generation uses them whether it reuses the program or
+     * synchronizes a new one.
+     */
+    readonly closures?: ClosureStore;
+    constructor(fields: RetainedProgramFields);
+    /** The published observations (derived from the mirror on read). */
+    get files(): TrackedFiles;
+    /** The re-verification state (derived from the mirror on read). */
+    get watch(): ProgramWatch;
+}
+/** The sweep counters of a synchronization that kept its retained Project. */
+export interface SweepCounters {
+    stamped: number;
+    rehashed: number;
+    probed: number;
+    /** Directory listings verified by stat alone / read again. */
+    listed: number;
+    relisted: number;
+}
+/** How the last `synchronize` obtained its Project (instrumentation and tests). */
+export type SynchronizationPath = ({
+    path: 'reused';
+} & SweepCounters)
+/**
+ * The retained Project with the content of `files` applied to it. `failed`: the patched program
+ * failed the cold synchronization's syntax check; the Project is handed back as it is.
+ */
+ | ({
+    path: 'patched';
+    files: string[];
+    failed?: true;
+} & SweepCounters) | {
+    path: 'full';
+    reason: string;
+};
+/**
+ * Retention request of a development generation: build the Project so it can be retained and,
+ * when `previous` is given, reuse it instead of rebuilding if the request's changes and a stat
+ * sweep prove every observation of that program still holds. `previous` is consumed: removed from
+ * this object when the program is not kept.
+ */
+export type SemanticRetention = SemanticRetentionRequest;

package/generator/semantic/program-verify.d.ts

@@ -0,0 +1,22 @@
+import { type Project } from 'ts-morph';
+/**
+ * The semantic facts of a program that `NGDOC_INCREMENTAL_PROGRAM=verify` compares between a
+ * patched program and a cold synchronization of the same tree, beyond the observations, root names
+ * and texts: what the queries read through the checker, which a stale cache on an object a patched
+ * program reused (a symbol of an unchanged file) would change.
+ *
+ * For every workspace file of the program (not a default library, not under `node_modules`), in
+ * program order:
+ * - the program index facts: `token`, `exportSurface`, `typeClosure`, `dtsShape` and
+ *   `shapeClosure` (and `env` once);
+ * - the documentation TypeScript gives every export and every member of it (inherited
+ *   documentation included), with its tags;
+ * - the derived-class list of every top-level class, as the API template renders it.
+ *
+ * A fresh index is built for each program (never the shared one of `programIndex`, whose
+ * observations digest the closures of the generation use). Everything runs with recording
+ * suspended.
+ */
+export declare function programFacts(project: Project): Array<[string, string]>;
+/** The first fact whose name or value differs, or undefined when the two lists are equal. */
+export declare function firstFactDifference(left: ReadonlyArray<readonly [string, string]>, right: ReadonlyArray<readonly [string, string]>): string | undefined;

package/generator/semantic/recorder.d.ts

@@ -0,0 +1,89 @@
+import { Project } from 'ts-morph';
+import { type Footprint, type FootprintScopeKind, type RecorderMode, FootprintScope } from '../kernel/footprint.js';
+/** Runs `build` with recording suspended (shared indexes). */
+export declare function suspendRecording<T>(build: () => T): T;
+/**
+ * Runs `query`, the derived-class list of the class `identity` (`path#start`), recording only the
+ * identity into the current scope. The list depends on heritage clauses anywhere in the program,
+ * and the scope's semantic closure recomputes it (`derived`), so the query itself runs with
+ * recording suspended: the reference searches it makes would record whatever TypeScript resolves
+ * for the first time, which depends on what ran before, not on this scope.
+ */
+export declare function recordDerivedQuery<T>(identity: string, query: () => T): T;
+/** Channel 3: an explicit source-file lookup by path. */
+export declare function recordLookup(path: string): void;
+export interface RecordedAnswer<T> {
+    readonly value: T;
+    readonly footprint: Footprint;
+    /** Verify-mode gaps found while computing the answer; replayed on every use. */
+    readonly gaps: readonly string[];
+}
+/**
+ * A per-answer cache entry that replays what computing it recorded. The key is an identity
+ * (`path#name`, position), never a ts-morph node. The answer is always computed inside a capture
+ * scope, even when the caller's recording is suspended, so a hit never under-records.
+ */
+export declare function recordedAnswer<T>(cache: Map<string, RecordedAnswer<T>>, key: string, compute: () => T): T;
+export declare const SYMBOL_DOC_METHODS: readonly ["getDocumentationComment", "getContextualDocumentationComment", "getJsDocTags", "getContextualJsDocTags"];
+export declare const SIGNATURE_DOC_METHODS: readonly ["getDocumentationComment", "getJsDocTags"];
+/** The factory methods every wrapper is created or fetched through (ts-morph 28.0.0). */
+export declare const NODE_FACTORY_METHODS: readonly ["getNodeFromCompilerNode", "getSourceFile", "getSourceFileForNode"];
+export declare const VERIFIED_NODE_READS: readonly ["getJsDocs", "getText", "getFullText", "getStructure"];
+export interface RecorderCompatibility {
+    ok: boolean;
+    /** Why recording is off when `ok` is false. */
+    reason?: string;
+    typescript: string;
+}
+/**
+ * The pinned-version probe, run once per process on a two-file in-memory project: TypeScript's
+ * `TypeObject`/`SymbolObject` methods reach the wrapped checker, ts-morph wrappers come through all
+ * three factory methods, and `findReferences` reaches the wrapped language service. Any failure
+ * turns recording off.
+ */
+export declare function recorderCompatibility(): RecorderCompatibility;
+/** Test hook: forget the cached probe result. */
+export declare function resetRecorderCompatibility(): void;
+/**
+ *
+ */
+export declare function probeRecorder(): RecorderCompatibility;
+/** One open scope of a semantic query. */
+export declare class RecordingScope {
+    readonly scope: FootprintScope;
+    private open;
+    constructor(scope: FootprintScope);
+    /** The files-channel observer handed to the query's `TrackedFiles`. */
+    readonly observe: (dependency: Parameters<FootprintScope["observe"]>[0]) => void;
+    /**
+     * Closes the scope. In verify mode a recorder gap (a node read outside the footprint, or a
+     * failure while recording) throws `SEMANTIC_RECORDER_GAP`; outside verify mode nothing throws.
+     */
+    close(assert?: boolean): Footprint;
+    /** Removes the scope from the stack if it is still open. */
+    dispose(): void;
+}
+/** A semantic service's recorder: its mode, and hook installation on each Project it queries. */
+export declare class SemanticRecorder {
+    readonly mode: RecorderMode;
+    /**
+     * Why recording is off although the mode asks for it (the probe or an install failed). Once set
+     * it is never cleared: this recorder then opens no scope again.
+     */
+    unavailable?: string;
+    constructor(mode: RecorderMode);
+    /**
+     * Installs the channels on the project's current program (idempotent; a re-created program gets
+     * its checker wrapped here) and returns whether recording is available.
+     */
+    ensure(project: Project): boolean;
+    /** Opens a scope for one phase call, or undefined when recording is off or unavailable. */
+    open(kind: FootprintScopeKind, key: string, project: Project | undefined): RecordingScope | undefined;
+}
+/** Test and diagnostics hook: the number of open scopes (0 between queries). */
+export declare function openRecordingScopes(): number;
+/**
+ * Closes every scope and ends every suspension. For use between queries only, after a query was
+ * terminated (V8's `vm` watchdog runs no `finally` block, so its scopes were never closed).
+ */
+export declare function resetRecording(): void;

package/generator/semantic/rendering.d.ts

@@ -0,0 +1,34 @@
+import { type JSDocableNode, Node } from 'ts-morph';
+import type { TrackedFiles } from './dependencies.js';
+export type MarkdownRenderer = (markdown: string, context: {
+    source: string;
+    read(path: string): string;
+}) => string;
+/** Standalone parity default; a caller may inject another renderer (the `markdown` option). */
+export declare const renderMarkdown: MarkdownRenderer;
+/** Same TSDoc excerpt/status traversal as the legacy Formatter, with an explicit renderer. */
+export declare function createJsDoc(markdown: (text: string) => string): {
+    getJsDocDescription: (node?: JSDocableNode) => string;
+    getJsDocTags: (node: JSDocableNode | undefined, name: string) => string[];
+    getJsDocTag: (node: JSDocableNode | undefined, name: string) => string;
+    hasJsDocTag: (node: JSDocableNode | undefined, name: string) => boolean;
+    getAllJsDocTags: (node?: JSDocableNode) => Record<string, string[]>;
+    getJsDocParam: (node: JSDocableNode | undefined, name: string) => string;
+};
+export type JsDoc = ReturnType<typeof createJsDoc>;
+/** The Angular signal function that declares a member, as the symbol view's members table shows it. */
+export interface SignalMember {
+    /** `input`, `model` or `output`. */
+    kind: 'input' | 'model' | 'output';
+    /** Whether it is `input.required()` or `model.required()`. */
+    required: boolean;
+}
+/**
+ * Tells a signal input, model or output from its initializer (`input()`, `input.required()`,
+ * `model()`, `model.required()`, `output()`, `outputFromObservable()`), so the members table
+ * shows it as an input or output the way it shows `@Input()` and `@Output()`. It reads only the
+ * member's own syntax.
+ * @param node - A class member.
+ */
+export declare function signalMember(node: Node): SignalMember | undefined;
+export declare function renderApiTemplate(template: string, context: object, root: string, files: TrackedFiles, markdown: (text: string) => string, configDirectory?: string): string;

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

@@ -0,0 +1,129 @@
+import type { Dependency, SemanticClosureDependency } from '../contracts.js';
+import type { FlagValue } from '../kernel/flags.js';
+import type { Footprint } from '../kernel/footprint.js';
+import type { Snapshot } from './program-state.js';
+/**
+ * Recorded semantic closures: in a scoped development generation every semantic query records one
+ * `semantic-closure` dependency, `{ scopeId, key: <query>, digest }`, in place of the global
+ * `semantic-reference`. The digest covers exactly the program files the query's
+ * footprint read (`R`), their type closures, the program environment and the derived-class lists
+ * it read (`ProgramIndex`).
+ *
+ * The artifact carries only the digest. `R` stays with the retained program (`ClosureStore`,
+ * keyed by digest, so a record always belongs to the digest it produced), and the refresher
+ * recomputes the digest from it over the current program. A digest without a record still holds
+ * when the whole program equals the one of the previous candidate, since every closure is a
+ * function of the program; otherwise it refreshes as changed and its unit is recomputed, as without
+ * scoping. A runtime that carries no records (a fresh runtime, a recycle) is seeded from the
+ * persistent store (`compiler/closure-store.ts`, {@link SemanticClosures.seed}). A record is
+ * checked every time it is used: the digest covers `R` and the derived identities themselves, so
+ * a record recomputes to its dependency's digest only when it is that digest's record and the
+ * closure holds, whatever its source. The store also keeps its program's file order: with
+ * `stableTypeOrdering` output depends on the relative order of the files that declare the printed
+ * types, so when two files both programs have swapped places no earlier closure is confirmed
+ * (every closure refreshes as changed); files added or removed reorder no surviving file.
+ *
+ * Shape closures (`NGDOC_SHAPE_CLOSURE`, on by default) follow the files of `R` by their content
+ * and their declaration-shape closures (`ProgramIndex.closure` with `shape`): a body edit that
+ * keeps every declaration shape then changes only the closures whose `R` holds the edited file.
+ * Their keys carry {@link SHAPE_KEY_SUFFIX}, so a digest recorded in the other mode never holds
+ * without a record (a cache restored across a switch change). `verify` reports every closure that
+ * holds only by its shapes as narrowed ({@link SemanticClosures.narrowed}): its type-closure digest
+ * changed since its query recorded it, or is not known (a record carried from a generation that did
+ * not keep it); the compiler then renders the content reused on it again and compares.
+ */
+/** The mode of shape closures: `off` keeps type closures for every file of `R`. */
+export type ShapeClosureMode = FlagValue;
+/** The key suffix of a closure recorded with shape closures. */
+export declare const SHAPE_KEY_SUFFIX = "@shape";
+/** What one closure digest was computed from. */
+export interface ClosureRecord {
+    /** `R`: the program files the query's semantic channels touched, sorted. */
+    readonly files: readonly string[];
+    /** The classes whose derived-class list the query read, sorted. */
+    readonly derived: readonly string[];
+    /**
+     * Shape closures in `verify` mode: per closure key, the closure's digest with type closures only
+     * when that query last recorded this digest (queries with equal footprints share a record).
+     */
+    readonly wide?: Readonly<Record<string, string>>;
+    /**
+     * Set only on a record the service hands to the persistent store (`closureRecord`): the file
+     * order of the program it holds on, which the store keeps as the seeded records' order.
+     */
+    readonly order?: readonly string[];
+}
+/**
+ * Closure records by digest, handed from one generation of a runtime to the next, with the file
+ * order of the program they were refreshed on ({@link programOrder}).
+ */
+export type ClosureStore = ReadonlyMap<string, ClosureRecord> & {
+    readonly order?: readonly string[];
+};
+export declare class SemanticClosures {
+    private readonly shape;
+    /** Whether queries record closures (a scoped development generation). */
+    enabled: boolean;
+    private previous;
+    /** Whether the previous records' program and the current one order every common file alike. */
+    private ordered?;
+    private current;
+    /** The whole-program digest of the previous candidate's program. */
+    private base?;
+    /** Digests whose record came from the persistent store in this generation (see `seed`). */
+    private seeded;
+    /** `verify`: the closures (`key` and digest) that held only by their shapes in this generation. */
+    private readonly narrowedClosures;
+    constructor(shape?: ShapeClosureMode);
+    /** Starts a generation: its mode, and the records of the generation it continues. */
+    start(enabled: boolean, previous: ClosureStore | undefined): void;
+    /**
+     * Seeds a generation that carries no records of its runtime with the records of the persistent
+     * store (`load` is called only then). They are used as the carried records are: each is checked
+     * when it is used, and the next generation carries it.
+     */
+    seed(load: () => ClosureStore): void;
+    /** The record of a closure digest, recorded, refreshed or carried in this generation. */
+    recorded(digest: string): ClosureRecord | undefined;
+    /** The whole-program `semantic` digest of the previous candidate (from its aggregate artifact). */
+    setBase(digest: string | undefined): void;
+    /**
+     * The closure dependency of one query, or undefined when its footprint cannot state one (the
+     * caller then records the global reference).
+     */
+    record(state: Snapshot, key: string, footprint: Footprint): SemanticClosureDependency | undefined;
+    /**
+     * The current digest of a recorded closure, or undefined when it cannot be recomputed (no
+     * record, and a program other than the previous candidate's).
+     */
+    refresh(state: Snapshot, dependency: SemanticClosureDependency): string | undefined;
+    /**
+     * `verify`: whether the closure held in this generation only by its shapes (its type closures
+     * changed), so the content reused on it is rendered again and compared.
+     */
+    narrowed(dependency: SemanticClosureDependency): boolean;
+    /** Whether the program equals the previous candidate's, so every recorded closure holds. */
+    holds(state: Snapshot | undefined): boolean;
+    /**
+     * The records the next generation of this runtime refreshes against, with the file order of
+     * `state`'s program (the one they hold on); without it the next generation cannot use them.
+     */
+    retained(state?: Pick<Snapshot, 'project'>): ClosureStore;
+}
+/**
+ * The file order of the snapshot's current program: its source file names in program order, one
+ * array per program. A program the patch or a restructuring re-created is a new program.
+ */
+export declare function programOrder(state: Pick<Snapshot, 'project'>): readonly string[];
+/**
+ * Whether every pair of files that both orders contain is in the same relative order in both:
+ * files added or removed reorder nothing, two surviving files that swapped places do.
+ */
+export declare function sameRelativeOrder(before: readonly string[], after: readonly string[]): boolean;
+/** The whole-program `semantic` digest recorded by a candidate's aggregate artifact. */
+export declare function programDigestOf(artifacts: ReadonlyArray<{
+    identity: {
+        role: string;
+    };
+    dependencies: Dependency[];
+}>): string | undefined;

package/generator/semantic/semantic-service.d.ts

@@ -0,0 +1,186 @@
+import type { DeclarationDescriptor, JsonValue, SemanticClosureDependency, SemanticFragment, SemanticFragmentRequest, SemanticProgramRetention, SemanticProgramSynchronization, SemanticService, ServiceResult } from '../contracts.js';
+import { type RecorderMode } from '../kernel/footprint.js';
+import { type ProgramWatchFacts } from './program-retention.js';
+import { type RetainedSemanticState, type SynchronizationPath } from './program-state.js';
+import { type MarkdownRenderer } from './rendering.js';
+import { type ClosureRecord, type ClosureStore, type ShapeClosureMode } from './semantic-closure.js';
+/**
+ * The semantic service: one TypeScript program per generation, and the queries over it.
+ *
+ * Module map:
+ * - `program-builder.ts`: builds the Project of a discovery snapshot (program lifecycle);
+ * - `program-observations.ts`: per-importer and global program tracking, and their aggregate;
+ * - `program-retention.ts`: the retention key, the re-verification state and the reuse check;
+ * - `program-state.ts`: the typed state (snapshot, `ProgramMirror`, `RetainedProgram`);
+ * - `api-enumeration.ts`: the declarations of an API entry (queries);
+ * - `fragments.ts`: JSDoc fragments and API templates (rendering).
+ * This facade orchestrates `synchronize`, runs every query in its recorder scope, and hands the
+ * retained program to the next generation.
+ */
+export { declarationIdentity } from './api-enumeration.js';
+export type { RetainedSemanticState, SemanticRetention, SynchronizationPath, } from './program-state.js';
+export interface SemanticServiceOptions {
+    /** Caller retains synchronize provenance and resolves query references through it. */
+    dependencyMode?: 'full' | 'scope-reference';
+    templateRoot?: string;
+    markdown?: MarkdownRenderer;
+    /** Discovery-local evaluated JSON hook; never exposes live values, Nodes, or functions. */
+    readGuideValues?: (entryId: string) => ServiceResult<JsonValue>;
+    /**
+     * The footprint recorder: `on` attaches each query's recorded footprint to its result out of
+     * band (`footprintOf`), `verify` also fails a query that reads a node outside it.
+     * Defaults to `NGDOC_SEMANTIC_RECORDER` (on unless `0`). Results are identical in every mode.
+     */
+    recorder?: RecorderMode;
+    /**
+     * The incremental program: `on` patches the content edits of program files into a
+     * retained program instead of synchronizing a new one; `verify` also synchronizes a cold program
+     * after every patch, keeps the patched one only when the two are equal, and otherwise uses the
+     * cold one and warns `SEMANTIC_PATCH_MISMATCH`. Defaults to `NGDOC_INCREMENTAL_PROGRAM` (on unless
+     * `0`). Only a synchronization that is handed a retained program can patch it.
+     */
+    incrementalProgram?: IncrementalProgramMode;
+    /**
+     * Shape closures (`semantic-closure.ts`): `on` follows the files of a closure by
+     * their content and declaration-shape closures; `verify` also reports every closure that
+     * holds only by its shapes as narrowed (`closureNarrowed`). Defaults to `NGDOC_SHAPE_CLOSURE` (on
+     * unless `0`). Only scoped generations record closures.
+     */
+    shapeClosure?: ShapeClosureMode;
+    /**
+     * Whether the queries of one synchronization that depend on the whole program share one
+     * tracking of it (`fragments.ts`, `trackWholeProgram`). Defaults to `NGDOC_TRACKED_PROGRAM_REUSE`
+     * (on unless `0`); off, every such query tracks the program again. Results are identical.
+     */
+    trackedProgramReuse?: boolean;
+}
+export type IncrementalProgramMode = 'off' | 'on' | 'verify';
+/** Warns that a patched program differed from a cold synchronization (`verify` only). */
+export declare const SEMANTIC_PATCH_MISMATCH = "SEMANTIC_PATCH_MISMATCH";
+export declare class SemanticServiceImpl implements SemanticService, SemanticProgramRetention {
+    private readonly options;
+    private snapshot?;
+    private revision;
+    private disposed;
+    private readonly recorder;
+    /** The rendering helpers every query uses, bound to this service's options. */
+    private readonly context;
+    /** Recorded semantic closures; on only for scoped development generations. */
+    private readonly closures;
+    private scoped;
+    private readonly incremental;
+    /** The taken program a failed patch hands back (the port's `patched-failed`). */
+    private handedBack?;
+    /**
+     * Queries started and not yet returned. A query that never returns was terminated: a template
+     * action runs a query inside the template's `vm` render, whose watchdog terminates the render
+     * without running any `finally` block. The TypeScript checker, the recorder and the Project may
+     * then hold the state of a half-done query.
+     */
+    private running;
+    /** A query of this program was terminated: it is never retained, and answers no more queries. */
+    private interrupted;
+    constructor(options?: SemanticServiceOptions);
+    /** The recorder's mode and, when it asked for recording but the probe failed, why it is off. */
+    recording(): {
+        mode: RecorderMode;
+        unavailable?: string;
+    };
+    private lastSynchronization?;
+    /**
+     * Whether the next synchronization's queries record `semantic-closure` dependencies instead of
+     * the global `semantic-reference` (a scoped development generation). Only the `scope-reference`
+     * dependency mode records closures.
+     */
+    scopeClosures(enabled: boolean): void;
+    /** The previous candidate's whole-program digest, which confirms closures without a record. */
+    closureBase(digest: string | undefined): void;
+    /**
+     * After `synchronize`: seeds a generation whose runtime carries no closure records with the
+     * records of the persistent store (`compiler/closure-store.ts`); `load` runs only then.
+     */
+    seedClosures(load: () => ClosureStore): void;
+    /**
+     * The record of a closure digest this generation holds, for the persistent store, with the file
+     * order of this generation's program: without it a restored record confirms no closure after an
+     * edit (`SemanticClosures`).
+     */
+    closureRecord(digest: string): ClosureRecord | undefined;
+    /**
+     * The current digest of a recorded closure (the refresher's source), or undefined when it cannot
+     * be recomputed, which refreshes it as changed.
+     */
+    refreshClosure(dependency: SemanticClosureDependency): string | undefined;
+    /**
+     * The current digest of the whole program a `semantic-reference` names, for a scoped generation,
+     * whose descriptors do not carry the reference (a query whose footprint could not state its
+     * closure records it instead). Undefined when closures are off or the scope is another.
+     */
+    refreshReference(dependency: {
+        scopeId: string;
+    }): string | undefined;
+    /**
+     * Shape closures in `verify` mode: whether the closure held in this generation only by its
+     * declaration shapes, so the content reused on it must be rendered again and compared.
+     */
+    closureNarrowed(dependency: SemanticClosureDependency): boolean;
+    /**
+     * Whether every closure recorded against the previous candidate still holds without a refresh:
+     * the program equals that candidate's (always true when closures are off).
+     */
+    closuresHold(): boolean;
+    /** How the last `synchronize` obtained its Project (instrumentation and tests). */
+    synchronization(): SynchronizationPath | undefined;
+    /** The retention port's view of the last `synchronize`. */
+    programSynchronization(): SemanticProgramSynchronization | undefined;
+    synchronize(request: Parameters<SemanticService['synchronize']>[0], signal: AbortSignal): Promise<ServiceResult<null>>;
+    /** Publishes a kept (reused or patched) retained program to this generation's queries. */
+    private keep;
+    /**
+     * Patches the retained program (`patchProgram`). A refused or throwing patch leaves a Project
+     * that must not be kept; in `verify` mode a patch that differs from a cold synchronization of the
+     * same tree is refused as a mismatch.
+     */
+    private patch;
+    /** A FULL synchronization: a new Project, made retainable when `key` is given. */
+    private build;
+    enumerateApi(entryId: string): ServiceResult<DeclarationDescriptor[]>;
+    describeGuide(entryId: string): ServiceResult<import("../contracts.js").GuideSemantics>;
+    renderFragment(request: SemanticFragmentRequest): ServiceResult<SemanticFragment>;
+    /**
+     * Forgets the declarations this generation enumerated so far. A full attempt enumerates every
+     * API entry again, in entry order, and each entry's routes are disambiguated only against the
+     * declarations of earlier entries: the targeted path's admission enumerated all of them first.
+     */
+    forgetDeclarations(): void;
+    /**
+     * The current Project for the next development generation, or undefined when this service did
+     * not synchronize for retention, has no successful synchronization, or a query changed the
+     * Project's source files (the next generation's cold Project would not contain them).
+     */
+    retain(): RetainedSemanticState | undefined;
+    /**
+     * The current program's private observations as JSON (`watchFacts`), which a later process
+     * checks before it trusts a candidate built on this program without building it again (the fast
+     * start). Undefined when {@link retain} would retain nothing, or a listing cannot vouch for its
+     * directory.
+     */
+    programWatchFacts(): ProgramWatchFacts | undefined;
+    dispose(): Promise<void>;
+    /** Resource counters for host diagnostics/tests; no compiler objects escape. */
+    inspect(): {
+        projects: number;
+        declarations: number;
+    };
+    private check;
+    private markdown;
+    /**
+     * Runs one query in its own recorder scope. The recorded footprint is attached to the returned
+     * result out of band; the result itself is exactly what it was without the recorder.
+     */
+    private run;
+    /** Marks the program interrupted when a query never returned, and resets the recorder. */
+    private noteInterruption;
+    private query;
+}
+export declare function createSemanticService(options?: SemanticServiceOptions): SemanticServiceImpl;