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

package/generator/contracts.js

@@ -0,0 +1,15 @@
+// libs/builder/generator/contracts.ts
+var GENERATOR_SCHEMA_VERSION = 4;
+var OUTPUT_SCHEMA_VERSION = 1;
+function nonPhysicalIdentity(dependency) {
+  return dependency.kind === "semantic-closure" ? `semantic-closure:${dependency.scopeId}:${dependency.key}` : `evaluated:${dependency.entryId}`;
+}
+function isDeclarationDescriptor(entry) {
+  return entry.descriptorKind === "declaration" || "apiEntryId" in entry;
+}
+export {
+  GENERATOR_SCHEMA_VERSION,
+  OUTPUT_SCHEMA_VERSION,
+  isDeclarationDescriptor,
+  nonPhysicalIdentity
+};

package/generator/discovery/index.d.ts

@@ -0,0 +1,77 @@
+import { DiscoveryRequest, DiscoveryService, DiscoverySnapshot, EntryDescriptor, GeneratorConfiguration, JsonValue, ServiceResult, TemplateActions, TemplateEvaluationService, TemplateRequest } from '../contracts.js';
+export interface DiscoveryOptions {
+    inlineStyleLanguage?: GeneratorConfiguration['inlineStyleLanguage'];
+    defaultAnchorHeadings?: GeneratorConfiguration['anchorHeadings'];
+    defaultThemes?: GeneratorConfiguration['themes'];
+    moduleTimeoutMs?: number;
+    /**
+     * The time budget of the user code of one markdown template render (default 2 000 ms): the
+     * template and the functions of the page it calls. The time spent in the engine's template
+     * actions (`NgDocActions`, `NgDocApi`, `JSDoc`) is not counted. It is checked at every action
+     * call and when the render ends; a render with no action calls stops at
+     * `templateWallTimeoutMs` at the latest (see `TemplateActionMeter`).
+     */
+    templateTimeoutMs?: number;
+    /**
+     * The wall-clock cap of one markdown template render, its template actions included (default
+     * 30 000 ms, never below `templateTimeoutMs`). V8 terminates the render when it is reached: this
+     * is the bound for user code that never calls an action, or that swallows the failure of one.
+     */
+    templateWallTimeoutMs?: number;
+    /** The most template action calls one markdown template render may make (default 10 000). */
+    templateActionLimit?: number;
+    loaderTimeoutMs?: number;
+    /**
+     * Build tags of this build or dev server, matched against `onlyForTags` of pages and categories.
+     * An entry that declares `onlyForTags` is kept only when it shares at least one tag with this
+     * list; otherwise it and everything under it (child categories, pages, API pages) is left out of
+     * the discovery snapshot, so it has no route, navigation item, search record, keyword or output.
+     * Entries without `onlyForTags` (or with `null` or `''`) are always kept; `[]` is never kept.
+     * Absent or empty means no tags.
+     *
+     * The tags name the build configuration, as the legacy engine's `onlyForTags` check did, so
+     * that the usual `development`/`production` configurations work without extra options. The
+     * hosts default them accordingly: the Vite plugin (and the Vite builders) to the Vite mode, and
+     * the CLI to `development` for `dev`/`watch` and `production` for `generate`.
+     */
+    tags?: readonly string[];
+}
+/** Narrow JSON-only bridge used by the semantic composition for playground controls. */
+export interface GuideValueReader {
+    readGuideValues(entryId: string): ServiceResult<JsonValue>;
+}
+/** Discovery and template evaluation share one replaceable, process-local live scope. */
+export declare class DiscoveryServiceImpl implements DiscoveryService, TemplateEvaluationService, GuideValueReader {
+    private readonly options;
+    /** Normalized build tags, or the reason the configured value is invalid. */
+    private readonly tags;
+    private liveEntries;
+    private liveDependencies;
+    /** The `evaluated` dependency of every described entry of the current snapshot. */
+    private liveEvaluated;
+    private executableScope?;
+    private activeDiscovery?;
+    private generation?;
+    constructor(options?: DiscoveryOptions);
+    discover(request: DiscoveryRequest, signal: AbortSignal): Promise<ServiceResult<DiscoverySnapshot>>;
+    render(request: TemplateRequest, actions: TemplateActions): ServiceResult<string>;
+    readGuideValues(entryId: string): ServiceResult<JsonValue>;
+    dispose(): Promise<void>;
+    private resetRuntime;
+}
+/**
+ * Explicit composition point for the compiler without a dependency on a builder barrel.
+ * @param options
+ */
+export declare function createDiscoveryServices(options?: DiscoveryOptions): {
+    discovery: DiscoveryService;
+    templates: TemplateEvaluationService;
+    values: GuideValueReader;
+    runtime: DiscoveryServiceImpl;
+};
+/**
+ * The `evaluated` digest of every entry of a discovery snapshot: the refresh source of the
+ * `evaluated` dependencies a generation recorded against it.
+ * @param entries
+ */
+export declare function evaluatedDigests(entries: readonly EntryDescriptor[]): Map<string, string>;

package/generator/graph/index.d.ts

@@ -0,0 +1,211 @@
+import type { Dependency, Diagnostic, FileChange, KeywordExport, PageArtifact, RebuildReason, SemanticClosureDependency } from '../contracts.js';
+import { CONFLICTING_CONTENT_DIGEST } from '../kernel/observations.js';
+export { CONFLICTING_CONTENT_DIGEST };
+export interface DependencyIndex {
+    affected(changes: FileChange[]): RebuildReason[];
+    affectedKeywords(changedKeys: Iterable<string>): RebuildReason[];
+}
+export interface DependencyIndexOptions {
+    /**
+     * Reports reasons only for these owner IDs. The semantic closure of every artifact is still
+     * validated, and each answer equals the unrestricted index's answer filtered to these owners;
+     * physical edges are indexed only for the selected owners.
+     */
+    owners?: Iterable<string>;
+}
+export interface RefreshedDependencies {
+    dependencies: Dependency[];
+    digest: string;
+    diagnostics: Diagnostic[];
+}
+export interface DependencyRefresher {
+    refresh(dependencies: Dependency[], keywords: KeywordExport[]): Promise<RefreshedDependencies>;
+}
+export interface DependencyRefresherOptions {
+    /** Reports a real filesystem observation. Intended for performance instrumentation. */
+    onObserve?: (kind: Extract<Dependency['kind'], 'content' | 'existence' | 'glob'>, identity: string) => void;
+    /**
+     * The refresh source of `evaluated` dependencies: each entry's digest in the generation's fresh
+     * discovery snapshot (`evaluatedDigests`). An entry it does not name refreshes as changed.
+     * Without it, every `evaluated` dependency refreshes as changed.
+     */
+    evaluated?: ReadonlyMap<string, string>;
+    /**
+     * The refresh source of `semantic-closure` dependencies: the digest recomputed over the current
+     * program, or undefined when it cannot be, which refreshes as changed. Without it, every
+     * `semantic-closure` dependency refreshes as changed.
+     */
+    semanticClosure?: (dependency: SemanticClosureDependency) => string | undefined;
+    /**
+     * The refresh source of `semantic-reference` dependencies where a unit's own semantic closures
+     * stand in for the global reference, so that no descriptor carries it: the current digest of the
+     * referenced scope. Without it, a reference refreshes as itself (its owner's descriptor carries
+     * the current reference).
+     */
+    semanticReference?: (dependency: SemanticReference) => string | undefined;
+}
+type SemanticReference = Extract<Dependency, {
+    kind: 'semantic-reference';
+}>;
+/** Validates the compact semantic definition/reference closure of a complete candidate. */
+export declare function validateSemanticScopes(artifacts: PageArtifact[]): Diagnostic[];
+/**
+ * Creates an immutable reverse index for one complete artifact candidate.
+ *
+ * With `options.owners`, only those owners' physical edges are indexed (and semantic scopes
+ * without a selected consumer are skipped); every answer equals the unrestricted answer
+ * filtered to the selected owners.
+ */
+export declare function createDependencyIndex(artifacts: PageArtifact[], options?: DependencyIndexOptions): DependencyIndex;
+/**
+ * The refreshed digest of a non-physical dependency while nothing can recompute it. It is not a
+ * sha256 hex digest, so it never equals a recorded one.
+ */
+export declare const UNREFRESHED_DIGEST = "unrefreshed";
+/**
+ * Creates one dependency refresher for a compile generation.
+ *
+ * Its physical observations are promises so concurrent and subsequent units see
+ * one consistent filesystem snapshot. Semantic digests and keyword bindings stay
+ * call-local because their producers can change within the same generation.
+ */
+export declare function createDependencyRefresher(options?: DependencyRefresherOptions): DependencyRefresher;
+/** Refreshes against a new filesystem observation set. */
+export declare function refreshDependencies(dependencies: Dependency[], keywords: KeywordExport[]): Promise<RefreshedDependencies>;
+/**
+ * A file identity as `stat` (following links) reports it. Any rewrite, rename, retarget or chmod
+ * changes `ino`, `size`, `mtimeNs` or `ctimeNs`.
+ */
+export interface ObservationStamp {
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+}
+export interface ObservationSweep {
+    /** The first observation that no longer holds, or undefined when every observation holds. */
+    changed?: {
+        path: string;
+        kind: 'content' | 'existence';
+    };
+    /** Content observations checked by stat alone. */
+    stamped: number;
+    /** Content observations whose bytes were read again (no stamp, a racy stamp or a stat change). */
+    rehashed: number;
+    /** Existence observations probed. */
+    probed: number;
+}
+/** The stat identity of a regular file, or undefined when it is not one (or is gone). */
+export declare function stampOf(file: string): ObservationStamp | undefined;
+export declare function sameStamp(left: ObservationStamp, right: ObservationStamp): boolean;
+/** True when the stamp proves the file was last written well before `sinceNs` (exported for tests). */
+export declare function stampSettledBefore(stamp: ObservationStamp, sinceNs: bigint): boolean;
+/**
+ * Stat-validated physical observations.
+ *
+ * - `record` runs right after an observation that began at `observedAtNs`. A content observation
+ *   whose file was written at or after that time (within a timestamp-granularity margin), whose
+ *   file is gone, or whose digest is {@link CONFLICTING_CONTENT_DIGEST} is *unverifiable*: the
+ *   observer may have used other bytes than the recorded digest describes (an A→B→A write during
+ *   the observation), so every later sweep reports it as changed. Every other one is stamped.
+ * - `sweep` re-verifies: a content observation whose file keeps its stamp holds by `stat` alone;
+ *   otherwise its bytes are read again and compared with the recorded digest by the caller's
+ *   digest function (the one that produced the observation), and the new stamp is trusted only
+ *   if the file was settled before the sweep began. Existence observations are always probed.
+ *   Glob observations are not swept (see {@link changedObservation}).
+ */
+export declare class ObservationStamps {
+    private readonly digestOf;
+    private readonly stamps;
+    private readonly unverifiable;
+    constructor(digestOf: (file: string) => string);
+    record(dependencies: Iterable<Dependency>, observedAtNs: bigint): void;
+    /** Re-verifies content and existence observations; stops at the first one that changed. */
+    sweep(dependencies: Iterable<Dependency>): ObservationSweep;
+    /** Trusted stamps and unverifiable paths (instrumentation and tests). */
+    get counts(): {
+        stamped: number;
+        unverifiable: number;
+    };
+}
+/** One observed directory listing (see {@link DirectoryListings}). */
+/** A directory's entry names as recorded (`null`: it did not exist), as JSON. */
+export interface DirectoryFact {
+    path: string;
+    entries: string[] | null;
+}
+/**
+ * Whether the directory still lists exactly the recorded entries (read, never stat alone).
+ */
+export declare function directoryListed(fact: DirectoryFact): boolean;
+export interface DirectorySweep {
+    changed?: string;
+    /** Listings verified by the directory's stat alone. */
+    stamped: number;
+    /** Listings read again (no trusted stamp, or the directory's stat changed). */
+    relisted: number;
+}
+/**
+ * Directory facts a program depended on without reading any file in them: the packages under a type
+ * root that automatic type directives enumerate, and the directories that hold (or lead to) the
+ * members of an observed glob, where a create that no watcher reported would otherwise stay unseen.
+ *
+ * A listing is re-verified by the directory's stat while it keeps a stamp recorded when the
+ * directory had settled before the observation began; otherwise the directory is read again and
+ * its selected entries are compared with the recorded ones (so an atomic save in the directory,
+ * which only renames a temporary file, costs one re-read and keeps the program). A strict listing
+ * written during the observation is unverifiable, like a content observation.
+ */
+export declare class DirectoryListings {
+    private readonly listings;
+    /**
+     * Records a directory's current listing (every entry). `strict`: a directory written during the
+     * observation never verifies (the observer may have listed other entries).
+     */
+    record(directory: string, observedAtNs: bigint, strict?: boolean): void;
+    /**
+     * Records, for an observed glob, its root and every directory on the way from the root to a
+     * member: the member files the glob matched in that directory plus its subdirectories. A
+     * directory whose matching files differ from the glob's members already (the tree changed while
+     * it was observed) is unverifiable.
+     */
+    recordGlob(dependency: Extract<Dependency, {
+        kind: 'glob';
+    }>, observedAtNs: bigint, ignore?: (path: string) => boolean): void;
+    /**
+     * A new set with this one's whole-directory listings ({@link record}) and none of its glob
+     * listings: a program whose root membership is observed again records its globs anew. The
+     * listings are shared, so a sweep of either set re-stamps them for both.
+     */
+    withoutGlobs(): DirectoryListings;
+    /**
+     * The whole-directory listings ({@link record}) as JSON facts, sorted by path, for a check in
+     * another process ({@link directoryListed}); the glob listings are left out, since such a check
+     * observes each glob again in full. Undefined when any listing cannot vouch for its directory
+     * (the tree changed while it was observed).
+     */
+    directories(): DirectoryFact[] | undefined;
+    sweep(): DirectorySweep;
+    get size(): number;
+    private stamp;
+}
+/** Wall clock in nanoseconds, the time base of {@link ObservationStamps.record}. */
+export declare function observationClockNs(): bigint;
+/**
+ * Returns why a watcher change set may invalidate these observations, or undefined when it
+ * provably cannot, judged by paths alone:
+ * - a changed path (or its real path) is an observed content or existence path;
+ * - a change alters the membership of an observed glob (a matching file appeared or a member
+ *   disappeared);
+ * - a delete of a directory that held glob members;
+ * - a create of a directory under a glob root (its files may not have been reported).
+ * A create of a path that no longer exists (a temporary file of an atomic save) or of a
+ * non-matching file, and a delete of a path that held no member, cannot change membership.
+ *
+ * Paths are compared under every alias (as reported, and resolved through symlinks, for example
+ * `/var` and `/private/var`), for globs on both sides. Content and existence observations are
+ * re-verified by {@link ObservationStamps} and directory listings by {@link DirectoryListings}
+ * regardless; this check makes an event-reported change rebuild at once.
+ */
+export declare function changedObservation(dependencies: Dependency[], changes: FileChange[]): string | undefined;

package/generator/graph/unit-index.d.ts

@@ -0,0 +1,216 @@
+import type { Dependency, EntryDescriptor, FileChange, KeywordExport, PageArtifact } from '../contracts.js';
+/**
+ * The reverse index of one committed build, for the targeted rebuild's change classifier and
+ * affected closure (`compiler/classify.ts`). Built from the candidate snapshot a generation
+ * returned, plus the facts of the same generation the snapshot does not carry (the discovery
+ * snapshot and its dependencies, the output templates, the keyword set). It does not depend on the
+ * persistent reuse memo, which only exists with `cache: true`: every edge comes from artifacts,
+ * descriptors, IR, discovery and keyword exports/uses, so it is complete with the cache off.
+ *
+ * Edges:
+ * - canonical path → the owners (units) that recorded it, at descriptor level (a descriptor's or
+ *   an IR's own dependency, with those content IDs), unit level (only the unit's describe/entry
+ *   inputs) or observed level (a guide's markdown file, observed by discovery);
+ * - canonical path → the roles of an input that is not a unit's content (a set: a page module or
+ *   a file its module imports is usually a program input as well): a program input, the
+ *   configuration and every other evaluated discovery input, a description (entry) module, an
+ *   input of an entry's evaluated closure, the header template, a structural output template;
+ * - discovery, content-level and program globs; every ancestor directory of a recorded path;
+ * - keyword key → consumer owners (`usedKeywords`, `keyword` dependencies and the root key of each
+ *   `key.anchor` / `key#anchor` use, `libs/utils/html/plugins/keywords.plugin.ts`);
+ * - owner → exported keys; key → binding digest of the combined keyword set;
+ * - entry → its discovery descriptor with markdown digests masked, and those digests, for the
+ *   fresh-discovery equality check.
+ *
+ * API scope → owner edges are not built: a program change reaches the units that read the file
+ * (the program files a scoped unit keeps as its own dependencies), and the targeted path refreshes
+ * every replayed unit's semantic closures against the current program (`compiler/targeted.ts`).
+ *
+ * Paths are canonical (`canonicalAliases`): absolute, forward slashes, as recorded and resolved
+ * through symlinks of their directory (one `realpath` per directory). A lookup matches any alias.
+ */
+export type PathLevel = 'descriptor' | 'unit' | 'observed';
+export interface PathHit {
+    owner: string;
+    level: PathLevel;
+    /** Descriptor or IR IDs, for `descriptor` hits. */
+    ids: string[];
+}
+export type InputRole = 'program' | 'configuration' | 'entry-module' | 'entry-input' | 'header-template' | 'output-template';
+export interface IndexedOwner {
+    id: string;
+    entryId: string;
+    entryKind: EntryDescriptor['kind'] | 'unknown';
+    declarationId?: string;
+    descriptors: string[];
+    exports: string[];
+}
+export interface UnitIndexInput {
+    /** The candidate snapshot's artifacts (the aggregate artifact holds the program inputs). */
+    artifacts: PageArtifact[];
+    /** The generation's discovery snapshot. */
+    entries: EntryDescriptor[];
+    configurationDigest: string;
+    headerTemplate?: string;
+    /** The discovery service's own dependencies (evaluated inputs, markdown, description globs). */
+    discovery: Dependency[];
+    /** Structural output templates (`templateDependencies`). */
+    templates: Dependency[];
+    /** The combined keyword set every link read. */
+    keywords: KeywordExport[];
+}
+type Glob = Extract<Dependency, {
+    kind: 'glob';
+}>;
+/** Absolute, forward slashes; a path already in that form (no `.`, `..` or empty segment) is kept. */
+export declare function normalizePath(file: string): string;
+/** The key a keyword use is resolved under before its anchor (`Key.anchor`, `Key#anchor`). */
+export declare function rootKeyword(used: string): string;
+/** Digest of each key's binding in a combined keyword set (every export of a key, in order). */
+export declare function keywordBindingDigests(keywords: KeywordExport[]): Map<string, string>;
+/**
+ * @internal The parent directory of an engine path; a root (`/`, `C:/`) is its own parent. `path.posix`
+ * alone gets drive paths wrong: it gives `.` for `C:/` and the drive designator `C:` for
+ * `C:/docs`, and Windows resolves `C:` to the drive's current directory, not its root.
+ */
+export declare function parentDirectory(file: string): string;
+/** @internal Test ports of {@link createCanonicalAliases}; the real filesystem by default. */
+export interface CanonicalAliasPorts {
+    /** Turns a path into its engine spelling; {@link normalizePath} by default. */
+    readonly normalize?: (file: string) => string;
+    readonly exists?: (file: string) => boolean;
+    /** The native realpath of an existing directory. */
+    readonly realpath?: (directory: string) => string;
+}
+/**
+ * One canonical path helper: the normalized path, and its physical spelling through the realpath of
+ * its nearest existing directory. Directory realpaths are cached per helper.
+ */
+export declare function createCanonicalAliases(ports?: CanonicalAliasPorts): (file: string) => string[];
+/** The retained discovery facts of one entry, for the fresh-discovery equality check. */
+export interface IndexedEntry {
+    kind: EntryDescriptor['kind'];
+    /** Canonical JSON of the descriptor with the content digests of its markdown files masked. */
+    masked: string;
+    /** Markdown path → digest recorded in `entry.dependencies`. */
+    markdown: Map<string, string>;
+    /** The entry's `evaluated` digest, masked in `masked` (compared on its own). */
+    evaluated?: string;
+}
+export declare function indexEntry(entry: EntryDescriptor): IndexedEntry;
+/**
+ * What a generation that reused most of its base's build changed, for {@link UnitIndex.overlay}:
+ * the owners whose artifact revision changed (their edges are rebuilt from `input.artifacts`), the
+ * entries whose discovery descriptor changed (only their markdown digests can, on the targeted
+ * path), and the keys whose binding may have changed (`undefined`: every key is digested again).
+ */
+export interface UnitIndexDelta {
+    replaced: ReadonlySet<string>;
+    entries: ReadonlySet<string>;
+    keys?: Iterable<string>;
+    /**
+     * The generation's discovery inputs or program differ from the base's (an entry's closure, its
+     * markdown list, the program's files): the roles, the observed markdown owners and the discovery
+     * and program globs are built again from `input` instead of being shared with the base.
+     */
+    inputs?: boolean;
+}
+export declare class UnitIndex {
+    readonly owners: Map<string, IndexedOwner>;
+    readonly configurationDigest: string;
+    readonly entries: Map<string, IndexedEntry>;
+    readonly bindings: Map<string, string>;
+    /** Paths recorded by at least one owner or input (canonical aliases). */
+    private readonly paths;
+    /** Roles of each path alias, in the order they were added (see {@link roles}). */
+    private readonly roleSets;
+    private readonly markdownOwners;
+    private readonly ancestors;
+    private readonly consumers;
+    /** Per owner: the path aliases, consumed keys and content-level globs it added (overlay removal). */
+    private readonly ownerPaths;
+    private readonly ownerKeys;
+    private readonly ownerGlobs;
+    /** Discovery globs (no owner). */
+    private readonly discoveryGlobs;
+    readonly structuralGlobs: Glob[];
+    readonly programGlobs: Glob[];
+    readonly aliases: (file: string) => string[];
+    private readonly normalized;
+    /** An overlay shares its base's arrays and sets, so it replaces them instead of changing them. */
+    private readonly copying;
+    private constructor();
+    /**
+     * The edges of the generation's inputs that are no unit's content: the observed markdown owners
+     * (and, `observed`, their observed-level hits) and the roles of discovery inputs and output
+     * templates. A role is added to the path's set; the program roles are added by {@link program}.
+     */
+    private inputs;
+    /** Builds the index of one generation's build (see {@link UnitIndexInput}). */
+    static build(input: UnitIndexInput): UnitIndex;
+    /**
+     * The index of a generation that kept most of `base`'s build: `base`'s edges, with those of the
+     * `delta.replaced` owners rebuilt from `input.artifacts`, the changed entries re-indexed and the
+     * named keys' bindings digested again. It equals {@link build} of the same input when the
+     * generation changed nothing else (the same discovery, program and output templates, which the
+     * targeted path proves before it reuses anything), except that ancestors of paths no owner
+     * records any more are kept: an event there is classified structural, which only costs a full
+     * generation. `base` is not changed.
+     */
+    static overlay(base: UnitIndex, input: UnitIndexInput, delta: UnitIndexDelta): UnitIndex;
+    /** The owners (and levels) that recorded `file`, under any of its aliases. */
+    hits(file: string): PathHit[];
+    /**
+     * The role of a non-content input (`program` included), under any alias: its first discovery or
+     * template role, or `program` when it has no other.
+     */
+    role(file: string): InputRole | undefined;
+    /** Every role of a non-content input, under all of its aliases (empty for none). */
+    roles(file: string): ReadonlySet<InputRole>;
+    /** Owners of `file` when it is a guide's markdown file observed by discovery. */
+    markdown(file: string): string[] | undefined;
+    /** Whether `file` is a strict ancestor directory of a recorded path. */
+    isAncestor(file: string): boolean;
+    /** Why `change` alters the membership of a discovery or content-level glob, if it does. */
+    structuralGlobChange(change: FileChange): string | undefined;
+    /** Why `change` alters the membership of a content-level glob (one a unit recorded), if it does. */
+    contentGlobChange(change: FileChange): string | undefined;
+    /** Why `change` alters the membership of a program glob (an API scope), if it does. */
+    programGlobChange(change: FileChange): string | undefined;
+    /** Owners that use any of `keys` (directly, as a `keyword` dependency, or as a root key). */
+    consumersOf(keys: Iterable<string>): Set<string>;
+    /** Counts (evidence and tests). */
+    size(): {
+        owners: number;
+        paths: number;
+        roles: number;
+        keys: number;
+        ancestors: number;
+    };
+    /**
+     * One unit's edges: its descriptor- and IR-level paths (with those content IDs), its unit-level
+     * inputs, its content-level globs, the keys it consumes, and (overlay only, `entry` given) its
+     * guide's observed markdown.
+     */
+    private addOwner;
+    /** Removes every edge `id` added (overlay only; the structures were copied first). */
+    private removeOwner;
+    /**
+     * Program inputs are indexed under every alias, like content paths: a file that is both a program
+     * input and some unit's content must be semantic whichever spelling a change reports (a symlinked
+     * workspace, `/var` and `/private/var`), or it would be taken for content-only. Their ancestors
+     * are not indexed (thousands of files, declaration files included; a change that misses them is
+     * `unknown`, which rebuilds in full as well). The retained program's own `stale()` stays the
+     * authority on program changes.
+     */
+    private program;
+    /** {@link normalizePath}, memoised for this build (dependency paths repeat across units). */
+    private canonical;
+    private addPath;
+    /** Adds a discovery or template role to the path's set (its ancestors are recorded paths). */
+    private addRole;
+    private roleOf;
+    private addAncestors;
+    private consume;
+}
+export {};

package/generator/kernel/canonical.d.ts

@@ -0,0 +1,57 @@
+import type { Dependency } from '../contracts.js';
+/**
+ * The one digest domain of the engine. Every persisted or compared digest (fingerprints, artifact
+ * revisions, dependency digests, closure and evaluated digests, memo and cache keys) is a single
+ * `sha256` over a canonical form built here, so two phases that digest the same value always agree,
+ * on every machine and locale.
+ *
+ * - {@link canonicalJson} orders object keys by UTF-16 code units. `localeCompare` depends on ICU and
+ *   the process locale (and ignores control characters such as `\0`), so it must never order what a
+ *   digest or a key covers; use {@link compareCodeUnits}.
+ * - {@link bytesDigest} is the content digest of a file: the digest of its bytes. Every reader of a
+ *   file decodes those bytes (UTF-8; TypeScript and esbuild also drop a leading byte order mark),
+ *   so whatever it compiled is a function of them. A reader that only holds the decoded text uses
+ *   {@link contentDigest}, which is the same function over the UTF-8 encoding of that text.
+ *
+ * Output identities that generated files contain (content module ids and revisions, keyword
+ * digests, output ids and file digests) keep their own fixed formulas: changing them would change
+ * generated files. They still hash through {@link sha256Hex}.
+ */
+/** Orders two strings by UTF-16 code units, independent of locale and ICU. */
+export declare function compareCodeUnits(left: string, right: string): number;
+/** The hex sha256 of a string (its UTF-8 encoding) or of bytes. */
+export declare function sha256Hex(value: string | NodeJS.ArrayBufferView): string;
+/**
+ * Canonical JSON: the text `JSON.stringify` would produce, with every object's keys in code-unit
+ * order. As in JSON, `toJSON` is honoured, object members whose value is `undefined`, a function or
+ * a symbol are omitted, such array items (and non-finite numbers) become `null`, and a `bigint`
+ * throws. So `canonicalJson(value) === canonicalJson(JSON.parse(JSON.stringify(value)))`. A cycle
+ * throws a `TypeError`.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Strict canonical JSON for exact identities: `undefined` stays distinct from an absent member,
+ * and anything JSON cannot represent exactly (functions, symbols, non-finite numbers, `-0`, holes,
+ * class instances, cycles) has no identity, so the result is `undefined`.
+ */
+export declare function canonicalJsonStrict(value: unknown): string | undefined;
+/** The digest of a value: `sha256` of its {@link canonicalJson}. */
+export declare function digestOf(value: unknown): string;
+/** The content digest of a file's bytes. */
+export declare function bytesDigest(bytes: NodeJS.ArrayBufferView): string;
+/**
+ * The content digest of decoded text: {@link bytesDigest} of its UTF-8 encoding. It equals the
+ * digest of the file the text was read from whenever decoding kept every byte (valid UTF-8 and no
+ * byte order mark dropped); otherwise the two differ, which only ever reports the file as changed.
+ */
+export declare function contentDigest(text: string): string;
+/**
+ * The identity of a dependency: two dependencies with one identity describe the same observation
+ * (a file's content or existence, one glob, one keyword, one semantic scope or closure, one
+ * entry's evaluated value), so a dependency list holds at most one per identity.
+ */
+export declare function dependencyIdentity(dependency: Dependency): string;
+/** A glob's identity: its root and its include and exclude patterns, unambiguously quoted. */
+export declare function globIdentity(glob: Pick<Extract<Dependency, {
+    kind: 'glob';
+}>, 'root' | 'include' | 'exclude'>): string;

package/generator/kernel/flags.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The engine's environment switches, registered and parsed in one place, so a switch means the
+ * same in the host and in the compiler runtime (which sees the host's environment through the
+ * worker).
+ *
+ * Every switch is on by default. `0`, `false`, `off` or `no` (case-insensitive, trimmed) turn it
+ * off; `1`, `true`, `on`, `yes` and an empty value leave it on; switches that accept `verify` also
+ * take `verify`, which keeps the optimization on and checks it against the reference path. Any
+ * other value is unrecognised: it leaves the switch on, and {@link readFlag} returns it so the
+ * reader that reports values (bootstrap) can warn once.
+ */
+/** A switch's parsed value. */
+export type FlagValue = 'on' | 'off' | 'verify';
+export interface FlagDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly default: 'on';
+    /** Whether `verify` is a recognised value. */
+    readonly verify: boolean;
+}
+export declare const PERSISTENT_WORKER_FLAG = "NGDOC_PERSISTENT_WORKER";
+export declare const PERSISTENT_WORKER_PRIME_FLAG = "NGDOC_PERSISTENT_WORKER_PRIME";
+export declare const DELTA_TRANSPORT_FLAG = "NGDOC_DELTA_TRANSPORT";
+export declare const TARGETED_REBUILD_FLAG = "NGDOC_TARGETED_REBUILD";
+export declare const INCREMENTAL_SKIP_FLAG = "NGDOC_INCREMENTAL_SKIP";
+export declare const SEMANTIC_RECORDER_FLAG = "NGDOC_SEMANTIC_RECORDER";
+export declare const SCOPED_SEMANTIC_FLAG = "NGDOC_SCOPED_SEMANTIC";
+export declare const INCREMENTAL_PROGRAM_FLAG = "NGDOC_INCREMENTAL_PROGRAM";
+export declare const SHAPE_CLOSURE_FLAG = "NGDOC_SHAPE_CLOSURE";
+export declare const ANGULAR_SHARED_PASS_FLAG = "NGDOC_ANGULAR_SHARED_PASS";
+export declare const ANGULAR_STRUCTURAL_PASS_FLAG = "NGDOC_ANGULAR_STRUCTURAL_PASS";
+export declare const VITE_BUILD_HANDOFF_FLAG = "NGDOC_VITE_BUILD_HANDOFF";
+export declare const TRACKED_PROGRAM_REUSE_FLAG = "NGDOC_TRACKED_PROGRAM_REUSE";
+export declare const FAST_START_FLAG = "NGDOC_FAST_START";
+export declare const PARALLEL_WRITES_FLAG = "NGDOC_PARALLEL_WRITES";
+export declare const HIGHLIGHT_CACHE_FLAG = "NGDOC_HIGHLIGHT_CACHE";
+export declare const PARALLEL_RENDER_FLAG = "NGDOC_PARALLEL_RENDER";
+/** The registry, in the order the engine applies the switches. */
+export declare const FLAGS: readonly FlagDefinition[];
+/**
+ * The value of the registered switch `name` in `env`. `unrecognised` is the trimmed raw value when
+ * it is not one the switch accepts; the value is then the default.
+ */
+export declare function readFlag(name: string, env?: Readonly<Record<string, string | undefined>>): {
+    value: FlagValue;
+    unrecognised?: string;
+};
+/** Whether the registered switch `name` is turned off in `env`. */
+export declare function flagOff(name: string, env?: Readonly<Record<string, string | undefined>>): boolean;