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

package/generator/compiler/fold.d.ts

@@ -0,0 +1,116 @@
+import type { ArtifactSnapshot, CompilationResult, Dependency, Diagnostic, RebuildReason } from '../contracts.js';
+/**
+ * Per-unit records and the fold.
+ *
+ * Every phase of a compile writes what it emits (diagnostics and dependencies) into records
+ * instead of shared accumulators, and every exit builds its `CompilationResult` with `fold`. The
+ * fold replays the records phase-major, units in plan order, which is exactly the order in which
+ * the full path runs its phases:
+ *
+ * 1. discovery, semantic, setup (cache restore, output templates);
+ * 2. per unit: describe (`enumerateApi` on the entry's first unit, entry-doc, `describeGuide`,
+ *    `describe`), then the unit's dependency list;
+ * 3. plan (descriptor duplicates);
+ * 4. per unit: render/demo steps, then the unit's dependency list;
+ * 5. keywords (duplicates, index completeness);
+ * 6. per unit: link; 7. per unit: assembly;
+ * 8. aggregate, scope validation, and a failure of the whole attempt.
+ *
+ * Dependencies enter one map in that order, last write wins, and two content reads of one path
+ * with different digests are recorded as conflicting.
+ *
+ * A render step records the projection the full path used for it: `fresh` when it rendered,
+ * emitting its diagnostics and raw dependencies; `reuse` when its reuse predicate held, emitting
+ * nothing and adding only the compacted IR dependencies to the unit. The unit's dependency list
+ * after render is derived from its describe list and the steps' projections, so a later slice can
+ * replay a retained unit by choosing its projection. Describe and link are replayed as recorded
+ * (the full path runs them for every unit), and so is assembly.
+ *
+ * Two facts a replay that chooses projections for retained units must not lose:
+ * - a `none` step is not necessarily empty: a descriptor without a current request settles as
+ *   `none` with the error `COMPILATION_CONTENT_DESCRIPTOR_REQUEST` (render.ts), and the fold replays
+ *   every step's `emitted`, whatever its projection;
+ * - an assembly is fresh-equivalent unless the assembly memo supplied it: the unit record says
+ *   which (`UnitRecord.assembly`). A memoised assembly emits no diagnostics (a unit with assembly
+ *   diagnostics is never memoised), so today replaying it as recorded is exact.
+ */
+export interface Contribution {
+    diagnostics: Diagnostic[];
+    dependencies: Dependency[];
+}
+export type GlobalPhase = 'discovery' | 'semantic' | 'setup' | 'plan' | 'keywords' | 'aggregate' | 'validate' | 'failure';
+/** One descriptor, or the demo-assets IR (`<unit>:demos`), of a unit's render phase. */
+export interface RenderStep {
+    id: string;
+    /**
+     * `fresh`: rendered in this generation; `reuse`: the previous IR; `none`: no IR (a descriptor
+     * without a current request). `none` may still carry an error in `emitted`
+     * (`COMPILATION_CONTENT_DESCRIPTOR_REQUEST`), which the fold replays like any other.
+     */
+    projection: 'fresh' | 'reuse' | 'none';
+    /** Emitted into the generation: diagnostics and raw dependencies (empty for `reuse`). */
+    emitted: Contribution;
+    /** Compacted dependencies the step adds to the unit's own dependency list. */
+    unitDependencies: Dependency[];
+}
+export interface UnitRecord {
+    describe: Contribution[];
+    /** The unit's dependency list once describe completed. */
+    described?: Dependency[];
+    render: RenderStep[];
+    /** Whether the unit's render phase completed (its dependency list was then emitted). */
+    rendered: boolean;
+    link: Contribution[];
+    assemble: Contribution[];
+    /**
+     * How the assembly phase obtained the unit's outputs, routes and API list: `memo` when the
+     * assembly memo supplied the previous page (the reuse projection: nothing is emitted), `fresh`
+     * when it was assembled in this generation. Unset until the assembly phase reaches the unit.
+     */
+    assembly?: 'memo' | 'fresh';
+}
+type Tracer = (records: GenerationRecords) => void;
+/**
+ * Tests only: `sink` receives every new `GenerationRecords`, which then also keeps a journal of
+ * its contributions in the order the phases emitted them (see `foldContributions`).
+ */
+export declare function traceRecords(sink: Tracer | undefined): void;
+export declare class GenerationRecords {
+    readonly units: UnitRecord[];
+    readonly reasons: RebuildReason[];
+    /** Tests only (`traceRecords`): every contribution in emission order. */
+    readonly journal?: Contribution[];
+    private readonly globals;
+    private readonly errorStages;
+    constructor();
+    /** Whether any recorded diagnostic is an error. */
+    failed(): boolean;
+    global(phase: GlobalPhase, value: Contribution): void;
+    globalContributions(phase: GlobalPhase): readonly Contribution[];
+    /** Opens the record of the next unit in plan order. */
+    unit(): UnitRecord;
+    /**
+     * Appends the record of a unit the targeted path replays instead of describing it again: what
+     * the full path would record for it, built from the retained build of a successful generation
+     * (so it holds no error). Its phases that still run in this generation add to it as usual.
+     */
+    adopt(record: UnitRecord): void;
+    describe(record: UnitRecord, value: Contribution): void;
+    described(record: UnitRecord, dependencies: Dependency[]): void;
+    /** Opens the render step of a descriptor (or the demo-assets IR) with no IR yet. */
+    renderStep(record: UnitRecord, id: string): RenderStep;
+    /** What the step emitted, and the projection it took. */
+    settle(step: RenderStep, projection: RenderStep['projection'], emitted: Contribution, unitDependencies?: Dependency[]): void;
+    /** `dependencies` is the unit's actual list; the fold derives it from the steps. */
+    rendered(record: UnitRecord, dependencies: Dependency[]): void;
+    link(record: UnitRecord, value: Contribution): void;
+    assemble(record: UnitRecord, value: Contribution, assembly?: 'memo' | 'fresh'): void;
+    reason(...values: RebuildReason[]): void;
+    private note;
+}
+/** Replays the records phase-major (see above) into the generation's result. */
+export declare function fold(records: GenerationRecords, candidate?: ArtifactSnapshot): CompilationResult;
+/** Diagnostics in order, and the generation's dependency map (conflicting digests), sorted. */
+export declare function foldContributions(contributions: readonly Contribution[]): Contribution;
+export declare function mergeReasons(values: RebuildReason[]): RebuildReason[];
+export {};

package/generator/compiler/index.d.ts

@@ -0,0 +1,111 @@
+import type { CompilationResult, CompilationService, DiscoveryRequest } from '../contracts.js';
+import { type DiscoveryOptions } from '../discovery/index.js';
+export { disposeHtmlPool as disposeRenderThreads, keepHtmlPool as keepRenderThreads, } from '../content/html-pool.js';
+export { type DryRunRecord, type DryRunReport, resetTargetedDryRun, TARGETED_MISMATCH, TARGETED_REBUILD_TRACE_ENV, targetedDryRun, } from './dry-run.js';
+export { type IncrementalRetentionReport, INCREMENTAL_PROGRAM_ENV, INCREMENTAL_SKIP_ENV, incrementalRetention, resetIncrementalRetention, } from './retention.js';
+/** JSON factory options can cross the disposable compilation worker boundary. */
+export interface CompilationOptions {
+    projectId: string;
+    workspaceRoot: string;
+    configFile?: string;
+    defaults: DiscoveryRequest['defaults'];
+    discovery?: DiscoveryOptions;
+    /** Explicit template location for bundled hosts; defaults to packaged sibling templates. */
+    templateRoot?: string;
+    /** Host/package supplies its exact version and toolchain provenance. */
+    compilerVersion: string;
+    toolchainDigest: string;
+    /**
+     * Exact incremental reuse (restricted `whyRebuilt` index, link/assembly/revision reuse and
+     * unchanged cache-entry skips) for development generations. Production generations never
+     * use it. Defaults to on; `false` is the reference path that recomputes everything, kept for
+     * differential verification.
+     *
+     * It also governs the retained-program skip: a development generation that is not a one-shot
+     * build (`context.lifetime !== 'generation'`) keeps its TypeScript Project for the next
+     * generation of the same runtime, which skips `synchronize` when nothing the program observed
+     * changed. `false` turns both off; {@link INCREMENTAL_SKIP_ENV} turns off only the skip.
+     */
+    incrementalReuse?: boolean;
+    /**
+     * The targeted rebuild (`compiler/targeted.ts`): a development watch generation whose changes
+     * are content, page or program edits compiles only the units they reach and replays the others
+     * from the retained build of its base; its result is byte-identical to the full generation's.
+     * On by default (`true`); `false` is the full path exactly, with nothing retained for it.
+     * `verify` also compiles every targeted generation in full and compares the two results byte
+     * for byte; on a difference it publishes the full one and reports
+     * `COMPILATION_TARGETED_MISMATCH` (the report of `targetedDryRun()`, the trace and stderr).
+     * It also reports, per generation, the units the full generation changed outside the targeted
+     * closure (misses).
+     * Resolved by bootstrap from `NGDOC_TARGETED_REBUILD` (`bootstrap/index.ts`). Only generations
+     * that retain a program (development, not one-shot, `incrementalReuse` on) can be targeted.
+     */
+    targetedRebuild?: boolean | 'verify';
+    /**
+     * Scoped semantic invalidation (`compiler/semantic-closure.ts`): development generations of a
+     * long-lived runtime record one `semantic-closure` per semantic query instead of the global
+     * `semantic-reference`, so an API edit re-renders only the IRs whose closure changed. On by
+     * default; `false`, like `NGDOC_SCOPED_SEMANTIC=0`, records the global reference. `verify` (or
+     * the environment's `verify`) also renders every IR reused on its closure and reports
+     * `COMPILATION_SCOPED_SEMANTIC_MISMATCH` on a difference.
+     */
+    scopedSemantic?: boolean | 'verify';
+    /**
+     * The incremental program (`semantic/program-retention.ts`): a development generation that
+     * reuses the retained program patches the content edits of its program files into it instead of
+     * synchronizing a new one. On by default; `false`, like `NGDOC_INCREMENTAL_PROGRAM=0`,
+     * synchronizes anew after any program-file edit. `verify` (or the environment's `verify`) also
+     * synchronizes a cold program after every patch and uses it, with a `SEMANTIC_PATCH_MISMATCH`
+     * warning, when the two differ.
+     */
+    incrementalProgram?: boolean | 'verify';
+    /**
+     * The fast start (`compiler/fast-start.ts`): a development start whose recorded inputs all
+     * re-read identically publishes the recorded candidate without compiling, and a start after
+     * edits reuses the cache index's links and assemblies. On by default; `false`, like
+     * `NGDOC_FAST_START=0`, compiles every start. `verify` (or the environment's `verify`) also
+     * compiles a restored start in full, publishes that result and reports
+     * `COMPILATION_FAST_START_MISMATCH` when the candidates differ.
+     */
+    fastStart?: boolean | 'verify';
+    /**
+     * The cache of highlighted code blocks (`content/highlight-cache.ts`): code is highlighted by one
+     * Shiki highlighter per runtime, and a block whose text, language, meta, themes and Shiki release
+     * were highlighted before reuses that result. Development generations with the artifact cache
+     * keep it beside the cache; production, `cache: false` and the reference path
+     * (`incrementalReuse: false`, which highlights every block) keep none. On by default; `false`,
+     * like `NGDOC_HIGHLIGHT_CACHE=0`, highlights every block with the plain plugin. `verify` (or the
+     * environment's `verify`) also highlights every hit again, uses that result and reports
+     * `CONTENT_HIGHLIGHT_CACHE_MISMATCH` when it differs.
+     */
+    highlightCache?: boolean | 'verify';
+    /**
+     * Parallel rendering (`content/html-pool.ts`): a large generation runs the HTML pipeline of its
+     * content (highlighting, anchors, keyword links, search records) on render threads, while the
+     * main thread runs every front (files, templates, semantic queries) in plan order and settles
+     * every result in plan order; the output is the same. Never on the targeted path or the
+     * reference path (`incrementalReuse: false`). On by default; `false`, like
+     * `NGDOC_PARALLEL_RENDER=0`, runs everything in the main thread. `verify` (or the environment's
+     * `verify`) also runs every thread task in the main thread, uses that result and reports
+     * `CONTENT_PARALLEL_MISMATCH` when it differs.
+     */
+    parallelRender?: boolean | 'verify';
+    /**
+     * The number of render threads (`parallelRender`). Defaults to the available parallelism less
+     * two (the main thread and Prettier's), at most 4; `0` uses none.
+     */
+    renderThreads?: number;
+}
+/** A compiler service that can say which of its results came from a targeted generation. */
+export interface TargetedCompilationService extends CompilationService {
+    targetedResult(result: CompilationResult): boolean;
+}
+/**
+ * Each attempt constructs a complete immutable candidate; publication belongs to the session
+ * and the committer.
+ *
+ * A compile runs its phases in order (discovery, semantic, setup, describe, plan, render, keywords,
+ * link, assembly, aggregate, validation): each phase records what it emits per unit or globally,
+ * and every exit folds those records into its result (`./fold`).
+ */
+export declare function createCompilationService(options: CompilationOptions): TargetedCompilationService;