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

package/generator/compiler/targeted.d.ts

@@ -0,0 +1,280 @@
+import type { ArtifactSnapshot, CompilationContext, CompilationRequest, Dependency, DiscoverySnapshot, EntryDescriptor, JsonValue, KeywordExport, PageArtifact, RemoteKeywordSnapshot, ServiceResult } from '../contracts.js';
+import { type DependencyRefresher, type ObservationStamp } from '../graph/index.js';
+import { type UnitIndex } from '../graph/unit-index.js';
+import type { SynchronizationPath } from '../semantic/semantic-service.js';
+import { type PathPass } from './classify.js';
+import { type Unit } from './common.js';
+import type { DescribePlan } from './describe.js';
+import type { CompilationOptions } from './index.js';
+import type { GenerationPlan } from './plan.js';
+import type { GenerationRetention } from './retention.js';
+/**
+ * The targeted rebuild: a development watch generation whose changes are content, page (entry),
+ * program or structural edits compiles only the units they reach, and replays every other unit
+ * from the retained build of its base.
+ *
+ * - Before discovery, the changes (with the changes of every generation against the same base that
+ *   did not commit, and the paths a stat sweep of the retained observations finds changed) are
+ *   classified against the base's reverse index. Anything but content, an evaluated entry input
+ *   (a page module or a file it imports), an existing program input or a structural change the
+ *   structural class scopes (entries added, removed or moved, a discovery or program glob that
+ *   gained or lost a file, a deleted program file, an unknown path) goes FULL; program inputs and
+ *   structural changes only while the generation records semantic closures.
+ * - After discovery and the semantic synchronization, the fresh-discovery check: the
+ *   configuration, the `onlyForTags` exclusions and the output templates must equal the base's.
+ *   Every entry the base does not have is described, the units of every entry it no longer has are
+ *   dropped, and every entry whose descriptor or evaluated value changed becomes a candidate (all
+ *   of its units), as does a guide whose live values (playground controls read from its evaluated
+ *   page) changed. When the program is not the base's (it was patched or synchronized again), every
+ *   replayed unit's semantic closures are refreshed against it, as the full path's reuse predicate
+ *   does, and each unit whose closure changed makes its entry a candidate (an API declaration only
+ *   itself). API entries are enumerated again, in entry order, whenever the program or the entry
+ *   set may have changed: a declaration the enumeration adds, drops or describes differently is
+ *   described (or dropped) on its own, and every other declaration unit is replayed.
+ * - Candidates are described, rendered, linked and assembled by the full path's own code (its
+ *   reuse predicates included). Every other unit is replayed: its retained records are what the
+ *   full path would record for it, and its previous artifact is what the full path would build.
+ *   The keyword set is combined in full, and the one-hop consumers of every key whose binding
+ *   changed are linked and assembled again. The site-wide outputs (routes, context, search index,
+ *   keywords, API lists) are aggregated in full, the output existence scan covers every previously
+ *   published output, and the fold builds the result as the full path does.
+ * - Any doubt goes FULL in the same generation: a precondition, a class, the equality check, the
+ *   dirty threshold, a digest conflict, an unknown path no rebuilt unit read, and any error
+ *   diagnostic of the targeted attempt (the full path is the arbiter of failures).
+ */
+/** `on`: targeted generations; `verify`: each targeted generation is also compiled in full and compared. */
+export type TargetedMode = 'on' | 'verify';
+export declare function targetedMode(options: CompilationOptions): TargetedMode | undefined;
+/** One unit of a retained build: its state and records once its generation completed. */
+export interface RetainedUnit {
+    /** Never changed after its generation (`previous` is dropped). */
+    unit: Unit;
+    /**
+     * Every render step of its generation reused the previous IR: its dependency list and input
+     * digest are the reuse projection, so its artifact is exactly what the full path builds for it
+     * while its inputs stay unchanged.
+     */
+    settled: boolean;
+}
+/** What discovery and setup produced, compared by the fresh-discovery equality check. */
+interface DiscoveryFacts {
+    configuration: string;
+    order: string;
+    filtered: string;
+    globalKeywords: string;
+    remoteKeywords: string;
+    templates: string;
+}
+/**
+ * The stat of a recorded path when its generation observed it: a regular file's stamp, a path that
+ * did not exist or was not a file, or `unverifiable` (written while it was observed, or recorded
+ * with a conflicting digest): the sweep always reports that one as changed.
+ */
+export type Observation = ObservationStamp | 'missing' | 'present' | 'unverifiable';
+/** The per-unit records and facts of one successful build, retained for the next generation. */
+export interface RetainedBuild {
+    units: RetainedUnit[];
+    byEntry: Map<string, RetainedUnit[]>;
+    /** Guide entry → `readGuideValues` as JSON. */
+    guideValues: Map<string, string>;
+    observations: Map<string, Observation>;
+    /** Content-level glob dependencies of the units (their membership is refreshed). */
+    globs: Dependency[];
+    facts: DiscoveryFacts;
+    /** The keyword loaders' results of the build: a targeted attempt's discovery pins them. */
+    remoteKeywords: RemoteKeywordSnapshot[];
+}
+/** What the phases ask of the targeted path about one unit. */
+export interface ReplayScope {
+    /** The retained unit a replayed unit was built from; undefined for a described unit. */
+    retained(unit: Unit): RetainedUnit | undefined;
+    /** A replayed unit that is not linked and assembled again (not a one-hop consumer). */
+    keepsLink(unit: Unit): boolean;
+}
+/** Thrown inside a targeted attempt: the generation runs FULL instead, for `message`. */
+export declare class TargetedFallback extends Error {
+}
+type GuideValues = (entryId: string) => ServiceResult<JsonValue>;
+/** The report fields the targeted path fills for its generation (see `dry-run.ts`). */
+export interface TargetedFacts {
+    path: 'content' | 'full';
+    reason?: string;
+    pass?: PathPass;
+    pending: number;
+    swept: string[];
+    candidates: {
+        units: number;
+        descriptors: number;
+    };
+    keys: string[];
+    /** Whether K was computed over the candidates' exports or (global/remote keywords changed) all keys. */
+    keysFrom?: 'candidates' | 'all';
+    consumers: number;
+    closure: string[];
+    /**
+     * `pinned`: discovery kept the base's keyword loader results; `refreshed`: it was pinned, and
+     * ran again with the loaders evaluated because the generation did not publish a targeted result.
+     */
+    loaders?: 'pinned' | 'refreshed';
+    /** The structural class: entries the fresh discovery added and removed, by ID. */
+    entries?: {
+        added: string[];
+        removed: string[];
+    };
+    timings: {
+        sweepMs: number;
+        classifyMs: number;
+        admitMs: number;
+    };
+}
+/** One generation's use of the targeted path (created before discovery). */
+export declare class TargetedGeneration implements ReplayScope {
+    readonly mode: TargetedMode;
+    private readonly request;
+    private readonly committed;
+    private readonly startedNs;
+    readonly facts: TargetedFacts;
+    /** Candidate units (owner IDs) and their entries. */
+    readonly candidates: Set<string>;
+    /** Entries described in full (their descriptor changed, or the base has none). */
+    private readonly candidateEntries;
+    /** Entries of the base the fresh discovery no longer has. */
+    private removedEntries;
+    /**
+     * API entries described declaration by declaration: their enumeration changed, or one of their
+     * units is a candidate. The others are replayed (see {@link describing}).
+     */
+    private readonly apiEntries;
+    /** API entries whose own unit is described (its record holds the enumeration, which changed). */
+    private readonly apiShells;
+    /** This generation's enumeration of every API entry, when it had to run again. */
+    private readonly enumerations;
+    /** Base owners the generation no longer has (known once the keyword set is combined). */
+    private removedOwners;
+    /** Unknown paths no fresh discovery or program input explains (a rebuilt unit must read them). */
+    private unknown;
+    private readonly replayed;
+    private linked;
+    /** K, and whether it was computed over every key (otherwise over the candidates' exports). */
+    private keys;
+    private everyKey;
+    private keywordFacts;
+    /**
+     * Whether the generation's discovery inputs or program may differ from the base's (a changed
+     * entry, a program synchronized again): the retained index then builds its input roles again.
+     */
+    private inputsChanged;
+    /** Live guide values read in this generation (the retained ones for the next). */
+    readonly guideValues: Map<string, string>;
+    private constructor();
+    /**
+     * Undefined when the targeted rebuild is off or the generation retains nothing (production,
+     * one-shot, the reference path): such a generation is FULL and builds no retained state.
+     */
+    static start(options: CompilationOptions, request: CompilationRequest, context: CompilationContext | undefined, retention: GenerationRetention, startedNs: bigint): TargetedGeneration | undefined;
+    /** The base's reverse index, when there is one for this generation's base. */
+    get index(): UnitIndex | undefined;
+    /** Whether the path pass allows a targeted attempt (the equality check still follows). */
+    get eligible(): boolean;
+    /**
+     * The keyword loader results discovery keeps instead of invoking the loaders, when the path pass
+     * allows a targeted attempt: the base's. Loaders are evaluated on every other generation (the
+     * pin is refreshed by each FULL generation and by a restart). Decided before discovery, which
+     * invokes the loaders; a generation that then does not publish a targeted result runs discovery
+     * again without the pin.
+     */
+    pin(): RemoteKeywordSnapshot[] | undefined;
+    /** The generation runs FULL, for `reason` (the first reason is kept). */
+    full(reason: string): void;
+    /**
+     * The fresh-discovery equality check and the other admission rules, after discovery, the
+     * semantic synchronization and setup. False (with a reason) when the generation must run FULL.
+     * It may add candidates: a guide whose live values changed.
+     */
+    admit(input: {
+        found: DiscoverySnapshot;
+        synchronization: SynchronizationPath | undefined;
+        plan: GenerationPlan;
+        readGuideValues: GuideValues;
+        refresher: DependencyRefresher;
+    }): Promise<boolean>;
+    private admission;
+    /**
+     * The unknown paths of the path pass that neither this generation's discovery nor its program
+     * read (a directory is explained by what they read below it).
+     */
+    private unexplained;
+    /**
+     * Compares an API entry's fresh enumeration with its retained units: the entry's own unit holds
+     * the enumeration's contribution (its first describe record), each declaration unit its
+     * descriptor. A difference makes the entry one described declaration by declaration, with its
+     * own unit described when the contribution changed and each declaration whose descriptor changed
+     * a candidate; new declarations are described and dropped ones removed.
+     */
+    private enumerationDiff;
+    /**
+     * Whether a refresh changes a non-physical dependency a replayed unit recorded (its describe
+     * records and its published artifact with every IR). `semantic`: the semantic closures and
+     * references are refreshed too; otherwise the program is the base's and they hold.
+     */
+    private replayedChanged;
+    /**
+     * Describe phase of an entry with no candidate: appends its retained units, with records that
+     * hold what the full path's describe (and, for a settled unit, render) phases would record.
+     * False for an entry the caller describes: a candidate, a new entry, or an API entry described
+     * declaration by declaration ({@link describing}).
+     */
+    replay(plan: GenerationPlan, entry: EntryDescriptor, units: Unit[]): boolean;
+    /**
+     * How the caller describes an entry {@link replay} did not replay: an API entry takes this
+     * generation's enumeration (enumerated for every API entry in entry order, so a second call
+     * would see later entries' declarations), and one that is not a candidate replays its own unit
+     * when its enumeration's contribution is unchanged and each declaration whose unit is unchanged.
+     */
+    describing(plan: GenerationPlan, entry: EntryDescriptor, units: Unit[]): DescribePlan | undefined;
+    /** Appends one retained unit with the records the full path would hold for it. */
+    private replayUnit;
+    retained(unit: Unit): RetainedUnit | undefined;
+    keepsLink(unit: Unit): boolean;
+    /**
+     * After render: a path a candidate read in this generation with other bytes than a replayed
+     * unit recorded changed without an event that reached this generation. The full path would
+     * refresh and render that unit again, so the generation runs FULL. Only digests of the same
+     * recorder (the content compiler) are compared.
+     */
+    conflict(units: Unit[]): string | undefined;
+    /**
+     * After the keyword set is combined: the keyword diff K and the link set (candidates plus the
+     * one-hop consumers of K). One hop is exact: exports come only from entries and IR, and linking
+     * changes neither.
+     */
+    closure(units: Unit[], keywords: KeywordExport[]): void;
+    /**
+     * After assembly: every unknown path of the path pass that no fresh discovery or program input
+     * read must be read by a unit this generation built; otherwise the full path decides.
+     */
+    explain(artifacts: PageArtifact[], units: Unit[]): void;
+    /** The units a targeted generation linked and assembled (for the report). */
+    get closureUnits(): ReadonlySet<string>;
+    /**
+     * The retained build and index of this generation's published units, for the next generation.
+     * `targeted`: the published result is this generation's targeted attempt, so the base's build
+     * and index are overlaid; otherwise both are built from scratch.
+     */
+    retain(input: {
+        targeted: boolean;
+        units: Unit[];
+        candidate: ArtifactSnapshot;
+        found: DiscoverySnapshot;
+        plan: GenerationPlan;
+        keywords: KeywordExport[];
+        discovery: Dependency[];
+        guideValues: Map<string, string>;
+    }): {
+        index: UnitIndex;
+        build: RetainedBuild;
+    };
+}
+/** Changed units between two snapshots (the aggregate artifact excluded). */
+export declare function changedArtifacts(previous: ArtifactSnapshot | undefined, candidate: ArtifactSnapshot): string[];
+export {};

package/generator/content/code-snippet.d.ts

@@ -0,0 +1,20 @@
+/** The code of a named snippet, or why a file has none. */
+export type SnippetRegion = {
+    status: 'found';
+    code: string;
+} | {
+    status: 'unknown';
+} | {
+    status: 'unclosed';
+};
+/**
+ * The region of `text` between the first `snippet#<id>` marker and the next marker with the same
+ * id, as a code block's `file="./x.ts"#<id>` shows it: every marker line inside it is removed
+ * (nested snippets included, as in demos) and so are `ng-doc-ignore-line` lines, blank lines
+ * around it are dropped, and the common indentation is taken off, so a region inside a class
+ * reads like top-level code. Lines end with LF whatever the file uses, so the output never
+ * depends on the platform that saved the file.
+ * @param text - The whole file.
+ * @param id - The snippet id.
+ */
+export declare function snippetRegion(text: string, id: string): SnippetRegion;

package/generator/content/content-compiler.d.ts

@@ -0,0 +1,122 @@
+import type { ContentCompiler, ContentCompilerServices, ContentDescriptor, ContentDescriptorProvenance, ContentIR, ContentRequest, DeferredContentRequest, KeywordExport, LinkedContent, ServiceResult } from '../contracts.js';
+import { type HighlightSession } from './highlight-cache.js';
+import { type LinkedDocument, type LinkTask, type RenderedDocument, type RenderTask } from './html-pipeline.js';
+/** The warning of `NGDOC_PARALLEL_RENDER=verify` (`./html-pool`). */
+export declare const PARALLEL_RENDER_MISMATCH = "CONTENT_PARALLEL_MISMATCH";
+/**
+ * Where a generation runs the back half of its content (`./html-pipeline`): in the main thread or
+ * on render threads (`./html-pool`). Either way a task's result is the pipeline's result for its
+ * input, so the content compiler cannot tell them apart.
+ */
+export interface ContentBack {
+    render(task: RenderTask, signal: AbortSignal): Promise<RenderedDocument[]>;
+    link(task: LinkTask, keywords: readonly KeywordExport[], signal: AbortSignal): Promise<LinkedDocument>;
+}
+/** A link whose back half was dispatched ahead of its turn (`prepareLink`). */
+export interface PreparedLink {
+    readonly ir: ContentIR;
+    readonly keywords: KeywordExport[];
+    readonly outcome: Promise<LinkedDocument>;
+}
+/**
+ * Stateless, per-document content compiler. It never touches legacy stores.
+ *
+ * A compile has a front, which reads files, evaluates templates and queries the program, and a back
+ * half, the HTML pipeline, which is a pure function of the HTML the front produced
+ * (`./html-pipeline`). `compileStaged` resolves once the front is done and the back half is
+ * dispatched, so a caller can run the next front while the back half of this one runs elsewhere.
+ */
+export declare class GeneratorContentCompiler implements ContentCompiler {
+    private readonly services;
+    private readonly highlight?;
+    private readonly back?;
+    /** The Shiki grammars highlighting loads (`grammarsSwitch`). */
+    private readonly grammars;
+    /**
+     * @param services - What the compiler reads.
+     * @param highlight - The generation's cache of highlighted code blocks; without it, every block
+     *   is highlighted (`./highlight-cache`).
+     * @param back - Where the HTML pipeline runs; without it, in this thread, at once.
+     */
+    constructor(services: ContentCompilerServices, highlight?: HighlightSession | undefined, back?: ContentBack | undefined, 
+    /** The Shiki grammars highlighting loads (`grammarsSwitch`). */
+    grammars?: 'used' | 'all');
+    /**
+     * Whether this call records its footprint. The semantic service's effective recorder state
+     * decides when it reports one: a service that records nothing, or whose probe or install failed,
+     * gets no content footprint either. Otherwise the environment
+     * decides. A query that still returns no footprint makes the content footprint incomplete.
+     */
+    private recording;
+    /**
+     * One recorder scope per content phase call. The files channel is every physical dependency the
+     * call reports, and the semantic queries it made are merged in. The footprint is attached to the
+     * result out of band; the result itself is unchanged.
+     */
+    private scope;
+    private sealed;
+    describe(request: DeferredContentRequest, provenance: ContentDescriptorProvenance, signal: AbortSignal): Promise<ServiceResult<ContentDescriptor>>;
+    private describeContent;
+    compile(request: ContentRequest, signal: AbortSignal, descriptor?: ContentDescriptor): Promise<ServiceResult<ContentIR>>;
+    /**
+     * `compile` in two stages: resolves once the front of the compile is done (everything it reads,
+     * evaluates and queries) and its HTML pipeline is dispatched to the back (`ContentBack`); `finish`
+     * then settles with exactly what `compile` returns. The rest of the compile after the pipeline is
+     * pure, so a caller may start the next front before `finish` settles: the fronts, and with them
+     * the semantic queries and their order, stay those of sequential compiles.
+     */
+    compileStaged(request: ContentRequest, signal: AbortSignal, descriptor?: ContentDescriptor): Promise<{
+        finish: Promise<ServiceResult<ContentIR>>;
+    }>;
+    private compileContent;
+    private descriptorFields;
+    private validateProvenance;
+    private matchesDescriptor;
+    private matchesCompiledDependencies;
+    private guideTab;
+    private apiTab;
+    private demoAssets;
+    private header;
+    /** Processes one document (`./html-pipeline`) and reports what failed. */
+    private process;
+    /**
+     * Dispatches a render task to the back (or runs it here), then tells the caller of
+     * `compileStaged` that the front is done: everything after the pipeline is pure.
+     */
+    private render;
+    /** A document's diagnostics, in the order the pipeline met them, and its HTML when it succeeded. */
+    private processed;
+    private ir;
+    /**
+     * `consulted`, when given, receives every keyword key the link pass looked up. The linked
+     * HTML is a function of the IR HTML and the bindings of exactly those keys: each lookup is
+     * made before any branch on its result.
+     *
+     * `prepared`, when given, is this request's back half dispatched earlier (`prepareLink`).
+     */
+    link(request: {
+        ir: ContentIR;
+        keywords: KeywordExport[];
+        breadcrumbs: string[];
+        pageType: 'guide' | 'api';
+    }, signal: AbortSignal, consulted?: Set<string>, prepared?: PreparedLink): Promise<ServiceResult<LinkedContent>>;
+    /**
+     * Dispatches the back half of a link before its turn. Linking is a pure function of the IR and
+     * the keyword set, so the result `link` makes of it is the one it would make of linking then.
+     */
+    prepareLink(request: Parameters<GeneratorContentCompiler['link']>[0], signal: AbortSignal): PreparedLink;
+    private linkBack;
+    private linkContent;
+    private actions;
+    private anchorKeywords;
+    /** A per-document renderer copied from the legacy Markdown contract without Marked.use globals. */
+    private markdownToHtml;
+    private stopIfAborted;
+    private readPhysicalFile;
+    /** `NGDOC_PARALLEL_RENDER=verify`: a thread result differed; the main thread's is used. */
+    private parallelMismatch;
+    private diag;
+}
+export declare function keywordBindings(keywords: KeywordExport[]): ReadonlyMap<string, KeywordExport>;
+/** The `keywordDigest` of linked content: the bindings of the IR's used keywords. */
+export declare function linkedKeywordDigest(ir: ContentIR, keywords: KeywordExport[]): string;

package/generator/content/format-cache.d.ts

@@ -0,0 +1,108 @@
+import type { Options } from 'prettier';
+import type { CompilationRequest, GeneratorConfiguration } from '../contracts.js';
+/**
+ * The cache of formatted code: API signatures and demo snippets that `formatCode` formats with
+ * Prettier (`helpers/format-code.ts`), the main thread's largest cost after highlighting at a
+ * cold start. Each call resolved the Prettier configuration again and formatted through
+ * `@prettier/sync`'s worker.
+ *
+ * - **Configuration.** One generation resolves the configuration of a directory once. The files
+ *   it reads (`.prettierrc*`, `prettier.config.*`, `.editorconfig`, `package.json` in the workspace
+ *   root and every directory above it) are already program inputs of every page that formats
+ *   (`trackFormatterConfiguration`), so an edit of one runs a new generation, which resolves
+ *   again.
+ * - **Formatted code.** Formatting is a pure function of the code, the parser, the resolved
+ *   configuration and the Prettier release, so its result is cached under
+ *   `digestOf({ context, parser, config, code })`: the context is this cache's format and the
+ *   resolved versions of `prettier` and `@prettier/sync`, and `config` the resolved configuration
+ *   with the versions of the plugins it names. A configuration that cannot be identified exactly
+ *   (a value JSON cannot hold, a plugin given as a path or that does not resolve to a package) is
+ *   never cached: such code is formatted every time. Code Prettier rejects with a syntax error
+ *   (signatures such as a bare `constructor(…): T;` always are) is cached as such and throws
+ *   again, so `formatCode` returns it unformatted as before; any other error stores nothing.
+ * - **Storage.** One map per runtime, kept across generations by a long-lived runtime and
+ *   cleared when it outgrows {@link FORMAT_CACHE_LIMIT}. Development generations with the artifact
+ *   cache read `<hash(projectId)>.format.json` beside it once per runtime and context, and write it
+ *   after the cache (best effort, atomic, skipped when unchanged), like the highlight cache.
+ *   Production, `cache: false` and the reference path never read or write the pack.
+ *
+ * No dependency or watch input is added: the result depends only on the key, and the
+ * configuration's own files are recorded where the program is built.
+ *
+ * `NGDOC_FORMAT_CACHE=0` (`CompilationOptions.formatCache: false`) formats every call as before;
+ * `verify` resolves the configuration and formats every hit again, uses the fresh result and
+ * reports `CONTENT_FORMAT_CACHE_MISMATCH` when one differs. The semantic service formats through
+ * the session the compiler installs for the generation (`semantic/formatting.ts`).
+ */
+/** The warning of a `verify` hit (or configuration) that differs from the cached one. */
+export declare const FORMAT_CACHE_MISMATCH = "CONTENT_FORMAT_CACHE_MISMATCH";
+/**
+ * Above this size (keys and values, in UTF-16 code units) the pack and the map keep only the
+ * entries of the current generation.
+ */
+export declare const FORMAT_CACHE_LIMIT: number;
+/**
+ * The cache's switch: `off`, `on` or `verify`.
+ * @param options
+ * @param options.formatCache
+ */
+export declare function formatCacheSwitch(options: {
+    formatCache?: boolean | 'verify';
+}): 'off' | 'on' | 'verify';
+/**
+ * The cache of one generation, or undefined when code is formatted without it: with the switch
+ * off, and on the reference path (`incrementalReuse: false`), which recomputes everything. Only
+ * a development generation with the artifact cache on keeps a pack.
+ * @param options
+ * @param options.projectId
+ * @param options.incrementalReuse
+ * @param options.formatCache
+ * @param request
+ * @param configuration
+ */
+export declare function createFormatSession(options: {
+    projectId: string;
+    incrementalReuse?: boolean;
+    formatCache?: boolean | 'verify';
+}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot'>): FormatSession | undefined;
+/**
+ * One generation's use of the cache: its resolved configurations, the keys it used, its pack. It
+ * is a `FormatCodeCache` (`helpers/format-cache.ts`), structurally: the published declarations
+ * reach this class, and they cannot import from outside the generator.
+ */
+export declare class FormatSession {
+    readonly verify: boolean;
+    readonly pack: string | undefined;
+    readonly context: string;
+    /** The keys this generation hit or formatted. */
+    private readonly used;
+    /** The resolved configuration per directory (`''` for the process's working directory). */
+    private readonly configs;
+    /** Each resolved configuration's identity in the keys; undefined: not cacheable. */
+    private readonly identities;
+    private loaded;
+    /** An entry was replaced (a `verify` repair): the pack must be written. */
+    private replaced;
+    private mismatchCount;
+    constructor(verify: boolean, pack: string | undefined);
+    /** How many `verify` hits and configurations differed from the cached ones. */
+    get mismatches(): number;
+    config(configDirectory: string | undefined, resolve: () => Options | null): Options | null;
+    format(input: {
+        code: string;
+        parser: string;
+        config: Options | null;
+    }, format: () => string): string;
+    /**
+     * Writes the pack after the artifact cache: the entries this generation hit or formatted, plus
+     * those the pack held before unless the generation rendered every content (`complete`), or the
+     * result would exceed {@link FORMAT_CACHE_LIMIT}. Best effort.
+     * @param complete
+     */
+    save(complete: boolean): Promise<void>;
+    private remember;
+    /** Reads the pack once per runtime and context; an unusable pack is not read. */
+    private load;
+}
+/** Forgets every entry and pack of this runtime (tests). */
+export declare function resetFormatCache(): void;

package/generator/content/highlight-cache.d.ts

@@ -0,0 +1,115 @@
+import type { CompilationRequest, GeneratorConfiguration, ShikiLanguage } from '../contracts.js';
+/** The warning of a `verify` hit whose highlighting differs from the cached one. */
+export declare const HIGHLIGHT_CACHE_MISMATCH = "CONTENT_HIGHLIGHT_CACHE_MISMATCH";
+/**
+ * Above this size (keys and values, in UTF-16 code units) the pack and the map keep only the
+ * entries of the current generation.
+ */
+export declare const HIGHLIGHT_CACHE_LIMIT: number;
+/** The `@ng-doc/utils` block a key is computed from (`NgDocHighlightBlock`). */
+export interface HighlightBlock {
+    readonly options: Readonly<Record<string, string | number | boolean>>;
+    readonly themes: {
+        readonly light: string;
+        readonly dark: string;
+    };
+    readonly languages?: string;
+    readonly lang: string;
+    readonly meta: string;
+    readonly code: string;
+}
+/** The cache one `processHtml` call uses (`NgDocHighlightCache`), with the mismatches it saw. */
+export interface HighlightCall {
+    key(block: HighlightBlock): string;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    loads(themes: HighlightBlock['themes']): boolean;
+    readonly verify: boolean;
+    mismatch(key: string): void;
+    /** The keys of the `verify` hits that differed, in the order the call met them. */
+    readonly mismatches: readonly string[];
+}
+/** The writes into this runtime's entries since they were last cleared, and the clear count. */
+export declare function highlightJournal(): {
+    epoch: number;
+    entries: ReadonlyArray<[string, string]>;
+};
+/** The cache's switch: `off`, `on` or `verify`. */
+export declare function highlightCacheSwitch(options: {
+    highlightCache?: boolean | 'verify';
+}): 'off' | 'on' | 'verify';
+/**
+ * Which Shiki grammars highlighting loads: only those code blocks reach (`used`, the default), or
+ * every bundled grammar (`all`: `usedGrammars: false` or `NGDOC_USED_GRAMMARS=0`). The HTML is the
+ * same, so neither the cache keys nor any digest depend on it.
+ */
+export declare function grammarsSwitch(options: {
+    usedGrammars?: boolean;
+}): 'used' | 'all';
+/**
+ * The cache of one generation, or undefined when blocks are highlighted without it: with the
+ * switch off, and on the reference path (`incrementalReuse: false`), which recomputes everything.
+ * Only a development generation with the artifact cache on keeps a pack.
+ */
+export declare function createHighlightSession(options: {
+    projectId: string;
+    incrementalReuse?: boolean;
+    highlightCache?: boolean | 'verify';
+}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot' | 'themes' | 'shikiLangs'>): HighlightSession | undefined;
+/** One generation's use of the cache: what it hit or highlighted, and its pack. */
+export declare class HighlightSession {
+    readonly themes: {
+        readonly light: string;
+        readonly dark: string;
+    };
+    readonly verify: boolean;
+    readonly pack: string | undefined;
+    /** The keys this generation hit or highlighted. */
+    private readonly used;
+    readonly context: string;
+    private loaded;
+    /** An entry was replaced (a corrupt one, or a `verify` repair): the pack must be written. */
+    private replaced;
+    constructor(themes: {
+        readonly light: string;
+        readonly dark: string;
+    }, verify: boolean, pack: string | undefined, langs?: readonly ShikiLanguage[]);
+    /** The cache of one `processHtml` call. */
+    call(): HighlightCall;
+    /**
+     * What a render thread needs to use this cache: the context its keys are made in, whether hits
+     * are checked again, and whether the themes are known to load. Reads the pack first, so the
+     * journal holds its entries.
+     */
+    prepare(): {
+        context: string;
+        verify: boolean;
+        proven: boolean;
+    };
+    /** The entry this runtime holds for `key`, without counting it as used. */
+    peek(key: string): string | undefined;
+    /**
+     * Takes in what one document's highlighting recorded out of plan order (a render thread, or the
+     * main thread rendering ahead), as if this thread had processed it now, in plan order: a fresh
+     * value equal to the known one is a hit (another task highlighted the block first), any other
+     * replaces it; and a `verify` difference counts only while the known entry is still not the
+     * fresh value (an earlier document in plan order repaired it, as a sequential render would).
+     * Returns the differences this document reports.
+     */
+    merge(record: {
+        used: readonly string[];
+        fresh: ReadonlyArray<readonly [string, string]>;
+        mismatched: readonly string[];
+    }): number;
+    /** Reads the pack once per runtime and context; an unusable pack is not read. */
+    private load;
+    /**
+     * Writes the pack after the artifact cache: the entries this generation hit or highlighted, plus
+     * those the pack held before unless the generation rendered every content (`complete`), or the
+     * result would exceed {@link HIGHLIGHT_CACHE_LIMIT}. Best effort: a pack that is not written
+     * only makes a later generation highlight again.
+     */
+    save(complete: boolean): Promise<void>;
+}
+/** Forgets every entry, pack and proven context of this runtime (tests). */
+export declare function resetHighlightCache(): void;