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

package/generator/build-provenance.json

@@ -0,0 +1,121 @@
+{
+  "compilerVersion": "0.0.1",
+  "toolchainDigest": "d3b66d41f47865fb003a881897f703f6b49568eefa8f301d410768b97f5647e2",
+  "sourceDigest": "1a038ca999385c919ea565f867343af2f42f244061951c14649d551b1082c31d",
+  "lockfileDigest": "de382fb15a8f808000ec7fba99c68f6b8329faa07755202f04ac25d0f1c8ef64",
+  "tuple": {
+    "@angular-devkit/architect": "0.2202.1",
+    "@angular-devkit/core": "22.2.1",
+    "@microsoft/tsdoc": "0.15.1",
+    "@ng-doc/core": "0.0.0",
+    "@ng-doc/utils": "0.0.0",
+    "@orama/orama": "2.0.17",
+    "@orama/plugin-parsedoc": "2.0.17",
+    "@parcel/watcher": "2.6.0",
+    "@prettier/sync": "0.5.2",
+    "@shikijs/rehype": "4.5.0",
+    "cosmiconfig": "8.2.0",
+    "cosmiconfig-typescript-loader": "5.0.0",
+    "css-what": "6.1.0",
+    "esbuild": "0.27.2",
+    "fast-glob": "3.3.3",
+    "find-cache-dir": "3.3.2",
+    "github-slugger": "2.0.0",
+    "gray-matter": "4.0.3",
+    "hast-util-has-property": "3.0.0",
+    "hast-util-heading-rank": "3.0.0",
+    "hast-util-is-element": "3.0.0",
+    "hast-util-to-string": "3.0.0",
+    "jsonc-parser": "3.3.1",
+    "magic-string": "0.30.21",
+    "marked": "12.0.1",
+    "minimatch": "9.0.9",
+    "ng-morph": "4.9.0",
+    "nunjucks": "3.2.4",
+    "obug": "2.1.3",
+    "oxc-parser": "0.121.0",
+    "parsimmon": "1.18.1",
+    "posthtml-parser": "0.11.0",
+    "posthtml-render": "3.0.0",
+    "prettier": "3.2.5",
+    "rehype": "13.0.1",
+    "rehype-minify-whitespace": "6.0.0",
+    "rehype-parse": "9.0.0",
+    "rehype-stringify": "10.0.1",
+    "rxjs": "7.8.2",
+    "shiki": "4.5.0",
+    "stringify-entities": "4.0.4",
+    "tinyglobby": "0.2.17",
+    "ts-morph": "28.0.0",
+    "tslib": "2.8.1",
+    "typescript": "6.0.3",
+    "unified": "11.0.5",
+    "unist-util-filter": "5.0.1",
+    "unist-util-visit": "5.0.0",
+    "unist-util-visit-parents": "6.0.2"
+  },
+  "runtimeExternals": [
+    "@angular-devkit/architect",
+    "@angular/compiler",
+    "@angular/compiler-cli",
+    "@microsoft/tsdoc",
+    "@orama/plugin-parsedoc",
+    "@parcel/watcher",
+    "@prettier/sync",
+    "@shikijs/rehype",
+    "css-what",
+    "esbuild",
+    "fast-glob",
+    "github-slugger",
+    "gray-matter",
+    "hast-util-has-property",
+    "hast-util-heading-rank",
+    "hast-util-is-element",
+    "hast-util-to-string",
+    "magic-string",
+    "marked",
+    "minimatch",
+    "nunjucks",
+    "obug",
+    "oxc-parser",
+    "parsimmon",
+    "posthtml-parser",
+    "posthtml-render",
+    "rehype",
+    "rehype-minify-whitespace",
+    "rehype-parse",
+    "rehype-stringify",
+    "rxjs",
+    "shiki",
+    "stringify-entities",
+    "tinyglobby",
+    "ts-morph",
+    "typescript",
+    "unified",
+    "unist-util-filter",
+    "unist-util-visit",
+    "unist-util-visit-parents",
+    "vite"
+  ],
+  "angularCompatibility": {
+    "format": "ng-doc-analog-2.8.0-resources-v1",
+    "upstream": {
+      "name": "@analogjs/vite-plugin-angular",
+      "version": "2.8.0",
+      "license": "MIT"
+    },
+    "sourceInventorySha256": "59d7bbf119ca438674d11d3e1123b589f238d0d03ff34de9e46b284e0b7d0dc7",
+    "patchedSources": [
+      {
+        "path": "lib/angular-vite-plugin.js",
+        "sha256": "0d60401c25875de0aa06aeb991b8e27324f40cb51403dc061cc1c07db47fee5f",
+        "patchedSha256": "8a4b18a6ca06183a483b324d61b9d49863556ffeab0ff02f10253a187ead403e"
+      },
+      {
+        "path": "lib/encapsulate-component-styles-plugin.js",
+        "sha256": "6dd369d15c54ed8070eb10d3876bdf2b4e8ceb60be39275c7acd497c50a7c1d0",
+        "patchedSha256": "03c38e8443e7c41ab49f035d88fd7560f98acffbc1c212b7957fe82f5294a64d"
+      }
+    ]
+  }
+}

package/generator/compiler/assemble.d.ts

@@ -0,0 +1,41 @@
+import type { ArtifactSnapshot, DiscoverySnapshot, PageArtifact } from '../contracts.js';
+import { type Unit } from './common.js';
+import type { KeywordPlan, LinkOutcome } from './link.js';
+import { type GenerationPlan } from './plan.js';
+import type { ReplayScope } from './targeted.js';
+/** `whyRebuilt` of previous owners that discovery no longer produces. */
+export declare function recordRemovedOwners(plan: GenerationPlan, units: Unit[]): void;
+/**
+ * Assembly phase: per unit its outputs, routes and API list (from the assembly memo when it
+ * provably holds), then the artifact with its revision (the previous one when value-equal) and
+ * its `whyRebuilt` reasons.
+ *
+ * On the targeted path (`scope`), a replayed unit outside the link set is not assembled again:
+ * its assembly inputs (entry, declaration, descriptors, semantics, metadata, linked content and
+ * the output templates) are those of its previous page, so the assembler would return that page's
+ * outputs, routes and API list, and its retained record holds what assembling emitted. A settled
+ * unit (its previous artifact was already built from the reuse projection) keeps that artifact;
+ * any other still gets its artifact and revision computed here, exactly as below.
+ */
+export declare function assembleUnits(plan: GenerationPlan, units: Unit[], linked: LinkOutcome, scope?: ReplayScope): PageArtifact[];
+/** The site-wide outputs of the assembled pages. */
+export interface SiteAggregate {
+    outputs: PageArtifact['outputs'];
+}
+/** Aggregate phase: the global outputs (routes, context, indexes, keywords). */
+export declare function aggregateUnits(plan: GenerationPlan, artifacts: PageArtifact[], keywordPlan: KeywordPlan): SiteAggregate;
+/**
+ * The candidate snapshot: appends the aggregate artifact to `artifacts`, reports outputs of
+ * unchanged owners that are missing on disk, and validates the semantic scope references.
+ */
+export declare function candidateSnapshot(plan: GenerationPlan, artifacts: PageArtifact[], keywordPlan: KeywordPlan, site: SiteAggregate): ArtifactSnapshot;
+/**
+ * The snapshot of a generation's artifacts (the aggregate last) and its discovery: what a
+ * generation publishes, and what the fast start restores from the cache (`./fast-start`).
+ */
+export declare function snapshotOf(projectId: string, found: DiscoverySnapshot, artifacts: PageArtifact[]): ArtifactSnapshot;
+/**
+ * Writes the artifact cache (skipping entries the memo proves current) and its index. `unchanged`:
+ * the targeted path's unchanged artifacts, whose cache facts the memo already carries.
+ */
+export declare function writeCache(plan: GenerationPlan, artifacts: PageArtifact[], unchanged?: (artifact: PageArtifact) => boolean): Promise<void>;

package/generator/compiler/classify.d.ts

@@ -0,0 +1,161 @@
+import type { EntryDescriptor, FileChange, KeywordExport } from '../contracts.js';
+import { type UnitIndex } from '../graph/unit-index.js';
+/**
+ * The change classifier and the affected closure of the targeted rebuild. Pure functions over a
+ * committed build's {@link UnitIndex}: the targeted path (`./targeted`) goes FULL on anything they
+ * do not classify as content, an evaluated entry input, a program input or a structural change it
+ * can scope (see {@link classifyChanges}), and `verify` checks their closure against the full
+ * generation.
+ */
+export type ChangeClass = 'config-toolchain' | 'structural' | 'entry' | 'semantic' | 'content' | 'unknown';
+export interface PathClassification {
+    path: string;
+    /** The event kind as reported; ignored by the classification (see `classifyPath`). */
+    kind: FileChange['kind'];
+    class: ChangeClass;
+    detail: string;
+    /** An `entry` or `semantic` path that is an input of the TypeScript program. */
+    program?: true;
+    /**
+     * A structural (or unknown) path the structural class may scope: it moves the entry set, a
+     * discovery or program glob, or the program's file set, which a targeted generation observes
+     * again in full (discovery, the program's root membership, the entry diff), never a
+     * content-level glob. An unknown path must be read by the generation's fresh discovery, program
+     * or rebuilt units (`PathPass.unknown`).
+     */
+    scoped?: true;
+}
+export interface PathPass {
+    classes: PathClassification[];
+    /** Why the generation must be FULL, or undefined when every path may be targeted. */
+    full?: string;
+    /**
+     * Set when the candidates exceed the dirty threshold. A performance rule, not a correctness
+     * one: a targeted generation that large would cost about as much as a full one, so it runs in
+     * full; the dry run still checks the closure.
+     */
+    threshold?: string;
+    /** Candidate units (owner IDs) and descriptor/IR IDs. */
+    units: Set<string>;
+    descriptors: Set<string>;
+    /**
+     * Unknown paths a targeted attempt takes (the structural class): each must be read by this
+     * generation's discovery, its program or a unit it rebuilds, or the generation runs FULL.
+     */
+    unknown: string[];
+    /**
+     * Whether a generation may keep its keyword loaders' last results instead of running them:
+     * the preconditions hold and every path may be targeted (no path is config/toolchain,
+     * structural or unknown). The loaders and the files they import are configuration inputs, so a
+     * targeted path never reaches them; and a generation that then publishes anything but a targeted
+     * result runs discovery again without the pin. It must be decided before discovery runs
+     * (discovery invokes the loaders), which is why it comes from the path pass and not from the
+     * later equality check (`TargetedGeneration.pin`).
+     */
+    pin: boolean;
+}
+/** What the path pass may send down the targeted path besides content edits. */
+export interface PathPassOptions {
+    /**
+     * Program inputs (`semantic` paths, and `entry` paths the program also reads), and the
+     * structural class (`PathClassification.scoped`, which changes the program's root membership):
+     * only a generation whose units record semantic closures can refresh a replayed unit's program
+     * facts, so without them such a change goes FULL here rather than after discovery.
+     */
+    program: boolean;
+}
+/**
+ * The dirty threshold: above it a targeted generation would not pay off. The unit share applies
+ * only beyond a small floor: on a small site a full generation costs little either way, and a
+ * shared include there reaches a large share of the units.
+ */
+export declare const DIRTY_UNIT_SHARE = 0.2;
+export declare const DIRTY_UNIT_FLOOR = 8;
+export declare const DIRTY_DESCRIPTORS = 200;
+/** Whether `units` candidates of `owners` units with `descriptors` descriptors exceed the threshold. */
+export declare function dirty(units: number, owners: number, descriptors: number): boolean;
+/**
+ * Classifies one changed path by the current state of the filesystem, never by the event kind:
+ * an atomic save (an editor's safe write, a backup rename) may report `delete` and `create` of one
+ * path in different batches, and the `delete` of a file that exists again is an ordinary edit.
+ * A path may have several roles (a page module is usually a program input too). First match wins:
+ *
+ * 1. config/toolchain: a program configuration file; a path with the configuration, header
+ *    template or structural output template role;
+ * 2. entry: a description module, or an input of an entry's evaluated closure, that still exists
+ *    and moves no discovery, content-level or program glob (discovery evaluates it again, and the
+ *    fresh-discovery check decides which entries changed);
+ * 3. structural: a description module or an evaluated entry input that no longer exists, a
+ *    discovery or content-level glob whose membership changed, an ancestor directory of a
+ *    recorded path, a guide's markdown file that no longer exists;
+ * 4. semantic: a program input, or a program glob whose membership changed;
+ * 5. content: a path a unit recorded (descriptor, unit or observed level);
+ * 6. unknown: anything else.
+ *
+ * Every structural path but a content-level glob change, a program glob change, a program input
+ * that no longer exists, and an unknown path are `scoped`: the structural class takes them.
+ */
+export declare function classifyPath(index: UnitIndex, change: FileChange): PathClassification;
+/**
+ * The path pass: classifies every changed path, then applies the dirty threshold to the
+ * candidates. The candidates are the units that recorded a changed path; the targeted path adds,
+ * after discovery and the program synchronization, every entry whose descriptor or evaluated value
+ * changed (or that was added), every unit whose semantic closure changed, and every API
+ * declaration whose enumeration changed. `precondition` is the first failed precondition, if any;
+ * the paths are still classified for the record.
+ */
+export declare function classifyChanges(index: UnitIndex, changes: FileChange[], precondition?: string, options?: PathPassOptions): PathPass;
+/** What the generation's own (fresh) discovery and keyword set say, for the closure. */
+export interface FreshBuild {
+    configurationDigest: string;
+    entries: EntryDescriptor[];
+    keywords: KeywordExport[];
+}
+export interface Closure {
+    /** Set when the fresh-discovery equality check fails: the generation is FULL. */
+    full?: string;
+    /** Entries whose descriptor or evaluated value changed (their units are candidates). */
+    entries: Set<string>;
+    /** The keyword diff K: keys whose binding changed, appeared or disappeared. */
+    keys: string[];
+    /** One-hop consumers of K that are not candidates themselves. */
+    consumers: Set<string>;
+    /** Candidates ∪ consumers: the units the targeted path would re-describe, render or relink. */
+    units: Set<string>;
+}
+/** What the fresh-discovery equality check found: a FULL reason, or the entries that changed. */
+export interface DiscoveryChanges {
+    full?: string;
+    /** Entries whose descriptor (any field, its dependencies included) differs from the base's. */
+    entries: Set<string>;
+    /** With `structural`: entries of the fresh discovery the base has no entry for. */
+    added: Set<string>;
+    /** With `structural`: entries of the base the fresh discovery no longer has. */
+    removed: Set<string>;
+}
+/**
+ * The fresh-discovery equality check: the configuration digest and the entry set must equal the
+ * retained ones, and every entry must keep its kind. An entry whose descriptor differs in any other
+ * way (its title, route or data, its markdown files and their digests, the inputs of its evaluated
+ * closure, its evaluated value) is reported as changed: its units are described again, and every
+ * other unit replays exactly what the full path would build for it, since a unit's describe,
+ * render and assembly read no other entry's descriptor (the site-wide outputs, which do, are
+ * aggregated in full). This also covers what no event reported, for example a file a page module
+ * reads through a computed `require`. The live guide values `describeGuide` reads (playground
+ * controls from the evaluated page) are compared by the targeted path itself.
+ *
+ * With `structural` (the structural class) the entry set may differ: an entry the base does not
+ * have is `added`, one the fresh discovery no longer has is `removed`, and an entry whose kind
+ * changed is changed (its units change identity: the old ones are removed, the new ones added).
+ * Breadcrumbs, routes and parents are descriptor fields, so a moved page and the descendants of an
+ * edited category are changed entries.
+ */
+export declare function discoveryChanges(index: UnitIndex, fresh: Pick<FreshBuild, 'configurationDigest' | 'entries'>, structural?: boolean): DiscoveryChanges;
+/** The keys whose binding differs between the retained and the fresh keyword set (K). */
+export declare function keywordDiff(index: UnitIndex, keywords: KeywordExport[]): string[];
+/**
+ * The affected closure of a targeted generation: the path pass's candidates and the units of every
+ * changed entry, plus the one-hop consumers of K. One hop is enough because exports come only from
+ * entries and IR, which relinking does not change.
+ */
+export declare function affectedClosure(index: UnitIndex, pass: PathPass, fresh: FreshBuild): Closure;

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

@@ -0,0 +1,55 @@
+import { type CompilationRequest, type DiscoverySnapshot, type PageArtifact } from '../contracts.js';
+import type { ClosureRecord, ClosureStore } from '../semantic/semantic-closure.js';
+import type { CompilationOptions } from './index.js';
+import type { ScopedSemanticMode } from './semantic-closure.js';
+/**
+ * The persistent store of semantic closure records, beside the artifact cache.
+ *
+ * A closure record (`R` and the derived-class identities of one query) lives in the runtime that
+ * recorded it. The startup generation of a development server runs in a one-shot runtime, and a
+ * restart restores its artifacts from the cache, so the long-lived runtime that serves the edits
+ * would start without records: its first program edit would refresh every closure as changed and
+ * rebuild every semantic unit. Each development generation that writes the cache therefore also
+ * writes the records of every closure its candidate holds, and a runtime that carries no records
+ * is seeded from them (`SemanticClosures.seed`).
+ *
+ * A stored record is a fact that is checked every time it is used, as a carried one is: the
+ * closure digest covers the record's files and derived identities, so a record recomputes to its
+ * dependency's digest only when it is that digest's record and the closure holds. A missing,
+ * stale or corrupt store therefore only makes units render again; it never changes output.
+ *
+ * The store is kept only where the targeted rebuild and scoped semantic invalidation are on, for
+ * development generations with incremental reuse and the cache enabled: `NGDOC_TARGETED_REBUILD=0`
+ * (and `NGDOC_SCOPED_SEMANTIC=0`, the reference path, production) neither reads nor writes it.
+ *
+ * A start restored from a cache written without a store (or with a store another compiler,
+ * schema or configuration wrote) writes an almost empty one: its reused IRs have no records. Its
+ * first program edit then rebuilds the semantic units, as without the store, and the store holds
+ * their records from then on.
+ */
+/** What a store must have been written by to be read: the compiler, schema and configuration. */
+export interface ClosureStoreIdentity {
+    compilerVersion: string;
+    toolchainDigest: string;
+    configurationDigest: string;
+}
+/**
+ * The store of a generation, or undefined when it keeps none: a development generation with
+ * incremental reuse, the cache, scoped semantic invalidation and the targeted rebuild on.
+ */
+export declare function closureStorePath(options: CompilationOptions, request: CompilationRequest, configuration: DiscoverySnapshot['configuration'], scopedSemantic: ScopedSemanticMode): string | undefined;
+/** Reads a store. Absent, unreadable, invalid or of another compiler, schema or configuration: empty. */
+export declare function loadClosureStore(file: string, identity: ClosureStoreIdentity): ClosureStore;
+/**
+ * Writes the records of every closure the artifacts hold (their dependencies and their IRs'),
+ * as far as `record` knows them. Best effort, atomically replaced: a store that is not written only
+ * makes a later runtime render again.
+ */
+export declare function saveClosureStore(file: string, identity: ClosureStoreIdentity, artifacts: readonly PageArtifact[], record: (digest: string) => ClosureRecord | undefined): Promise<void>;
+/**
+ * Removes the temporary files a save of `file` left behind when its process was killed. A
+ * temporary file younger than {@link STALE_TEMPORARY_MS} may belong to a save in progress.
+ */
+export declare function sweepTemporaries(file: string): Promise<void>;
+/** Forgets what this process read or wrote (tests). */
+export declare function resetClosureStores(): void;

package/generator/compiler/common.d.ts

@@ -0,0 +1,32 @@
+import type { ArtifactIdentity, ContentDescriptor, ContentIR, DeclarationDescriptor, DeferredContentRequest, Dependency, Diagnostic, EntryDescriptor, GuideSemantics, KeywordExport, PageArtifact, RouteRecord } from '../contracts.js';
+import { canonicalJson, dependencyIdentity, digestOf } from '../kernel/canonical.js';
+import type { UnitRecord } from './fold.js';
+/** One page shell, category or API declaration of the current discovery. */
+export interface Unit {
+    id: string;
+    identity: ArtifactIdentity;
+    entry: EntryDescriptor;
+    declaration?: DeclarationDescriptor;
+    requests: DeferredContentRequest[];
+    descriptors: ContentDescriptor[];
+    dependencies: Dependency[];
+    ir: ContentIR[];
+    previous?: PageArtifact;
+    inputDigest: string;
+    ownerInputDigest: string;
+    metadata?: RouteRecord['metadata'];
+    semantics?: GuideSemantics;
+    /** What this unit's phases emitted, replayed by `fold`. */
+    record: UnitRecord;
+}
+/** Canonical JSON (`kernel/canonical.ts`): code-unit key order, `undefined` members omitted. */
+export declare const stable: typeof canonicalJson;
+/** The one value digest: `sha256` of the canonical JSON. */
+export declare const hash: typeof digestOf;
+export declare const diagnostic: (code: string, message: string, severity?: Diagnostic["severity"]) => Diagnostic;
+export declare const dependencyKey: typeof dependencyIdentity;
+export declare const uniqueDependencies: (values: Dependency[]) => Dependency[];
+export declare function sameValue(left: unknown, right: unknown): boolean;
+export declare function inputDigest(unit: Unit, dependencies: Dependency[]): string;
+export declare function unitExports(unit: Unit): KeywordExport[];
+export declare function sameStrings(left: string[], right: string[]): boolean;

package/generator/compiler/describe.d.ts

@@ -0,0 +1,21 @@
+import type { DeclarationDescriptor, EntryDescriptor, ServiceResult } from '../contracts.js';
+import { type Unit } from './common.js';
+import type { GenerationPlan } from './plan.js';
+/** How the targeted path has an API entry described (`TargetedGeneration.describing`). */
+export interface DescribePlan {
+    /** The entry's enumeration of this generation, used instead of enumerating it again. */
+    enumerated: ServiceResult<DeclarationDescriptor[]>;
+    /**
+     * Appends the retained unit of `declaration` (undefined: the entry's own unit) instead of
+     * describing it, and says whether it did. The entry's own unit holds the enumeration's record.
+     */
+    replay?(declaration: DeclarationDescriptor | undefined): boolean;
+}
+/**
+ * Describe phase of one discovered entry: its page shell or category unit and, for an API entry,
+ * one unit per declaration, each with its content requests, descriptors and dependencies. Every
+ * completed unit is appended to `units`; what each step emits is recorded on the unit's record
+ * (the entry's `enumerateApi` on its first unit). With `described` (the targeted path), an API
+ * entry takes the given enumeration, and the units it replays are appended in their place.
+ */
+export declare function describeEntry(plan: GenerationPlan, entry: EntryDescriptor, units: Unit[], described?: DescribePlan): Promise<void>;

package/generator/compiler/dry-run.d.ts

@@ -0,0 +1,108 @@
+import type { ArtifactSnapshot, CompilationRequest } from '../contracts.js';
+import type { PathPass } from './classify.js';
+import { type TargetedGeneration, changedArtifacts } from './targeted.js';
+/**
+ * The targeted rebuild's report: one record per development generation that retains a program
+ * while the targeted rebuild is on (`CompilationOptions.targetedRebuild`, resolved by bootstrap
+ * from `NGDOC_TARGETED_REBUILD`). It says which path the generation took and why, and with
+ * `verify` what the comparison with the full generation found.
+ *
+ * A file the report appends one JSON line per generation to (optional; for harnesses).
+ */
+export declare const TARGETED_REBUILD_TRACE_ENV = "NGDOC_TARGETED_REBUILD_TRACE";
+/** The code a difference between the targeted and the full generation is reported under. */
+export declare const TARGETED_MISMATCH = "COMPILATION_TARGETED_MISMATCH";
+/** One generation's path, and with `verify` its check against the full generation. */
+export interface DryRunRecord {
+    generation: number;
+    base: string | null;
+    revision: string | null;
+    /** `content`: the targeted path compiled this generation; `full`: it did not (with `reason`). */
+    path: 'content' | 'full';
+    /** Which compilation the result came from. */
+    published: 'targeted' | 'full';
+    reason?: string;
+    pin: boolean;
+    /** Whether discovery kept the keyword loaders' last results, and whether it ran again without. */
+    loaders?: 'pinned' | 'refreshed';
+    /** The structural class: the entries this generation added and removed. */
+    entries?: {
+        added: string[];
+        removed: string[];
+    };
+    /** The dirty threshold was exceeded (the generation ran FULL). */
+    threshold?: string;
+    classes: PathPass['classes'];
+    /** Changes of earlier generations against this base that did not commit, added to its own. */
+    pending: number;
+    /** Paths the stat sweep found changed without an event. */
+    swept: string[];
+    candidates: {
+        units: number;
+        descriptors: number;
+    };
+    /** The keyword diff K and its one-hop consumers. */
+    keys: string[];
+    /** Whether K came from the candidates' exports or from every key (global/remote keywords changed). */
+    keysFrom?: 'candidates' | 'all';
+    consumers: number;
+    /** Units linked and assembled by the targeted path (content path only). */
+    closure: string[];
+    /** `verify`: units whose artifact revision the full generation changed. */
+    actual: string[];
+    /** `verify`: changed units outside the closure. */
+    misses: string[];
+    /** |closure \ actual| (`verify`, content path only). */
+    superset: number;
+    /**
+     * `verify`: the first JSON path where the targeted and the full results differ. The full
+     * result is published and the difference is reported under {@link TARGETED_MISMATCH}.
+     */
+    mismatch?: string;
+    timings: {
+        sweepMs: number;
+        classifyMs: number;
+        admitMs: number;
+        targetedMs: number;
+        fullMs: number;
+        retainMs: number;
+    };
+    error?: string;
+}
+export interface DryRunReport {
+    counters: {
+        generations: number;
+        /** Generations the targeted path compiled (content) or not (full). */
+        content: number;
+        full: number;
+        /** `verify` generations with misses or a mismatch. */
+        misses: number;
+        mismatches: number;
+        noCandidate: number;
+        errors: number;
+    };
+    last?: DryRunRecord;
+}
+/**
+ * What the targeted rebuild did in this runtime. The long-lived worker runtime reads it through
+ * the compilation module (an optional export beside `createCompilationService`) to return each new
+ * record with its reply, since the worker's own stderr goes nowhere.
+ */
+export declare function targetedDryRun(): DryRunReport;
+export declare function resetTargetedDryRun(): void;
+/** Units whose artifact changed between two snapshots (the aggregate artifact excluded). */
+export declare const changedUnits: typeof changedArtifacts;
+/** The first JSON path at which two JSON values differ (`$` when their types differ). */
+export declare function firstDifference(left: unknown, right: unknown, at?: string): string | undefined;
+/** Writes the record of one generation (see {@link DryRunRecord}). */
+export declare function reportGeneration(input: {
+    request: CompilationRequest;
+    targeted: TargetedGeneration;
+    published: 'targeted' | 'full';
+    candidate: ArtifactSnapshot | undefined;
+    /** `verify`, when both compilations returned a candidate: the full one. */
+    full?: ArtifactSnapshot;
+    mismatch?: string;
+    timings: Pick<DryRunRecord['timings'], 'targetedMs' | 'fullMs' | 'retainMs'>;
+    error?: string;
+}): void;

package/generator/compiler/fast-start.d.ts

@@ -0,0 +1,104 @@
+import { type CompilationRequest, type CompilationResult, type DiscoverySnapshot, type PageArtifact } from '../contracts.js';
+import { type ProgramWatchFacts } from '../semantic/program-retention.js';
+import type { Contribution } from './fold.js';
+import type { CompilationOptions } from './index.js';
+/**
+ * The fast start: a development start whose recorded inputs all re-read identically publishes the
+ * candidate of the generation that recorded them, without building the TypeScript program or
+ * rendering, linking and assembling anything.
+ *
+ * Every development generation that writes the artifact cache also writes, beside it, a record of
+ * its result: the candidate's revision, the result's dependencies and diagnostics, the digest of
+ * its discovery (the snapshot and what discovery recorded), and the private observations of its
+ * program (`ProgramWatchFacts`). A start (a development `buildOnce`, which has no previous
+ * snapshot) runs discovery as always, so user modules are evaluated and keyword loaders refresh,
+ * and then takes the record only when all of this holds:
+ *
+ * - the record was written by this compiler, schema, options and engine switches, in a process
+ *   with the same runtime (`runtimeIdentity`: Node, ICU, the default locale, TypeScript and the
+ *   versions of the packages that shape output);
+ * - discovery produced exactly the recorded snapshot, dependencies and diagnostics;
+ * - every recorded physical dependency (content by its bytes' digest, existence, glob membership)
+ *   and every private observation of the program re-reads identically: the program a
+ *   synchronization would build now is then the recorded one, so every semantic digest the
+ *   candidate holds is current;
+ * - the artifact cache holds every artifact of the recorded candidate, each equal to its revision.
+ *
+ * The candidate is then the recorded one, assembled from the cache entries and the fresh discovery
+ * exactly as a generation assembles it, and the result's dependencies are exact: each was the
+ * digest of the bytes the recorded generation compiled, and those bytes are unchanged. Anything
+ * else (no record, another engine, a changed or unreadable input, an incomplete cache) is a reason,
+ * and the generation goes on as without the fast start. The long-lived runtime builds the program
+ * afterwards in its warm-up, so the first edit still compiles only what it reaches.
+ *
+ * `NGDOC_FAST_START=0` (or `CompilationOptions.fastStart: false`) turns it off, together with the
+ * reuse of the cache index's links and assemblies on a start after edits (`restoredReuse`).
+ * `verify` restores and then compiles from scratch (the reference path's options, no previous
+ * artifacts, no memo or closure store), publishes that result and reports
+ * `COMPILATION_FAST_START_MISMATCH` when the two candidates differ: a compile that reused the
+ * cache could not see an input that both the record and the cached artifacts lack.
+ */
+/** The warning a `verify` start reports when the restored candidate differs from the compiled one. */
+export declare const FAST_START_MISMATCH = "COMPILATION_FAST_START_MISMATCH";
+/**
+ * Whether a start may reuse the links, assemblies and revisions of the cache index's artifacts,
+ * as a generation reuses those of the session's snapshot (`GenerationPlan.sessionPrevious`), when
+ * each of them is {@link intact}.
+ */
+export declare function restoredReuse(options: CompilationOptions): boolean;
+/**
+ * The fast start's mode for this request, or undefined: only a development generation without a
+ * previous snapshot or watched changes (a start) with incremental reuse may take it.
+ */
+export declare function fastStartMode(options: CompilationOptions, request: CompilationRequest): 'on' | 'verify' | undefined;
+/** Where a generation of this request keeps its record, or undefined when it keeps none. */
+export declare function fastStartPath(options: CompilationOptions, request: CompilationRequest, configuration: DiscoverySnapshot['configuration']): string | undefined;
+/** Every engine switch but this one (`verify` and `on` record the same thing), as read now. */
+export declare function engineSwitches(): Array<[string, string]>;
+/**
+ * What the process that compiles brings to a generation besides the options: the Node and ICU
+ * versions and the default locale (`localeCompare` and `Intl` without a locale depend on them),
+ * the TypeScript that ts-morph runs, and the resolved versions of the packages that shape output
+ * (`runtimePackages`). 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 runtimeIdentity(): Record<string, unknown>;
+/**
+ * Writes the record of a generation's published result. Best effort and atomic: a record that is
+ * not written only makes the next start compile.
+ */
+export declare function saveFastStart(file: string, input: {
+    options: CompilationOptions;
+    /** The engine switches as the compilation service read them when it was created. */
+    switches: ReadonlyArray<[string, string]>;
+    found: DiscoverySnapshot;
+    discovery: readonly Contribution[];
+    result: CompilationResult;
+    program: ProgramWatchFacts;
+}): Promise<void>;
+/** The outcome of {@link restoreFastStart}: the restored result, or why there is none. */
+export type FastStart = {
+    result: CompilationResult;
+} | {
+    reason: string;
+};
+/**
+ * The recorded result, when every recorded input holds (see the module comment), or the reason
+ * the start compiles.
+ */
+export declare function restoreFastStart(input: {
+    file: string;
+    options: CompilationOptions;
+    /** The engine switches as the compilation service read them when it was created. */
+    switches: ReadonlyArray<[string, string]>;
+    found: DiscoverySnapshot;
+    discovery: readonly Contribution[];
+    signal: AbortSignal;
+}): Promise<FastStart>;
+/**
+ * Whether a restored artifact is the one its revision names. The cache vouches for an entry by its
+ * identity and fingerprint only; an entry damaged in place may still parse.
+ */
+export declare function intact(artifact: PageArtifact): boolean;
+/** Forgets what this process read or wrote, and the runtime identity it read (tests). */
+export declare function resetFastStarts(): void;