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

package/generator/progress/lines.d.ts

@@ -0,0 +1,42 @@
+import type { CiVendor } from './detect.js';
+import type { GenerationView } from './model.js';
+/** Never more than one heartbeat line per 5 s, whatever the configured cadence. */
+export declare const LINES_MIN_HEARTBEAT_MS = 5000;
+export interface LinesOptions {
+    /** Prints one line (never throws into the renderer's caller; the reporter contains it). */
+    print: (text: string) => void;
+    /** Prints a CI service message verbatim (free text goes through `print`, which neutralizes them). */
+    service?: (text: string) => void;
+    heartbeatMs: number;
+    /** Nx TUI / stream output: short append-only lines. */
+    compact: boolean;
+    /** Azure/TeamCity hidden progress messages, printed after each progress line. */
+    assist?: CiVendor;
+    project?: string;
+}
+/**
+ * LINES renderer for one build generation: a start line, one line per step, and a heartbeat on a
+ * fixed cadence. ASCII only, no escape bytes. About 5–10 lines for a 20–40 s build.
+ */
+export declare class LinesRenderer {
+    private readonly options;
+    private view;
+    private elapsed;
+    private printedSteps;
+    private lastLineAt;
+    /** Lines written for the tracked generation, for volume checks. */
+    lines: number;
+    constructor(options: LinesOptions);
+    get tracking(): boolean;
+    /** Starts a generation: prints the start line. */
+    track(view: GenerationView, elapsed: (now: number) => number, now: number): void;
+    /** A progress event was accepted: prints a line when a new step started. */
+    update(now: number): void;
+    nextWake(): number | undefined;
+    /** Heartbeat. */
+    wake(now: number): void;
+    stop(): void;
+    /** `step`: the line that announces a step shows totals; a heartbeat shows the count so far. */
+    private progressLine;
+    private emit;
+}

package/generator/progress/live.d.ts

@@ -0,0 +1,115 @@
+/** The stream the live line is drawn on (normally `process.stderr`). */
+export interface LiveStream {
+    write(chunk: string): unknown;
+    columns?: number;
+}
+/**
+ * Registers a callback for the end of the process and returns its removal
+ * ({@link processExitHook} by default).
+ */
+export type ExitHook = (callback: () => void) => () => void;
+/** The process-control port of {@link createProcessExitHook}. */
+export interface ExitProcess {
+    once(event: 'exit', listener: () => void): unknown;
+    prependListener(event: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): unknown;
+    removeListener(event: 'exit' | NodeJS.Signals, listener: (...args: never[]) => void): unknown;
+    listenerCount(event: NodeJS.Signals): number;
+    kill(pid: number, signal: NodeJS.Signals): unknown;
+    exit(code: number): unknown;
+    readonly pid: number;
+    readonly platform: string;
+    readonly stdin?: {
+        isTTY?: boolean;
+        isRaw?: boolean;
+        setRawMode?(mode: boolean): unknown;
+    };
+}
+/**
+ * Calls `callback` once, at `exit` or on SIGINT, SIGTERM or SIGHUP, and removes every listener it
+ * added.
+ *
+ * Host signal behaviour is kept in both cases:
+ * - **The host handles the signal** (a listener of its own, added before or after this one): the
+ *   callback runs first, so the line is gone before the host prints its shutdown lines, and the
+ *   host decides what happens next. Node's disposition does not change, since the host's listener
+ *   already replaced the default.
+ * - **Nobody else does**: this listener is what replaced Node's default ending, so it gives it
+ *   back. It restores the terminal mode (stdin raw mode), removes itself and raises the signal
+ *   again, and the process ends by that signal. Limitation: the rest of Node's own stdio reset on a
+ *   fatal signal (terminal attributes changed by native code) is not reproduced. Where a signal
+ *   cannot be raised (Windows, where only SIGINT and SIGTERM can be sent, or a failing `kill`), it
+ *   exits with `128 + signal number`, the shells' code for that signal.
+ *
+ * Not listening while alone would keep the default ending but leave the line on the screen after
+ * Ctrl-C; not listening next to a host's listener would put the host's shutdown lines behind the
+ * line. Neither changes behaviour more than this, so the line is always cleared.
+ */
+export declare function createProcessExitHook(target: ExitProcess): ExitHook;
+export declare const processExitHook: ExitHook;
+/** Live cadence: bounded redraws keep screen readers and Nx cache replays quiet. */
+export declare const LIVE_FIRST_DRAW_MS = 500;
+export declare const LIVE_ACTIVITY_DRAW_MS = 1000;
+/**
+ * Edits draw the in-progress line only past 1 s, so a sub-second edit never flashes one. The
+ * edit's completion line is printed regardless.
+ */
+export declare const LIVE_EDIT_DRAW_MS = 1000;
+/**
+ * Change-driven redraws: at most one per 750 ms (the ceiling is 5 per second). With whole-second
+ * elapsed time and a short bar, an Nx cache replay of a 60 s build stays around 10 KB, even when
+ * every update changes the text.
+ */
+export declare const LIVE_MIN_INTERVAL_MS = 750;
+export declare const LIVE_IDLE_TICK_MS = 1000;
+export declare const CLEAR_LINE = "\r\u001B[2K";
+/** What the live line shows right now. */
+export interface LiveFrame {
+    body: string;
+    elapsedMs: number;
+    /** Drives the bar; absent before the steps are known. */
+    fraction?: number;
+}
+export interface LiveOptions {
+    stream: LiveStream;
+    unicode: boolean;
+    /** Read at every draw: the terminal may be resized while a build runs. */
+    columns: () => number;
+    bar: boolean;
+    exitHook?: ExitHook;
+}
+/** Below this width a live line says too little to be worth redrawing: draw nothing. */
+export declare const LIVE_MIN_COLUMNS = 20;
+/**
+ * LIVE renderer: one line on the stream, redrawn in place. It is drawn first after a delay (quick
+ * work never flashes), then at most every 500 ms when the text changed and on a 1 s idle tick.
+ * It never writes `\n` and is cleared at the end, on dispose and at process exit.
+ */
+export declare class LiveRenderer {
+    private readonly options;
+    private source;
+    private firstDrawAt;
+    private lastDrawAt;
+    private dirty;
+    private shown;
+    private frame;
+    private removeExitHook;
+    /** The process is ending (exit or a signal): nothing is drawn again, even if a host lives on. */
+    private ended;
+    /** Frames written, for volume checks. */
+    frames: number;
+    constructor(options: LiveOptions);
+    get tracking(): boolean;
+    get showing(): boolean;
+    /** Starts showing `source`; the first frame is drawn `delayMs` after `now`. */
+    track(source: (now: number) => LiveFrame, now: number, delayMs?: number): void;
+    /** Something visible changed. */
+    touch(): void;
+    /** The absolute time of the next draw, or `undefined` when nothing is tracked. */
+    nextWake(): number | undefined;
+    /** Draws when a frame is due at `now`. */
+    wake(now: number): void;
+    /** Removes the line (before another line is printed); the next wake redraws it. */
+    clear(): void;
+    /** Stops tracking and clears the line. */
+    stop(): void;
+}

package/generator/progress/model.d.ts

@@ -0,0 +1,85 @@
+import type { ProgressActivityEvent, ProgressEvent, ProgressPass, ProgressPhase, ProgressSettledEvent, ProgressState, ProgressTrigger } from './events.js';
+/** The four user-facing steps; each groups the internal phases that run in it. */
+export interface ProgressStep {
+    label: 'preparing' | 'rendering' | 'linking' | 'writing';
+    phases: readonly ProgressPhase[];
+}
+export declare const PROGRESS_STEPS: readonly ProgressStep[];
+/** Zero-based index of the step a phase belongs to. */
+export declare const stepOf: (phase: ProgressPhase) => number;
+/**
+ * Default share of a cold build per phase (preparing ≈35 %, rendering ≈25 %, linking ≈15 %,
+ * writing ≈25 % on a large site). They only drive the percentage, never results.
+ */
+export declare const PHASE_WEIGHTS: Readonly<Record<ProgressPhase, number>>;
+/** What the model knows about one generation. */
+export interface GenerationView {
+    generation: number;
+    trigger: ProgressTrigger;
+    mode: 'development' | 'production';
+    changes: number;
+    /** Session clock of the newest accepted event. */
+    elapsedMs: number;
+    lastSeq: number;
+    pass?: ProgressPass;
+    reason?: string;
+    /** The phase sequence restarted once for a FULL pass. */
+    restarted: boolean;
+    phase?: ProgressPhase;
+    phaseState?: ProgressState;
+    completed?: number;
+    /** Totals fixed at each phase's start, in the current pass. */
+    totals: Partial<Record<ProgressPhase, number>>;
+    reused?: number;
+    /** Compiler phases are reported, so the four steps and a percentage can be shown. */
+    stepped: boolean;
+    /** Weighted overall fraction, clamped so the percentage never goes backwards. */
+    fraction: number;
+    settled?: ProgressSettledEvent;
+}
+export type ModelChange = {
+    kind: 'started';
+    view: GenerationView;
+    superseded?: GenerationView;
+} | {
+    kind: 'progress';
+    view: GenerationView;
+    phaseStarted: boolean;
+    passRestarted: boolean;
+} | {
+    kind: 'settled';
+    view: GenerationView;
+    event: ProgressSettledEvent;
+} | {
+    kind: 'activity';
+    event: ProgressActivityEvent;
+};
+/**
+ * The generation-scoped progress state: one start, strictly increasing `seq`, one settle; phases in
+ * declared order; fixed totals and monotonic counts. Only the newest started generation
+ * is tracked. Stale, out-of-order and malformed events are dropped (`apply` returns `undefined`);
+ * nothing throws.
+ */
+export declare class ProgressModel {
+    private latest;
+    private currentView;
+    /** Running activities, per kind: a warm-up and an input check may overlap. */
+    private readonly activities;
+    /** Sticky: once any generation reported a compiler phase, later generations are stepped. */
+    private compilerReports;
+    get current(): GenerationView | undefined;
+    /** A generation has started and not settled. */
+    get inFlight(): boolean;
+    apply(event: ProgressEvent): ModelChange | undefined;
+    private started;
+    /** The view when `event` belongs to the in-flight generation and advances its `seq`. */
+    private accepting;
+    private progress;
+    private settled;
+    /**
+     * Activities are tracked per kind and are accepted during a generation too: the session does
+     * not run them inside one, but a failure must never be lost to an ordering surprise. An `end`
+     * without a matching `start` is dropped, unless it reports a failure.
+     */
+    private activityChange;
+}

package/generator/progress/reporter.d.ts

@@ -0,0 +1,87 @@
+import type { ProgressEnvironment, ProgressStream } from './detect.js';
+import type { ProgressEvent } from './events.js';
+import type { ExitHook, LiveStream } from './live.js';
+import type { ProgressSetting } from './settings.js';
+/**
+ * The host's output port. Every method writes one complete line, except `live`, which receives the
+ * in-place line. Hosts map it to their logger: the CLI writes progress to stderr and results to
+ * stdout; Vite uses `server.config.logger.info` (never with `clear`) and, after listen,
+ * `{ timestamp: true }`; Angular uses `context.logger.info`.
+ */
+export interface ProgressWriter {
+    /** Progress and notice lines. */
+    line(text: string): void;
+    /** Result lines (build summary, per-edit line). Defaults to `line`. */
+    summary?(text: string): void;
+    /** Lines after another writer took the terminal (`foreign`). Defaults to `summary`/`line`. */
+    timestampedLine?(text: string): void;
+    /** The `json` style: one event per line, for the CLI's `--json` stdout stream. Defaults to `line`. */
+    json?(text: string): void;
+    /** Where the live line is drawn; without it the reporter never redraws in place. */
+    live?: LiveStream & ProgressStream;
+}
+/** Injectable time source: the reporter's own cadence. Displayed durations come from the session clock. */
+export interface ProgressClock {
+    now(): number;
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare const systemClock: ProgressClock;
+/**
+ * What the reporter still prints once another writer shares the terminal. `notices`: results plus
+ * the slow-edit and background notices (the Vite dev server, whose log is NgDoc's to share).
+ * `summaries`: results only (the CLI after it spawns a host), because the host's own output owns
+ * the terminal.
+ */
+export type ForeignMode = 'summaries' | 'notices';
+export interface ProgressReporterOptions {
+    writer: ProgressWriter;
+    /** The resolved setting; by default `resolveProgressSetting({ env })`. */
+    setting?: ProgressSetting;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** Another writer already shares the terminal (`true` means `notices`). */
+    foreign?: boolean | ForeignMode;
+    /** Named in the LINES start line; defaults to the Nx task project. */
+    project?: string;
+    clock?: ProgressClock;
+    /** Wall clock for GitLab section timestamps; `Date.now` by default. */
+    date?: () => number;
+    exitHook?: ExitHook;
+    /** Used for `$GITHUB_STEP_SUMMARY` (sections only). */
+    appendFile?: (file: string, data: string) => void;
+    /**
+     * The reporter stopped after its writer threw. Called once; hosts report it as the
+     * `SESSION_PROGRESS_FAILED` warning (`progressFailure`). Progress never stops a build or a watch.
+     */
+    onError?: (error: unknown) => void;
+}
+export interface ProgressReporter {
+    readonly environment: ProgressEnvironment;
+    /** Feeds one event. Never throws. */
+    handle(event: ProgressEvent): void;
+    /**
+     * Another writer took the terminal: the Vite dev server after it listens (`notices`) and the CLI
+     * after it spawns a host (`summaries`).
+     */
+    setForeign(mode?: ForeignMode): void;
+    /**
+     * The host is about to print its own output (a result's diagnostics): the live line is cleared
+     * first, so the output never lands behind it, and it is redrawn on its next frame.
+     */
+    interrupt(): void;
+    /**
+     * Clears the live line synchronously and stops. An unfinished generation gets no summary; a
+     * superseded one whose successor never started gets its committed result line.
+     */
+    dispose(): void;
+}
+/** Slow edits and background work stay quiet unless they run longer than this. */
+export declare const NOTICE_AFTER_MS = 2000;
+/** How long a superseded generation's result waits for the generation that continues it. */
+export declare const CARRY_EXPIRY_MS = 1000;
+/**
+ * Creates the reporter for one build session. Use one reporter per session: it follows a single
+ * generation sequence and drops events of generations older than the newest it has seen.
+ */
+export declare function createProgressReporter(options: ProgressReporterOptions): ProgressReporter;

package/generator/progress/settings.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Progress settings. Precedence: CLI flag > `NGDOC_PROGRESS` > builder or plugin
+ * option > host quiet settings > `auto`.
+ */
+export type ProgressSetting = 'auto' | 'live' | 'plain' | 'summary' | 'off' | 'json' | 'verbose';
+/** Builder and plugin options take every setting except `json`, which is for tools. */
+export type ProgressOptionSetting = Exclude<ProgressSetting, 'json'>;
+export declare const PROGRESS_SETTINGS: readonly ProgressSetting[];
+export declare const PROGRESS_ENV = "NGDOC_PROGRESS";
+/** Opt-in GitHub/GitLab collapsible groups and the GitHub step summary. */
+export declare const PROGRESS_SECTIONS_ENV = "NGDOC_PROGRESS_SECTIONS";
+/** Node warning code for an unknown `NGDOC_PROGRESS` value (once per process). */
+export declare const NGDOC_PROGRESS_VALUE = "NGDOC_PROGRESS_VALUE";
+export type ProgressSettingSource = 'cli' | 'env' | 'option' | 'host' | 'default';
+export interface ResolvedProgressSetting {
+    setting: ProgressSetting;
+    source: ProgressSettingSource;
+}
+/** What the host says about its own quietness. */
+export interface HostQuiet {
+    /** Vite `logLevel`: `warn`, `error` and `silent` turn progress off. */
+    viteLogLevel?: 'info' | 'warn' | 'error' | 'silent';
+}
+export interface ResolveProgressOptions {
+    /** `--progress <value>`, already validated by the CLI (`isProgressSetting`). */
+    cli?: ProgressSetting;
+    env?: NodeJS.ProcessEnv;
+    /** The Vite plugin option `progress` (Vite dev server and build). */
+    option?: ProgressOptionSetting;
+    host?: HostQuiet;
+    /** Defaults to `process.emitWarning`. */
+    warn?: (message: string, code: string) => void;
+}
+export declare const isProgressSetting: (value: unknown) => value is ProgressSetting;
+/** Normalises a user-typed value (`' Plain '` → `plain`); `undefined` when it is not a setting. */
+export declare function parseProgressSetting(value: string | undefined): ProgressSetting | undefined;
+/** Test hook: forget which unknown values were already reported in this process. */
+export declare function resetProgressWarnings(): void;
+/**
+ * Resolves the effective setting. An unknown `NGDOC_PROGRESS` warns once and counts as unset. The
+ * first explicit setting wins, except that an explicit `auto` ("decide for me") still yields to
+ * the host's quiet settings.
+ */
+export declare function resolveProgressSetting(options?: ResolveProgressOptions): ResolvedProgressSetting;
+/** `NGDOC_PROGRESS_SECTIONS`: `1`/`true`/`on`/`yes` turn the CI sections on. */
+export declare function sectionsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Engine switches that change how fast NgDoc works. When one is set to a non-default value, the
+ * reporter prints one notice, so a slow edit explains itself.
+ */
+export declare const ENGINE_SWITCHES: ReadonlyArray<{
+    name: string;
+    values: RegExp;
+    effect: string;
+}>;
+/**
+ * The engine switches set in `env`, in declaration order, each as `NAME=value (effect)`. `verify`
+ * values add checks rather than turning something off.
+ */
+export declare function activeEngineSwitches(env?: NodeJS.ProcessEnv): string[];

package/generator/semantic/angular.d.ts

@@ -0,0 +1,9 @@
+import { type ObjectLiteralExpression, type SourceFile, Node, ts } from 'ts-morph';
+import type { GeneratorConfiguration, GuideSemantics, JsonValue } from '../contracts.js';
+import { type TrackedFiles } from './dependencies.js';
+import type { JsDoc } from './rendering.js';
+/** Resolves wrappers and local constants without executing source code. */
+export declare function unwrap(node: Node | undefined, seen?: Set<Node<ts.Node>>): Node | undefined;
+export declare function entryObject(source: SourceFile): ObjectLiteralExpression;
+export declare function literal(node: Node | undefined): JsonValue;
+export declare function guideSemantics(source: SourceFile, files: TrackedFiles, config: GeneratorConfiguration, docs: JsDoc, values?: JsonValue): GuideSemantics;

package/generator/semantic/api-enumeration.d.ts

@@ -0,0 +1,19 @@
+import { type JSDocableNode, Node } from 'ts-morph';
+import type { DeclarationDescriptor, Diagnostic } from '../contracts.js';
+import { type TrackedFiles } from './dependencies.js';
+import type { QueryContext } from './fragments.js';
+import { type Snapshot, type SupportedDeclaration } from './program-state.js';
+/**
+ * API enumeration: the declarations of an API entry's scopes, with their identities, routes and
+ * exported keywords.
+ */
+/** The node whose JSDoc documents a declaration (a variable's statement). */
+export declare function docNode(node: Node): JSDocableNode | undefined;
+export declare function supported(node: Node): node is SupportedDeclaration;
+/** Semantic names and relative source paths survive checkout relocation and scope reordering. */
+export declare function declarationIdentity(project: string, api: string, scope: string, workspace: string, source: string, name: string): string;
+/**
+ * The public declarations of an API entry, in scope and export order, registered in the snapshot
+ * for later fragment requests.
+ */
+export declare function enumerateApi(state: Snapshot, entryId: string, files: TrackedFiles, diagnostics: Diagnostic[], context: QueryContext): DeclarationDescriptor[];

package/generator/semantic/api-summary.d.ts

@@ -0,0 +1,33 @@
+import { type ClassDeclaration, type EnumDeclaration, type InterfaceDeclaration, type JSDocableNode } from 'ts-morph';
+import type { SupportedDeclaration } from './program-state.js';
+/**
+ * The summary of an API declaration that the search palette and the API index show: a short
+ * signature and a one-line description.
+ *
+ * Both are read from the declaration's own syntax (its header and its doc comment), never from
+ * the type checker, so they depend only on the text of the declaring file, which the enumeration
+ * that calls this has already read. A type the declaration only refers to is printed as written.
+ */
+export interface ApiSummary {
+    /** The declaration header, for example `export class Name<T> extends Base`; a line per decorator. */
+    signature: string;
+    /**
+     * The first paragraph of the doc comment as plain text: its first sentence when the paragraph is
+     * longer than {@link API_DESCRIPTION_LIMIT} characters, cut at a word when that is still longer.
+     */
+    description?: string;
+}
+/** The longest description kept: one line in the palette preview and the index. */
+export declare const API_DESCRIPTION_LIMIT = 160;
+/**
+ * The summary of a declaration.
+ * @param node - The declaration.
+ * @param doc - The node that holds its doc comment (a variable's statement).
+ */
+export declare function apiSummary(node: SupportedDeclaration, doc: JSDocableNode | undefined): ApiSummary;
+/**
+ * The declaration panel of a class, an interface or an enum page: its signature with an elided
+ * body, and each heritage clause on its own indented line when the header does not fit on one line.
+ * @param node - The class, interface or enum.
+ */
+export declare function apiDeclaration(node: ClassDeclaration | InterfaceDeclaration | EnumDeclaration): string;

package/generator/semantic/dependencies.d.ts

@@ -0,0 +1,20 @@
+import type { Dependency, Diagnostic, SourceLocation } from '../contracts.js';
+import { ObservationRecorder } from '../kernel/observations.js';
+export declare const normalize: (file: string) => string;
+/** The sha256 of a text; digests of values go through `digestOf` (`kernel/canonical.ts`). */
+export declare const digest: (text: string) => string;
+export declare class SemanticFailure extends Error {
+    readonly code: string;
+    readonly source?: SourceLocation | undefined;
+    constructor(code: string, message: string, source?: SourceLocation | undefined);
+}
+export declare function diagnostic(error: unknown, source?: SourceLocation): Diagnostic;
+/**
+ * The semantic service's files recorder: the kernel {@link ObservationRecorder} without a byte
+ * cache (program observations outlive a generation), whose reads fail as semantic diagnostics.
+ * Two reads of one path that saw different bytes record a conflicting digest.
+ */
+export declare class TrackedFiles extends ObservationRecorder {
+    constructor(initial?: Dependency[], observer?: (dependency: Dependency) => void);
+    read(file: string): string;
+}

package/generator/semantic/derived-classes.d.ts

@@ -0,0 +1,58 @@
+import { type ClassDeclaration, type Project, Node, ts } from 'ts-morph';
+/**
+ * One heritage index per TypeScript program for the API "See Also" section.
+ *
+ * ts-morph `ClassDeclaration#getDerivedClasses()` runs a language-service `findReferences`
+ * for the class and then again for every class it finds, so a base class with N subclasses
+ * costs N + 1 whole-program reference searches (apps/ng-doc: 658 page subclasses of
+ * `NgDocRootPage`, about 16 s for one page).
+ *
+ * The index is built in one pass over the class declarations of the program. It records, for
+ * every `extends` clause, each identifier that ts-morph would accept as the reference to the
+ * base class (the expression itself, or any name in a property-access chain) both by text and
+ * by the declarations its symbol resolves to through any import/export aliases. A class that
+ * appears in neither set cannot be returned by a reference search: TypeScript reports only
+ * identifiers that bind to the searched symbol, directly or through an alias. Such a class has
+ * no derived classes, and no reference search runs for it.
+ *
+ * A class that the index marks may have subclasses keeps the exact ts-morph lookup, so the
+ * result, including its order (which follows TypeScript's reference-group order), is the one
+ * `getDerivedClasses()` returns.
+ */
+export declare class DerivedClassIndex {
+    private readonly names;
+    private readonly targets;
+    constructor(program: ts.Program);
+    /** False only when no reference search can find a class deriving from `declaration`. */
+    mayHaveDerivedClasses(declaration: ClassDeclaration): boolean;
+}
+/**
+ * The index of the project's current program; a changed program gets a new index. It is a shared
+ * index, so it is built with recording suspended: the one pass over every class would otherwise
+ * land in the footprint of whichever unit happens to render first.
+ *
+ * Its answers are NOT covered by the unit's footprint. A `true` is followed by the recorded
+ * reference search, but a `false` ("no subclass can exist") depends on the heritage clauses of
+ * every file in the program: adding `class Sub extends Lone` anywhere changes `Lone`'s See Also
+ * while `R(Lone)` does not contain that file. The scope records the class instead
+ * (`recordDerivedQuery`), and its semantic closure recomputes the list (`derivedClassList`); the
+ * index must not be turned into a replayed `recordedAnswer`, whose footprint could not state it.
+ */
+export declare function derivedClassIndex(project: Project): DerivedClassIndex;
+/** Same result and order as ts-morph `getDerivedClasses()`, without searches for leaf classes. */
+export declare function getDerivedClasses(declaration: ClassDeclaration, index: DerivedClassIndex): ClassDeclaration[];
+/** The identity of a class for the semantic closure: its file and start position. */
+export declare function classIdentity(declaration: ts.ClassDeclaration): string;
+/**
+ * The derived-class list of the class `identity` names in the project's current program, as it
+ * would be rendered (order included): each class's identity and name. `absent` when no class
+ * starts there. Callers run it with recording suspended.
+ */
+export declare function derivedClassList(project: Project, identity: string): string;
+/**
+ * Runs `render` while `declaration.getDerivedClasses()` is served from the program index.
+ *
+ * The shared API templates call that method directly and are shared with the legacy engine,
+ * so the modern engine changes the value it supplies rather than the template.
+ */
+export declare function withIndexedDerivedClasses<T>(declaration: Node, project: Project, render: () => T): T;

package/generator/semantic/documentation-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TypeScript caches the documentation of a symbol on the symbol object (`documentationComment`,
+ * `tags` and the contextual accessor variants), including documentation it inherited from base
+ * types in other files. A patched program reuses the unchanged files' source files, and with them
+ * the symbols their binder created, so after a base file is patched a reused symbol would keep
+ * answering with the documentation of the old base, where a cold program computes the new one.
+ *
+ * The readers below remember, per symbol, the checker its cached answers were computed with, and
+ * drop the cache when another checker asks (a patched program's, or the language service's, which
+ * sees the same files and computes the same answer). A cache found without a remembered checker
+ * (computed before these readers were installed) is dropped once as well. Signatures are created by
+ * the checker, so each program has its own.
+ */
+/** The symbol methods that cache documentation, with the position of their checker argument. */
+export declare const CACHED_DOCUMENTATION_METHODS: ReadonlyArray<readonly [string, number]>;
+/** The fields TypeScript caches those answers in. */
+export declare const CACHED_DOCUMENTATION_FIELDS: readonly string[];
+/**
+ * Installs the checker-aware documentation readers on TypeScript's symbol prototype, once per
+ * process. Throws when a pinned-version assumption does not hold (a method is missing), which the
+ * caller treats as a patch it cannot make.
+ */
+export declare function installDocumentationFreshness(): void;

package/generator/semantic/fragments.d.ts

@@ -0,0 +1,28 @@
+import type { SemanticFragment, SemanticFragmentRequest } from '../contracts.js';
+import type { FootprintScopeKind } from '../kernel/footprint.js';
+import { TrackedFiles } from './dependencies.js';
+import { type Snapshot } from './program-state.js';
+import { type SemanticRecorder } from './recorder.js';
+import { type createJsDoc } from './rendering.js';
+/**
+ * Semantic fragments: the entry JSDoc value, the JSDoc fragments of a declaration, and the
+ * rendered API templates.
+ */
+/** The service's rendering helpers a query needs, bound to the query's observations. */
+export interface QueryContext {
+    docs(source: string, files: TrackedFiles): ReturnType<typeof createJsDoc>;
+    markdown(text: string, source: string, files: TrackedFiles): string;
+}
+export interface FragmentContext extends QueryContext {
+    recorder: SemanticRecorder;
+    /** Whether queries record semantic closures (their footprint states the program files read). */
+    scoped?(): boolean;
+    /** Whether whole-program queries share one tracking of the program (`trackWholeProgram`). */
+    trackedProgramReuse?: boolean;
+    /** The API template root (the option, or the shipped templates). */
+    templateRoot(): string;
+}
+/** The recorder scope of a fragment request: its phase kind and its unit key. */
+export declare function fragmentScope(request: SemanticFragmentRequest): [FootprintScopeKind, string];
+/** Renders one fragment request against the snapshot, recording its reads in `files`. */
+export declare function renderFragment(state: Snapshot, request: SemanticFragmentRequest, files: TrackedFiles, context: FragmentContext): SemanticFragment;

package/generator/semantic/owned-roots.d.ts

@@ -0,0 +1,59 @@
+import { type FileSystemHost, ts } from 'ts-morph';
+/**
+ * Generator-owned roots hold this generator's own output and cache. They are never semantic
+ * inputs: the TypeScript program must not resolve into them and dependency tracking must not
+ * record them, otherwise a generation's own commit would change the next generation's
+ * semantic scope. Every other path resolves exactly as through the real file system.
+ */
+export declare class OwnedRoots {
+    private readonly roots;
+    /** The raw reads that began with a byte order mark, which the program's text omits. */
+    private readonly marked;
+    constructor(roots: readonly string[]);
+    has(file: string): boolean;
+    /** The owned root containing a path, if any. */
+    describe(file: string): string | undefined;
+    /**
+     * A non-owned path that is a symlink into an owned root stays unresolved: it is read through
+     * its own path like any other input instead of resolving to a hidden owned file.
+     */
+    realpath(path: string, resolve: (path: string) => string): string;
+    /** Notes a raw text read of the program's file system (see {@link contentDigest}). */
+    recordRead(file: string, text: string): void;
+    /**
+     * The content digest of a program file whose text is `text`. TypeScript drops a leading byte
+     * order mark from the text it compiles, while every other reader (and the refresher) digests the
+     * file's bytes; so a file read with one is digested from its raw read, and the recorded digest
+     * matches theirs.
+     */
+    contentDigest(file: string, text: string): string;
+    /** A module resolution host view without owned paths; owned probes are neither made nor recorded. */
+    resolutionHost(host: ts.ModuleResolutionHost): ts.ModuleResolutionHost;
+    /** The real ts-morph file system with owned paths absent. Writes are never issued by semantic. */
+    fileSystem(): FileSystemHost;
+}
+type NotFoundError = new (path: string) => Error;
+/**
+ * Returns the error class a real ts-morph file system throws for a missing file. ts-morph's
+ * transactional file system recognises "does not exist" only by that class (for example in
+ * readFileIfExistsSync), and the class is not part of its public declarations. It is therefore
+ * observed from the real host itself. If a ts-morph upgrade stops reporting a missing file this
+ * way, owned-root hiding cannot be enforced and synchronization fails loudly instead of silently
+ * treating owned files as unreadable.
+ */
+export declare function missingFileError(fileSystem: FileSystemHost): NotFoundError;
+/**
+ * The first owned root an API scope pattern can reach, judged from the patterns and the file
+ * shapes the generator writes, not from files that exist now: a scope that can match generated
+ * output would otherwise start failing only after the first commit. A generated path is excluded
+ * when a scope exclude matches it or one of its directories, as the scope scan's ignore does.
+ * Matches that exist anyway are still rejected by the caller's actual-match check.
+ */
+export declare function ownedRootReach(workspaceRoot: string, include: readonly string[], exclude: readonly string[], roots: {
+    outputRoot: string;
+    cacheRoot: string;
+}): {
+    root: string;
+    pattern: string;
+} | undefined;
+export {};