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

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 {};

package/generator/semantic/program-builder.d.ts

@@ -0,0 +1,55 @@
+import { Project, ts } from 'ts-morph';
+import type { DiscoverySnapshot } from '../contracts.js';
+import { type TrackedFiles, SemanticFailure } from './dependencies.js';
+import { OwnedRoots } from './owned-roots.js';
+import type { ProgramObservations } from './program-observations.js';
+/**
+ * The program lifecycle: builds the TypeScript Project of a discovery snapshot and records every
+ * observation it depends on. Per-importer tracking lives in `program-observations.ts`, retention
+ * in `program-retention.ts`.
+ */
+export declare function ownedOverlap(kind: string, path: string, owned: OwnedRoots): SemanticFailure;
+/**
+ * The formatter configuration files probed in the workspace root and each of its ancestors:
+ * formatting helpers receive the workspace explicitly, so their configuration is a program input.
+ */
+export declare const FORMATTER_CONFIGURATION_FILES: readonly string[];
+/** Records the existence (and the content, when present) of every formatter configuration file. */
+export declare function trackFormatterConfiguration(workspaceRoot: string, files: TrackedFiles): void;
+/** A built program: its Project, the members of each API scope, and the owned-root view. */
+export interface BuiltProgram {
+    project: Project;
+    /** `${entryId}:${scopeId}` → the sorted scope matches. */
+    scopes: Map<string, string[]>;
+    owned: OwnedRoots;
+    /** The root names of the built program (see `ProgramMirror.roots`). */
+    roots: readonly string[];
+}
+/** The root membership of a discovery snapshot's program (see {@link programMembers}). */
+export interface ProgramMembers {
+    parsed: ts.ParsedCommandLine;
+    owned: OwnedRoots;
+    /** `${entryId}:${scopeId}` → the sorted scope matches. */
+    scopes: Map<string, string[]>;
+    /** The files the Project is built from, in the order they are handed to ts-morph. */
+    members: string[];
+}
+/**
+ * The root membership of a discovery snapshot's program, recorded into `files` exactly as a FULL
+ * synchronization records it: the tsconfig reads, each entry's module and API scope glob, and the
+ * tsconfig membership. A root change of a retained program (`program-retention.ts`) records the
+ * same observations again with this function. Throws a `SemanticFailure`.
+ */
+export declare function programMembers(discovery: DiscoverySnapshot, files: TrackedFiles): Promise<ProgramMembers>;
+/**
+ * Builds the program of a discovery snapshot into `observations`: the tsconfig, the entries and API
+ * scopes (global), every program file (per importer), the formatter configuration (global), and
+ * last the aggregate `semantic` definition. Throws a `SemanticFailure`; what was observed until
+ * then stays in `observations`.
+ */
+export declare function buildProgram(discovery: DiscoverySnapshot, observations: ProgramObservations): Promise<BuiltProgram>;
+/**
+ * The failure a synchronization reports for a program with syntax errors, or undefined. A patched
+ * program is checked with the same function, so its diagnostic is the cold one.
+ */
+export declare function syntaxFailure(program: ts.Program): SemanticFailure | undefined;

package/generator/semantic/program-index.d.ts

@@ -0,0 +1,124 @@
+import { type Project, ts } from 'ts-morph';
+/**
+ * The program index behind the recorded semantic closure: per-file facts of one TypeScript
+ * program, each a pure function of that program, so a cold and an incremental generation compute
+ * the same digests.
+ *
+ * - `content(F)`: the digest of F's text as the program read it.
+ * - `token(F)`: F without comments and formatting (the printed AST, plus its triple-slash
+ *   directives) for TypeScript sources; the content for everything else (declaration, JavaScript,
+ *   JSX and JSON files, whose comments or pragmas can carry types).
+ * - `exportSurface(B)`: `token(B)`, the export map of B (each exported name to the files and name
+ *   of its resolved declaration) and the export map of every `export *` target of B, recursively,
+ *   including targets that export nothing. It holds no target's type information.
+ * - `typeClosure(F)`: `token(F)` and, per imported name, the export surfaces of the modules on the
+ *   name's alias chain and the `typeClosure` of the declaring files; any other module reference
+ *   (a namespace or side-effect import, an import type, a dynamic import or `require`, an import
+ *   equals, a triple-slash path reference) contributes that module's surface and the closures of
+ *   the module and of every declaration it exports. Cycles are condensed: every file of a strongly
+ *   connected component gets the component's digest. Declaration files under `node_modules` are
+ *   leaves: their content is in `env`.
+ * - `env`: the TypeScript version, the compiler options, the caller's global program observations
+ *   (tsconfig reads, formatter probes, type directives) and the content of every global-effect
+ *   file: declaration files, scripts, and modules with `declare global` or an ambient
+ *   `declare module`.
+ * - the derived-class list of a class, as the API template renders it.
+ *
+ * - `dtsShape(F)`: F's declaration shape, the isolated declaration emit of a TypeScript source
+ *   (`ts.transpileDeclaration`, comments removed) plus its enum declarations; the `token` of every
+ *   other file, and of a source the isolated emit reports a diagnostic for (a type it cannot state
+ *   without the checker, such as an inferred return type). The emit is given the program's
+ *   type-affecting options (strictness included: TypeScript's defaults are not the program's), so
+ *   it is a function of F's name, text and those options, and is memoized across programs.
+ * - `shapeClosure(F)`: `typeClosure(F)` over declaration shapes: `dtsShape(F)` and, per imported
+ *   name, the shape surfaces (`exportSurface` with `dtsShape` in place of `token`) of the modules
+ *   on its chain and the `shapeClosure` of the declaring files. A body edit that keeps the
+ *   declaration shapes keeps every `shapeClosure`.
+ *
+ * A unit's closure digest is `H(env, [(f, content(f), typeClosure(f)) for f in R], [(class,
+ * derived list)])`. With shape closures (`NGDOC_SHAPE_CLOSURE`), every file of `R` takes
+ * `shapeClosure(f)` in place of `typeClosure(f)`. `content(f)` stays, so whatever a query read of a
+ * file itself (its initializers, parameter defaults, bodies, comments) is covered by its content;
+ * only what it did not read, the files it merely depends on, is followed by shape. That is sound
+ * as long as the recorder puts every file a query reads into `R` and a declaration shape states
+ * everything an importer's types take from its file.
+ * Everything is computed with recording suspended: the index is shared by every scope and must not
+ * land in the footprint of whichever query asks first.
+ */
+export declare class ProgramIndex {
+    private readonly program;
+    private readonly project;
+    private readonly observations;
+    private readonly checker;
+    private environment?;
+    private readonly contents;
+    private readonly tokens;
+    private readonly exportMaps;
+    private readonly surfaces;
+    private readonly stars;
+    private readonly providers;
+    private readonly facts;
+    private readonly closures;
+    private readonly shapes;
+    private readonly shapeSurfaces;
+    private readonly shapeClosures;
+    private shapeOptions?;
+    private readonly derivedLists;
+    private readonly digests;
+    constructor(program: ts.Program, project: Project, observations: string);
+    /**
+     * The closure digest of a scope that read `files` and the derived lists of `derived`: with
+     * `shape` (shape closures on), each file's `shapeClosure` in place of its `typeClosure`.
+     */
+    closure(files: readonly string[], derived: readonly string[], shape?: boolean): string;
+    env(): string;
+    content(file: string): string;
+    token(file: string): string;
+    typeClosure(file: string): string;
+    /** `typeClosure` over declaration shapes (see the class comment). */
+    shapeClosure(file: string): string;
+    /** The declaration shape of a file (see the class comment). */
+    dtsShape(file: string): string;
+    /** The program's options the isolated declaration emit depends on, and their memo key. */
+    private declarationOptions;
+    /** `exportSurface` with `dtsShape` in place of `token`. */
+    shapeSurface(file: string): string;
+    exportSurface(file: string): string;
+    private derivedList;
+    /** Each exported name of a module, with the files and name of its resolved declaration. */
+    private exportMap;
+    /** The resolved files of every `export *` target of `file`, recursively, sorted. */
+    private starTargets;
+    /** The files a module specifier resolves to: the resolved module, or an ambient module's files. */
+    private moduleFiles;
+    /**
+     * The files declaring what a module exports (its export surface names any export that does not
+     * resolve, so it needs no provider).
+     */
+    private exportProviders;
+    private resolveAlias;
+    /** The references and the successors of one file in the closure graphs. */
+    private factsOf;
+    /** A file's local contribution to `typeClosure`: its token and its references' surfaces. */
+    private readonly typeLocal;
+    /** A file's local contribution to `shapeClosure`: its shape and its references' shape surfaces. */
+    private readonly shapeLocal;
+    private edges;
+    /**
+     * One imported name: every module on its alias chain (whose surfaces it depends on), and the
+     * files that declare the symbol the chain ends at. Undefined when the chain does not resolve.
+     */
+    private namedEdge;
+    /**
+     * Tarjan's algorithm from `root` over the files not condensed yet in `closures`; every component
+     * gets `H(tag, its members and their local contributions, the digests of the components it
+     * reaches)`.
+     */
+    private condense;
+}
+/**
+ * The index of the project's current program; a changed program (a FULL synchronization, or a
+ * query that added a source file) gets a new one. `observations` digests the program's global
+ * observations that `env` includes.
+ */
+export declare function programIndex(project: Project, observations: string): ProgramIndex;

package/generator/semantic/program-inputs.d.ts

@@ -0,0 +1,26 @@
+import { ts } from 'ts-morph';
+import type { Dependency } from '../contracts.js';
+import type { OwnedRoots } from './owned-roots.js';
+/** Present only while the recorded membership cannot be trusted: never exists, never verifies. */
+export declare const UNVERIFIABLE_MEMBERSHIP = ".ng-doc-unverifiable-tsconfig-membership";
+export interface TsconfigSpecs {
+    files: string[];
+    include: string[];
+    exclude: string[];
+}
+/** TypeScript's validated specs with `${configDir}` substituted, from the configuration it used. */
+export declare function tsconfigSpecs(parsed: ts.ParsedCommandLine, configFile: string): TsconfigSpecs;
+/**
+ * Filesystem observations that let the session re-verify how the tsconfig selected its program
+ * root files after watcher subscription:
+ * - every `files` entry as an existence observation (program bytes are recorded separately);
+ * - one glob per static include directory, recorded through the same dependency refresher the
+ *   session re-verifies with, so an unchanged tree reproduces the recorded members exactly.
+ *
+ * Include patterns may over-include relative to TypeScript (supported-extension groups, dot
+ * folders); excludes are applied only where fast-glob provably excludes no more than TypeScript.
+ * As a backstop, if any TypeScript root file is not reproduced by the recorded observations, an
+ * input that can never verify is recorded, so a translation gap always regenerates instead of
+ * reusing a result that may be stale. Owned roots are never observed.
+ */
+export declare function tsconfigMembershipDependencies(parsed: ts.ParsedCommandLine, configFile: string, owned: OwnedRoots, specs?: TsconfigSpecs): Promise<Dependency[]>;

package/generator/semantic/program-observations.d.ts

@@ -0,0 +1,158 @@
+import { type Project, ts } from 'ts-morph';
+import type { Dependency } from '../contracts.js';
+import { TrackedFiles } from './dependencies.js';
+import type { OwnedRoots } from './owned-roots.js';
+import type { ResolutionProbes, SemanticDefinition } from './program-state.js';
+/**
+ * Per-importer program tracking.
+ *
+ * A synchronization observes the program in two parts:
+ * - **global** observations: the tsconfig reads, the entries, the API scope globs, the tsconfig
+ *   membership, the formatter configuration probes, and the private probes of the `types`
+ *   directives;
+ * - **per importer**: for every program file, its own existence and content, and every probe the
+ *   resolution of its imports, type references and referenced files made, with what each resolved
+ *   to.
+ *
+ * The published dependency set is their aggregate, built exactly as one flat set would be (the
+ * same additions in the same order into one {@link TrackedFiles}). The attribution is an ordered
+ * log beside it, so one importer can be re-tracked after a patch and the aggregate re-derived from
+ * the log, and the resolved edges give the importers of a file (the reverse graph).
+ */
+/** Resolution facts reported by a tracking host (see `ProgramWatch`). */
+export interface ProbeSink {
+    missing(directory: string): void;
+    realpath(from: string, to: string): void;
+}
+/** One reference of a program file and the file it resolved to (normalized), if any. */
+export interface ImportResolution {
+    readonly kind: 'module' | 'type-reference' | 'reference';
+    readonly specifier: string;
+    readonly resolved?: string;
+}
+/** What tracking one program file observed, in observation order. */
+export interface ImporterObservations {
+    readonly path: string;
+    readonly dependencies: readonly Dependency[];
+    readonly missing: readonly string[];
+    readonly realpaths: ReadonlyArray<readonly [string, string]>;
+    readonly imports: readonly ImportResolution[];
+}
+/** What the aggregate `semantic` definition is derived from, besides the observations. */
+export interface SemanticConfiguration {
+    readonly projectId: string;
+    readonly digest: string;
+}
+/** `ts.sys.realpath` (what module resolution uses), or undefined when the path cannot be resolved. */
+export declare function realpathOf(path: string): string | undefined;
+/**
+ * A module resolution host that records every file probe and read in `files` and, when given,
+ * every directory reported missing and every symlinked path resolved in `probes`. The same
+ * owned-root view as the program: owned probes are neither followed nor recorded.
+ */
+export declare function trackingHost(files: TrackedFiles, owned: OwnedRoots, probes?: ProbeSink): ts.ModuleResolutionHost;
+/**
+ * Tracks one program file: its existence and content, and all failed candidate paths and package
+ * manifests of its imports and type references, not only the successfully loaded files. A newly
+ * created missing module or a changed exports/types field must invalidate consumers.
+ */
+export declare function trackSourceFile(source: ts.SourceFile, options: ts.CompilerOptions, host: ts.ModuleResolutionHost, files: TrackedFiles, owned: OwnedRoots, imports?: ImportResolution[]): void;
+/**
+ * Tracks every non-owned file of the project's program into one flat set (a query that added a
+ * source file tracks the re-created program into its own dependencies this way).
+ */
+export declare function trackProgram(project: Project, files: TrackedFiles, owned: OwnedRoots): void;
+/**
+ * The aggregate `semantic` definition: the whole program, its configuration, resolution libraries
+ * and source membership, over the observations made so far.
+ */
+export declare function semanticDefinition(configuration: SemanticConfiguration, files: TrackedFiles, project: Project): SemanticDefinition;
+/** The per-importer and global observations of one program, and their aggregate. */
+export declare class ProgramObservations {
+    private readonly segments;
+    private readonly importerSegments;
+    private current?;
+    private logging;
+    private aggregate;
+    private resolutionProbes;
+    private definition?;
+    private reverse?;
+    constructor();
+    /** The published observations: every global and per-importer one, and the definition. */
+    get files(): TrackedFiles;
+    /** Every directory reported missing and symlinked path resolved (global and per importer). */
+    get probes(): ResolutionProbes;
+    /** The aggregate `semantic` definition, once {@link define} ran. */
+    get semantic(): SemanticDefinition | undefined;
+    /** Reports resolution facts to the aggregate and to the current owner. */
+    readonly probeSink: ProbeSink;
+    /** Tracks every non-owned program file, each attributed to itself as importer. */
+    track(project: Project, owned: OwnedRoots): void;
+    /** Derives the aggregate `semantic` definition from the observations and publishes it. */
+    define(configuration: SemanticConfiguration, project: Project): SemanticDefinition;
+    /** The observations not attributed to a program file, in observation order. */
+    global(): Dependency[];
+    /** The tracked program files, in program order. */
+    importers(): string[];
+    /** What tracking one program file observed, or undefined when it is not a tracked importer. */
+    importer(path: string): ImporterObservations | undefined;
+    /** The tracked program files with a reference that resolved to this file, in program order. */
+    importersOf(path: string): string[];
+    /**
+     * The aggregate replayed from the attribution log: every observation (without the definition),
+     * probe and symlink in observation order. It equals what the aggregate recorded directly.
+     */
+    replay(): {
+        files: TrackedFiles;
+        probes: ResolutionProbes;
+    };
+    /**
+     * The aggregate as a synchronization that failed right after tracking the program files had it:
+     * every observation logged up to the last program file (the configuration, entries, scopes,
+     * membership and the files), without the later global ones (the formatter probes) and without a
+     * definition. A patched synchronization that fails its syntax check reports exactly these, as the
+     * cold one does.
+     */
+    throughImporters(): Dependency[];
+    /**
+     * Re-tracks program files against the project's current program: each file's observations are
+     * replaced in its place in the log, the aggregate and the probes are re-derived from the log,
+     * and so is the `semantic` definition when one was defined. Returns the
+     * re-tracked observations (the ones a patch re-stamps). The retained entries see the result,
+     * because they read the observations through the mirror.
+     *
+     * A program file can also be read as a global observation: an entry file is read before the
+     * program is tracked. A cold synchronization of the edited tree reads it again, so its global
+     * content observation takes the file's current digest too; otherwise the log would hold the old
+     * and the new digest of one path, and the aggregate would record them as conflicting. `reads`
+     * holds the digest of the bytes the caller applied (a global read digests the raw bytes, as
+     * `TrackedFiles.read` does); without it the file is read again.
+     */
+    retrack(project: Project, paths: Iterable<string>, owned: OwnedRoots, reads?: ReadonlyMap<string, string>): Dependency[];
+    /**
+     * The log's three parts: the global observations logged before the first program file (the
+     * program's root membership: the tsconfig reads, the entries, the API scope globs and the
+     * tsconfig membership), the tracked program files, and every later global observation (the
+     * formatter configuration probes).
+     */
+    layout(): {
+        membership: Dependency[];
+        importers: string[];
+        tail: Dependency[];
+        tailMissing: string[];
+        tailRealpaths: Array<[string, string]>;
+    };
+    /**
+     * Rebuilds the log for the project's current program after its root set or file set changed
+     * (`program-retention.ts` `restructureProgram`), as a cold synchronization of the same tree logs
+     * it: `membership`'s global observations (recorded again for the new root membership), then every
+     * non-owned program file in program order, then the later global observations as they are. A
+     * program file `keep` accepts keeps its segment (its observations were verified to hold); every
+     * other one is tracked again. The aggregate, the probes and the definition are re-derived from
+     * the log. Returns the observations of the files tracked again (the ones to stamp).
+     */
+    restructure(project: Project, owned: OwnedRoots, membership: ProgramObservations, keep: (path: string) => boolean): Dependency[];
+    private createAggregate;
+    private open;
+    private segment;
+}

package/generator/semantic/program-retention.d.ts

@@ -0,0 +1,147 @@
+import { type Project, ts } from 'ts-morph';
+import type { Dependency, DiscoverySnapshot, FileChange } from '../contracts.js';
+import { type DirectoryFact } from '../graph/index.js';
+import { type SemanticFailure } from './dependencies.js';
+import type { OwnedRoots } from './owned-roots.js';
+import { ProgramObservations } from './program-observations.js';
+import type { ProgramWatch, RetainedProgram, SweepCounters } from './program-state.js';
+/**
+ * Program retention: the key a retained program is valid for, the re-verification state recorded
+ * when it is retained, the check that decides whether it may be reused as it is or patched, and
+ * the patch itself: the content of edited program files applied to the retained Project, whose
+ * program TypeScript then re-creates from the old one.
+ */
+/** A tsconfig/jsconfig or package manifest change always rebuilds (resolution and options). */
+export declare const PROGRAM_CONFIGURATION: RegExp;
+/**
+ * Everything of a discovery snapshot that `synchronize` reads. Queries read the live snapshot of
+ * their own generation, so the rest may differ between the retaining and the reusing generation.
+ */
+export declare function programKey(discovery: DiscoverySnapshot): string;
+/**
+ * The re-verification state of a program synchronized for retention (see {@link ProgramWatch}).
+ * Recording the `types` directives' probes re-resolves them with a tracking host into the private
+ * observations only.
+ */
+export declare function watchProgram(project: Project, observations: ProgramObservations, owned: OwnedRoots, tsConfig: string, observedAtNs: bigint): ProgramWatch;
+/**
+ * A program's private observations (see {@link ProgramWatch}) as JSON, so that another process
+ * can check that a program synchronized now would be this one without building it: the published
+ * dependencies and these facts are everything the program read. Glob listings are left out: such
+ * a check observes each published glob again in full.
+ */
+export interface ProgramWatchFacts {
+    /** The `types` directives' probes and reads (content and existence observations). */
+    hidden: Dependency[];
+    missingDirectories: string[];
+    realpaths: Array<[string, string]>;
+    directories: DirectoryFact[];
+}
+/**
+ * The facts of `watch`, or undefined when a listing cannot vouch for its directory.
+ */
+export declare function watchFacts(watch: ProgramWatch): ProgramWatchFacts | undefined;
+/**
+ * Why the facts no longer hold, or undefined: the predicates of a retained program's sweep
+ * (`holds`), by reading, never by stat stamps. The caller checks the hidden observations with the
+ * published ones.
+ */
+export declare function watchFactsChange(facts: ProgramWatchFacts): string | undefined;
+/**
+ * Why a retained program may no longer describe the workspace, or the sweep counters when it
+ * provably still does: the discovery inputs of `synchronize` are equal, no change touches a
+ * program configuration, an observed path or an observed glob's membership, and every content
+ * and existence observation still holds (stat, re-hash on a stat change).
+ */
+export declare function stale(previous: RetainedProgram, key: string, changes: FileChange[]): string | SweepCounters;
+/** At most this many program files are patched into a retained program at once. */
+export declare const MAX_PATCHED_FILES = 50;
+/** What a synchronization may do with a retained program (see {@link assess}). */
+export type ProgramAssessment = {
+    kind: 'full';
+    reason: string;
+} | {
+    kind: 'reuse';
+    counters: SweepCounters;
+}
+/**
+ * Patch `files` (program files, in program order), then check the program as a cold one.
+ * `restructure`: the program's root membership or file set may change as well (entries added or
+ * removed, an API scope or tsconfig glob that gained or lost a file, a program file deleted), so
+ * the patch observes the root membership again (`restructureProgram`).
+ */
+ | {
+    kind: 'patch';
+    files: string[];
+    counters: SweepCounters;
+    restructure?: true;
+};
+/**
+ * Decides how a synchronization treats a retained program. Without `patching` this is
+ * {@link stale}: any change rebuilds. With it, the content observations of program files are
+ * verified one by one; the files whose bytes changed, and the paths a failed patch left applied
+ * (`ProgramMirror.appliedSinceBase`), are to be patched, and everything else the program observed
+ * must hold exactly as for a reuse. A change event of a program file that still exists is
+ * explained by that file's content, so it is taken off the events the remaining checks see.
+ *
+ * With `discovery` (the generation's snapshot), a change that moves the root membership (the
+ * discovery inputs of the program, an observed glob's membership, a deleted program file) may
+ * still be applied to the retained Project: {@link assessRestructure} checks everything but the
+ * root membership itself, which the patch observes again.
+ */
+export declare function assess(previous: RetainedProgram, key: string, changes: FileChange[], patching: boolean, discovery?: DiscoverySnapshot): ProgramAssessment;
+/** The outcome of {@link patchProgram}. */
+export type PatchResult = 
+/** The Project now equals a cold synchronization of the tree; its mirror says so. */
+{
+    kind: 'patched';
+}
+/**
+ * The patch is applied and tracked, but the program has syntax errors: the cold failure, with
+ * the observations a cold synchronization reports when it fails there.
+ */
+ | {
+    kind: 'failed';
+    failure: SemanticFailure;
+    dependencies: Dependency[];
+}
+/** The files cannot be patched; the Project may be changed and must not be kept. */
+ | {
+    kind: 'refused';
+    reason: string;
+};
+/**
+ * Applies the current content of `files` (program files of the retained Project, in program order)
+ * to the Project and re-creates its program from the old one:
+ *
+ * 1. Each file must be a TypeScript module before and after the edit (no declaration, JSON,
+ *    library or script file, no global or ambient module augmentation, no UMD global) whose
+ *    import, reference, type-reference and lib directives are unchanged; otherwise nothing is
+ *    changed and the patch is refused. A file whose directives changed, and an assessment that
+ *    moves the root membership (`restructure`), are applied by {@link restructureProgram}
+ *    instead, which needs the generation's `discovery`.
+ * 2. Write-ahead: each path is recorded as applied (`appliedSinceBase`) before the Project changes.
+ * 3. The texts are applied with the program's root names pinned to the FULL synchronization's.
+ * 4. The patched program must have the same root names and the same files in the same order, and
+ *    each re-tracked file must resolve exactly what it resolved before; otherwise it is refused.
+ * 5. The re-tracked files are re-stamped, as observed when their bytes were read.
+ * 6. The syntax check of a cold synchronization: errors fail the synchronization with the cold
+ *    diagnostic, and the paths stay applied.
+ *
+ * Throws only on a programmer error of ts-morph or TypeScript (or a pinned-version assumption that
+ * no longer holds), which the caller treats as refused.
+ */
+export declare function patchProgram(previous: RetainedProgram, assessment: {
+    files: readonly string[];
+    restructure?: true;
+}, discovery?: DiscoverySnapshot): Promise<PatchResult>;
+/** ts-morph's program wrapper; `_reset` is how its language service re-creates the program. */
+export interface ResettableProgram {
+    _reset(rootNames: readonly string[], host: unknown): void;
+}
+/**
+ * Runs `action` with the program's re-creation pinned to `roots`: ts-morph re-creates a changed
+ * program from every file in its cache (resolved dependencies included), which would change the
+ * root set, the file order and TypeScript's structure reuse.
+ */
+export declare function withPinnedRoots(program: ResettableProgram, roots: readonly string[], action: () => void, hostFor?: (host: ts.CompilerHost) => ts.CompilerHost): void;