@ahoo-wang/wow-generator 9.2.0-rc.0

package/dist/openapi/operations.d.ts

@@ -0,0 +1,78 @@
+import { Components, HTTPMethod, Operation, Parameter, PathItem, Paths, Reference, Response, Schema } from '@ahoo-wang/fetcher-openapi';
+/**
+ * Represents an HTTP method and its associated operation.
+ */
+export interface MethodOperation {
+    /** The HTTP method */
+    method: HTTPMethod;
+    /** The OpenAPI operation */
+    operation: Operation;
+}
+export interface OperationEndpoint extends MethodOperation {
+    path: string;
+}
+export declare function operationEndpointComparator(left: OperationEndpoint, right: OperationEndpoint): number;
+export declare function extractOperationEndpoints(paths: Paths, components?: Components): Array<OperationEndpoint>;
+/**
+ * Extracts all operations from a path item.
+ * @param pathItem - The OpenAPI path item
+ * @returns Array of method-operation pairs
+ */
+export declare function extractOperations(pathItem: PathItem): MethodOperation[];
+/**
+ * Picks the status code of an operation's success response: `200`, else the
+ * lowest other 2xx code, else `2XX`.
+ *
+ * @param operation - The OpenAPI operation
+ * @returns The status code key, or undefined when no 2xx response is declared
+ */
+export declare function okResponseStatus(operation: Operation): string | undefined;
+/**
+ * Extracts the success response from an operation: `200`, else the lowest
+ * other 2xx response, else `2XX`.
+ * @param operation - The OpenAPI operation
+ * @param components - Optional components used to resolve response references
+ * @returns The success response or undefined if not found
+ */
+export declare function extractOkResponse(operation: Operation, components?: Components): Response | Reference | undefined;
+/**
+ * Extracts the JSON schema from the OK response of an operation.
+ * @param operation - The OpenAPI operation
+ * @param components - Optional components used to resolve response references
+ * @returns The JSON schema from the OK response or undefined if not found
+ */
+export declare function extractOperationOkResponseJsonSchema(operation: Operation, components?: Components): Schema | Reference | undefined;
+/**
+ * Extracts the parameters of an operation, references resolved, in document
+ * order.
+ * @param operation - The OpenAPI operation
+ * @param components - The OpenAPI components object used to resolve references
+ * @returns The parameters
+ */
+export declare function extractParameters(operation: Operation, components: Components): Parameter[];
+/**
+ * Extracts path parameters from an operation.
+ * @param operation - The OpenAPI operation to extract path parameters from
+ * @param components - The OpenAPI components object used to resolve references
+ * @returns Array of path parameters
+ */
+export declare function extractPathParameters(operation: Operation, components: Components): Parameter[];
+/**
+ * Orders path parameters as the path holds them, whatever order the document
+ * lists them in: `/cart/{id}/{customerId}` gives `id`, then `customerId`.
+ * A method takes them in this order, so a route that gains a variable keeps
+ * the arguments before it where they were. Parameters the path does not
+ * hold keep their order, after the others.
+ *
+ * @param path - The route, with `{name}` variables
+ * @param parameters - Its path parameters
+ * @returns A new array, sorted
+ */
+export declare function inPathOrder<P extends Pick<Parameter, 'name'>>(path: string, parameters: readonly P[]): P[];
+/**
+ * Resolves the type of a path parameter.
+ * @param parameter - The path parameter to resolve the type for
+ * @returns The resolved primitive type as a string, or the default path parameter type if the schema is missing,
+ *          is a reference, lacks a type, or the type is not primitive
+ */
+export declare function resolvePathParameterType(parameter: Parameter): string;

package/dist/openapi/references.d.cts

@@ -0,0 +1,28 @@
+import { Reference } from '@ahoo-wang/fetcher-openapi';
+export declare function isReference(schema: any): schema is Reference;
+/**
+ * Resolves a local JSON pointer (`#/components/schemas/Item`) in a document.
+ *
+ * @param document - The document the pointer points into
+ * @param ref - The `$ref` value, starting with `#`
+ * @returns The value it points at, or undefined when there is none
+ */
+export declare function resolveLocalPointer(document: unknown, ref: string): unknown;
+/**
+ * Finds every reference to a component (`#/components/...`) that points at
+ * nothing.
+ *
+ * A dangling schema reference would otherwise generate a type that names an
+ * undeclared model, and a dangling parameter reference would silently drop
+ * the parameter. Other references are left alone: a reference to another
+ * document is refused where it is read, with a request to bundle it, and a
+ * schema may carry JSON Schema `definitions` it references relative to
+ * itself (`#/definitions/...`), as Wow 8.11 writes its filter schema.
+ *
+ * @param document - The parsed OpenAPI document
+ * @returns Each dangling reference with the JSON path of the object holding it
+ */
+export declare function findDanglingReferences(document: unknown): {
+    ref: string;
+    location: string;
+}[];

package/dist/openapi/references.d.ts

@@ -0,0 +1,28 @@
+import { Reference } from '@ahoo-wang/fetcher-openapi';
+export declare function isReference(schema: any): schema is Reference;
+/**
+ * Resolves a local JSON pointer (`#/components/schemas/Item`) in a document.
+ *
+ * @param document - The document the pointer points into
+ * @param ref - The `$ref` value, starting with `#`
+ * @returns The value it points at, or undefined when there is none
+ */
+export declare function resolveLocalPointer(document: unknown, ref: string): unknown;
+/**
+ * Finds every reference to a component (`#/components/...`) that points at
+ * nothing.
+ *
+ * A dangling schema reference would otherwise generate a type that names an
+ * undeclared model, and a dangling parameter reference would silently drop
+ * the parameter. Other references are left alone: a reference to another
+ * document is refused where it is read, with a request to bundle it, and a
+ * schema may carry JSON Schema `definitions` it references relative to
+ * itself (`#/definitions/...`), as Wow 8.11 writes its filter schema.
+ *
+ * @param document - The parsed OpenAPI document
+ * @returns Each dangling reference with the JSON path of the object holding it
+ */
+export declare function findDanglingReferences(document: unknown): {
+    ref: string;
+    location: string;
+}[];

package/dist/openapi/responses.d.cts

@@ -0,0 +1,44 @@
+import { MediaType, Reference, Response, Schema } from '@ahoo-wang/fetcher-openapi';
+/** The media type of JSON. */
+export declare const APPLICATION_JSON = "application/json";
+/** The media type of a server-sent event stream. */
+export declare const TEXT_EVENT_STREAM = "text/event-stream";
+/**
+ * The media type part of a content type, without parameters and in lower
+ * case: `application/json;charset=UTF-8` → `application/json`.
+ */
+export declare function mediaTypeOf(contentType: string): string;
+/**
+ * Tells whether a content type carries JSON: `application/json`, or any
+ * `+json` type such as `application/hal+json` or `application/problem+json`,
+ * with or without parameters.
+ */
+export declare function isJsonContentType(contentType: string): boolean;
+/**
+ * Tells whether a content type is text other than an event stream.
+ */
+export declare function isTextContentType(contentType: string): boolean;
+/**
+ * Finds the entry of a content map that matches, preferring an exact key.
+ *
+ * @param content - The content map of a request body or a response
+ * @param exact - The content type to prefer as written
+ * @param matches - What else qualifies
+ * @returns The media type object, or undefined
+ */
+export declare function findMediaType(content: Record<string, MediaType> | undefined, exact: string, matches?: (contentType: string) => boolean): MediaType | undefined;
+export declare function extractResponseSchema(contentType: string, response?: Response | Reference): Schema | Reference | undefined;
+/**
+ * Extracts the JSON schema of a response: `application/json` or any `+json`
+ * type, with or without parameters.
+ * @param response - The response object or reference
+ * @returns The JSON schema from the response content or undefined if not found
+ */
+export declare function extractResponseJsonSchema(response?: Response | Reference): Schema | Reference | undefined;
+export declare function extractResponseEventStreamSchema(response?: Response | Reference): Schema | Reference | undefined;
+export declare function extractResponseWildcardSchema(response?: Response | Reference): Schema | Reference | undefined;
+/**
+ * Tells whether a response carries text other than an event stream, such as
+ * `text/plain`.
+ */
+export declare function hasTextResponse(response?: Response | Reference): boolean;

package/dist/openapi/responses.d.ts

@@ -0,0 +1,44 @@
+import { MediaType, Reference, Response, Schema } from '@ahoo-wang/fetcher-openapi';
+/** The media type of JSON. */
+export declare const APPLICATION_JSON = "application/json";
+/** The media type of a server-sent event stream. */
+export declare const TEXT_EVENT_STREAM = "text/event-stream";
+/**
+ * The media type part of a content type, without parameters and in lower
+ * case: `application/json;charset=UTF-8` → `application/json`.
+ */
+export declare function mediaTypeOf(contentType: string): string;
+/**
+ * Tells whether a content type carries JSON: `application/json`, or any
+ * `+json` type such as `application/hal+json` or `application/problem+json`,
+ * with or without parameters.
+ */
+export declare function isJsonContentType(contentType: string): boolean;
+/**
+ * Tells whether a content type is text other than an event stream.
+ */
+export declare function isTextContentType(contentType: string): boolean;
+/**
+ * Finds the entry of a content map that matches, preferring an exact key.
+ *
+ * @param content - The content map of a request body or a response
+ * @param exact - The content type to prefer as written
+ * @param matches - What else qualifies
+ * @returns The media type object, or undefined
+ */
+export declare function findMediaType(content: Record<string, MediaType> | undefined, exact: string, matches?: (contentType: string) => boolean): MediaType | undefined;
+export declare function extractResponseSchema(contentType: string, response?: Response | Reference): Schema | Reference | undefined;
+/**
+ * Extracts the JSON schema of a response: `application/json` or any `+json`
+ * type, with or without parameters.
+ * @param response - The response object or reference
+ * @returns The JSON schema from the response content or undefined if not found
+ */
+export declare function extractResponseJsonSchema(response?: Response | Reference): Schema | Reference | undefined;
+export declare function extractResponseEventStreamSchema(response?: Response | Reference): Schema | Reference | undefined;
+export declare function extractResponseWildcardSchema(response?: Response | Reference): Schema | Reference | undefined;
+/**
+ * Tells whether a response carries text other than an event stream, such as
+ * `text/plain`.
+ */
+export declare function hasTextResponse(response?: Response | Reference): boolean;

package/dist/openapi/schemas.d.cts

@@ -0,0 +1,112 @@
+import { Components, Reference, Schema, SchemaType } from '@ahoo-wang/fetcher-openapi';
+/**
+ * Checks if a schema type is primitive.
+ * @param type - The schema type to check
+ * @returns True if the type is primitive, false otherwise
+ */
+export declare function isPrimitive(type: SchemaType | SchemaType[]): boolean;
+export type EnumSchema = Schema & {
+    enum: any[];
+};
+/**
+ * Checks if a schema represents an enum.
+ * @param schema - The schema to check
+ * @returns True if the schema has an enum property, false otherwise
+ */
+export declare function isEnum(schema: Schema): schema is EnumSchema;
+export type EnumText = Record<string, string>;
+export declare function getEnumText(schema: EnumSchema): EnumText | undefined;
+export type ObjectSchema = Schema & {
+    type: 'object';
+    properties: Record<string, Schema | Reference>;
+};
+export declare function isObject(schema: Schema): schema is ObjectSchema;
+export type ArraySchema = Schema & {
+    type: 'array';
+    items: Schema | Reference;
+};
+/**
+ * Checks if a schema is an array type.
+ * @param schema - The schema to check
+ * @returns True if the schema is an array type, false otherwise
+ */
+export declare function isArray(schema: Schema): schema is ArraySchema;
+export type AnyOfSchema = Schema & {
+    anyOf: any[];
+};
+/**
+ * Checks if a schema is an anyOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty anyOf property, false otherwise
+ */
+export declare function isAnyOf(schema: Schema): schema is AnyOfSchema;
+export type OneOfSchema = Schema & {
+    oneOf: any[];
+};
+/**
+ * Checks if a schema is a oneOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty oneOf property, false otherwise
+ */
+export declare function isOneOf(schema: Schema): schema is OneOfSchema;
+export type AllOfSchema = Schema & {
+    allOf: any[];
+};
+/**
+ * Checks if a schema is an allOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty allOf property, false otherwise
+ */
+export declare function isAllOf(schema: Schema): schema is AllOfSchema;
+export type CompositionSchema = AnyOfSchema | OneOfSchema | AllOfSchema;
+/**
+ * Checks if a schema is a composition (anyOf, oneOf, or allOf).
+ * @param schema - The schema to check
+ * @returns True if the schema is anyOf, oneOf, or allOf composition, false otherwise
+ */
+export declare function isComposition(schema: Schema): schema is CompositionSchema;
+/**
+ * Converts a type string to an array type.
+ * Wraps complex types (containing | or &) in parentheses before adding array notation.
+ * @param type - The type string to convert to an array type
+ * @returns The array type string
+ */
+export declare function toArrayType(type: string): string;
+export type MapSchema = Schema & {
+    type: 'object';
+    additionalProperties: boolean | Schema | Reference;
+};
+export declare function isMap(schema: Schema): schema is MapSchema;
+export declare function getMapKeySchema(schema: Schema): Schema | Reference | undefined;
+/**
+ * Checks if a schema represents an empty object.
+ * @param schema - The schema to check
+ * @returns True if the schema represents an empty object, false otherwise
+ */
+export declare function isEmptyObject(schema: Schema): boolean;
+export declare function isReadOnly(schema: Schema | Reference): boolean;
+/**
+ * Resolves a schema type to its TypeScript equivalent.
+ * @param type - The schema type(s) to resolve
+ * @returns The TypeScript type string
+ */
+export declare function resolvePrimitiveType(type: SchemaType | SchemaType[]): string;
+/**
+ * Lists the property names a command body may omit.
+ *
+ * A command type wraps its body in `PartialBy<Command, ...>` built from this
+ * list, which is where a request's declared optionality lives: generated model
+ * properties are always required. The walk follows `allOf` branches and
+ * references, because a command that inherits a base schema declares its
+ * properties there - reading only the top level would demand fields the
+ * document leaves optional.
+ *
+ * A property is optional when no branch requires it. `anyOf` and `oneOf` are
+ * not followed: a branch an instance need not match says nothing about the
+ * properties a command carries.
+ *
+ * @param schema - The command body schema, or a reference to it
+ * @param components - The components a reference resolves against
+ * @returns The declared property names absent from every `required` list
+ */
+export declare function resolveOptionalFields(schema: Schema | Reference, components?: Components): string[];

package/dist/openapi/schemas.d.ts

@@ -0,0 +1,112 @@
+import { Components, Reference, Schema, SchemaType } from '@ahoo-wang/fetcher-openapi';
+/**
+ * Checks if a schema type is primitive.
+ * @param type - The schema type to check
+ * @returns True if the type is primitive, false otherwise
+ */
+export declare function isPrimitive(type: SchemaType | SchemaType[]): boolean;
+export type EnumSchema = Schema & {
+    enum: any[];
+};
+/**
+ * Checks if a schema represents an enum.
+ * @param schema - The schema to check
+ * @returns True if the schema has an enum property, false otherwise
+ */
+export declare function isEnum(schema: Schema): schema is EnumSchema;
+export type EnumText = Record<string, string>;
+export declare function getEnumText(schema: EnumSchema): EnumText | undefined;
+export type ObjectSchema = Schema & {
+    type: 'object';
+    properties: Record<string, Schema | Reference>;
+};
+export declare function isObject(schema: Schema): schema is ObjectSchema;
+export type ArraySchema = Schema & {
+    type: 'array';
+    items: Schema | Reference;
+};
+/**
+ * Checks if a schema is an array type.
+ * @param schema - The schema to check
+ * @returns True if the schema is an array type, false otherwise
+ */
+export declare function isArray(schema: Schema): schema is ArraySchema;
+export type AnyOfSchema = Schema & {
+    anyOf: any[];
+};
+/**
+ * Checks if a schema is an anyOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty anyOf property, false otherwise
+ */
+export declare function isAnyOf(schema: Schema): schema is AnyOfSchema;
+export type OneOfSchema = Schema & {
+    oneOf: any[];
+};
+/**
+ * Checks if a schema is a oneOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty oneOf property, false otherwise
+ */
+export declare function isOneOf(schema: Schema): schema is OneOfSchema;
+export type AllOfSchema = Schema & {
+    allOf: any[];
+};
+/**
+ * Checks if a schema is an allOf composition.
+ * @param schema - The schema to check
+ * @returns True if the schema has a non-empty allOf property, false otherwise
+ */
+export declare function isAllOf(schema: Schema): schema is AllOfSchema;
+export type CompositionSchema = AnyOfSchema | OneOfSchema | AllOfSchema;
+/**
+ * Checks if a schema is a composition (anyOf, oneOf, or allOf).
+ * @param schema - The schema to check
+ * @returns True if the schema is anyOf, oneOf, or allOf composition, false otherwise
+ */
+export declare function isComposition(schema: Schema): schema is CompositionSchema;
+/**
+ * Converts a type string to an array type.
+ * Wraps complex types (containing | or &) in parentheses before adding array notation.
+ * @param type - The type string to convert to an array type
+ * @returns The array type string
+ */
+export declare function toArrayType(type: string): string;
+export type MapSchema = Schema & {
+    type: 'object';
+    additionalProperties: boolean | Schema | Reference;
+};
+export declare function isMap(schema: Schema): schema is MapSchema;
+export declare function getMapKeySchema(schema: Schema): Schema | Reference | undefined;
+/**
+ * Checks if a schema represents an empty object.
+ * @param schema - The schema to check
+ * @returns True if the schema represents an empty object, false otherwise
+ */
+export declare function isEmptyObject(schema: Schema): boolean;
+export declare function isReadOnly(schema: Schema | Reference): boolean;
+/**
+ * Resolves a schema type to its TypeScript equivalent.
+ * @param type - The schema type(s) to resolve
+ * @returns The TypeScript type string
+ */
+export declare function resolvePrimitiveType(type: SchemaType | SchemaType[]): string;
+/**
+ * Lists the property names a command body may omit.
+ *
+ * A command type wraps its body in `PartialBy<Command, ...>` built from this
+ * list, which is where a request's declared optionality lives: generated model
+ * properties are always required. The walk follows `allOf` branches and
+ * references, because a command that inherits a base schema declares its
+ * properties there - reading only the top level would demand fields the
+ * document leaves optional.
+ *
+ * A property is optional when no branch requires it. `anyOf` and `oneOf` are
+ * not followed: a branch an instance need not match says nothing about the
+ * properties a command carries.
+ *
+ * @param schema - The command body schema, or a reference to it
+ * @param components - The components a reference resolves against
+ * @returns The declared property names absent from every `required` list
+ */
+export declare function resolveOptionalFields(schema: Schema | Reference, components?: Components): string[];

package/dist/output/outputStore.d.cts

@@ -0,0 +1,92 @@
+import { Project, SourceFile } from 'ts-morph';
+/** The manifest that records the files a generation wrote, and their hashes. */
+export declare const GENERATION_MANIFEST = ".wow-generator.json";
+export declare const LEGACY_GENERATION_MANIFEST = ".fetcher-generator.json";
+/**
+ * The version of the manifest format this generator reads and writes. A
+ * change a reader of this version would misread bumps it; see section 3 of
+ * docs/design/architecture.md.
+ */
+export declare const MANIFEST_VERSION = 1;
+/**
+ * The output directory of one generation: which files it owns, which of the
+ * files an earlier run wrote it may remove, and writing them.
+ *
+ * The manifest (`.wow-generator.json`) records every file a run wrote and
+ * the hash it wrote. A file of the last run that this run does not write is
+ * stale; it is removed only if its bytes are still the ones recorded, so a
+ * hand-edited file is never lost. A file the manifest does not name is never
+ * touched.
+ *
+ * One store per run: {@link open} reads the manifest, {@link claim} hands
+ * out the files the run writes, {@link commit} writes them, removes the stale
+ * ones and writes the new manifest.
+ */
+export declare class OutputStore {
+    private readonly project;
+    /** The output directory as the caller named it. */
+    private readonly outputPath;
+    /** The output directory, absolute. */
+    private readonly outputDir;
+    /** The files of the last run, with the hash each was written with. */
+    private readonly previous;
+    /** A pre-Wow manifest to delete once the new one is written. */
+    private readonly legacyManifest;
+    /** The files this run writes, by absolute path. */
+    private readonly written;
+    /** Files of the last run this run does not write and may remove. */
+    private readonly stale;
+    private constructor();
+    /**
+     * Reads the manifest of an output directory, the pre-Wow one when the new
+     * one is absent, and takes the files it names out of the project: a run
+     * writes its files afresh.
+     *
+     * @param project - The project the run writes into
+     * @param outputDir - The output directory, absolute or relative to the
+     * project's working directory
+     * @param last - The store of the last run into the same project, whose
+     * files, written or only drafted, leave the project too
+     * @throws GeneratorError (`output`) when the manifest cannot be parsed, was
+     * written by a newer generator, is not one, or names a file outside the
+     * output directory
+     */
+    static open(project: Project, outputDir: string, last?: OutputStore): OutputStore;
+    /** The files this run writes, by absolute path. */
+    get files(): ReadonlySet<string>;
+    /**
+     * The source file of a path under a directory of the output, claimed for
+     * this run: the first claim empties it, and {@link commit} writes it.
+     *
+     * @param filePath - The path, relative to `directory`
+     * @param directory - The output directory as the caller named it, or a
+     * directory under it
+     * @throws GeneratorError (`output`) when the path resolves outside it
+     */
+    claim(filePath: string, directory?: string): SourceFile;
+    /**
+     * Takes the files of the last run this run does not write out of the
+     * project, when they are still as that run wrote them, so the indexes do
+     * not export them; {@link commit} removes them. Nothing on disk changes.
+     */
+    forgetStale(): void;
+    /**
+     * Writes the files this run claimed, then removes the stale ones that are
+     * still as the last run wrote them, then writes the manifest and deletes a
+     * pre-Wow one. A stale file this run writes again under a name that
+     * differs only in case is removed before the writing instead.
+     *
+     * @param signal - Stops the run after the files are written: nothing is
+     * removed and the manifest stays the last run's, so an interrupted run
+     * never records files it did not finish
+     * @throws GeneratorError (`output`) when writing or removing a file fails;
+     * the signal's reason when it was aborted
+     */
+    commit(signal?: AbortSignal): Promise<void>;
+    /**
+     * Tells whether a file of the last run is still as it wrote it: present,
+     * inside the output directory once links are followed, and of the hash the
+     * manifest records.
+     */
+    private isUnchanged;
+}

package/dist/output/outputStore.d.ts

@@ -0,0 +1,92 @@
+import { Project, SourceFile } from 'ts-morph';
+/** The manifest that records the files a generation wrote, and their hashes. */
+export declare const GENERATION_MANIFEST = ".wow-generator.json";
+export declare const LEGACY_GENERATION_MANIFEST = ".fetcher-generator.json";
+/**
+ * The version of the manifest format this generator reads and writes. A
+ * change a reader of this version would misread bumps it; see section 3 of
+ * docs/design/architecture.md.
+ */
+export declare const MANIFEST_VERSION = 1;
+/**
+ * The output directory of one generation: which files it owns, which of the
+ * files an earlier run wrote it may remove, and writing them.
+ *
+ * The manifest (`.wow-generator.json`) records every file a run wrote and
+ * the hash it wrote. A file of the last run that this run does not write is
+ * stale; it is removed only if its bytes are still the ones recorded, so a
+ * hand-edited file is never lost. A file the manifest does not name is never
+ * touched.
+ *
+ * One store per run: {@link open} reads the manifest, {@link claim} hands
+ * out the files the run writes, {@link commit} writes them, removes the stale
+ * ones and writes the new manifest.
+ */
+export declare class OutputStore {
+    private readonly project;
+    /** The output directory as the caller named it. */
+    private readonly outputPath;
+    /** The output directory, absolute. */
+    private readonly outputDir;
+    /** The files of the last run, with the hash each was written with. */
+    private readonly previous;
+    /** A pre-Wow manifest to delete once the new one is written. */
+    private readonly legacyManifest;
+    /** The files this run writes, by absolute path. */
+    private readonly written;
+    /** Files of the last run this run does not write and may remove. */
+    private readonly stale;
+    private constructor();
+    /**
+     * Reads the manifest of an output directory, the pre-Wow one when the new
+     * one is absent, and takes the files it names out of the project: a run
+     * writes its files afresh.
+     *
+     * @param project - The project the run writes into
+     * @param outputDir - The output directory, absolute or relative to the
+     * project's working directory
+     * @param last - The store of the last run into the same project, whose
+     * files, written or only drafted, leave the project too
+     * @throws GeneratorError (`output`) when the manifest cannot be parsed, was
+     * written by a newer generator, is not one, or names a file outside the
+     * output directory
+     */
+    static open(project: Project, outputDir: string, last?: OutputStore): OutputStore;
+    /** The files this run writes, by absolute path. */
+    get files(): ReadonlySet<string>;
+    /**
+     * The source file of a path under a directory of the output, claimed for
+     * this run: the first claim empties it, and {@link commit} writes it.
+     *
+     * @param filePath - The path, relative to `directory`
+     * @param directory - The output directory as the caller named it, or a
+     * directory under it
+     * @throws GeneratorError (`output`) when the path resolves outside it
+     */
+    claim(filePath: string, directory?: string): SourceFile;
+    /**
+     * Takes the files of the last run this run does not write out of the
+     * project, when they are still as that run wrote them, so the indexes do
+     * not export them; {@link commit} removes them. Nothing on disk changes.
+     */
+    forgetStale(): void;
+    /**
+     * Writes the files this run claimed, then removes the stale ones that are
+     * still as the last run wrote them, then writes the manifest and deletes a
+     * pre-Wow one. A stale file this run writes again under a name that
+     * differs only in case is removed before the writing instead.
+     *
+     * @param signal - Stops the run after the files are written: nothing is
+     * removed and the manifest stays the last run's, so an interrupted run
+     * never records files it did not finish
+     * @throws GeneratorError (`output`) when writing or removing a file fails;
+     * the signal's reason when it was aborted
+     */
+    commit(signal?: AbortSignal): Promise<void>;
+    /**
+     * Tells whether a file of the last run is still as it wrote it: present,
+     * inside the output directory once links are followed, and of the hash the
+     * manifest records.
+     */
+    private isUnchanged;
+}