openapi-typesafe 1.0.0-rc.4 → 1.0.0-rc.6

package/dist/index.d.mts

@@ -4,6 +4,22 @@ import { Config } from '@redocly/openapi-core';
 import * as TypeScript from 'typescript';
 import colors from 'ansi-colors';
 
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+interface Logger {
+    /**
+     * A debug line, with how long the step took when it was measured. A line without a group is
+     * written whenever debug output is on.
+     */
+    debug(message: string, group?: DebugGroup, durationMs?: number): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
@@ -268,6 +284,11 @@ declare const FIX: {
     readonly ARRAY_LENGTH_TUPLES: "array-length-tuples";
     /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
     readonly DEDUPE_ENUM_NAMES: "dedupe-enum-names";
+    /**
+     * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+     * by the words `parameters` and `requestBody` anywhere in a schema's location.
+     */
+    readonly DEFAULT_INPUT_LOCATIONS: "default-input-locations";
     /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
     readonly DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required";
     /**
@@ -280,8 +301,8 @@ declare const FIX: {
     readonly EXPLODED_QUERY_OBJECTS: "exploded-query-objects";
     /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
     readonly NULLABLE_ENUMS: "nullable-enums";
-    /** A parameter with `content` instead of `schema` is typed by the schema of its media type. */
-    readonly PARAMETER_CONTENT: "parameter-content";
+    /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+    readonly PARAMETER_HEADER_CONTENT: "parameter-header-content";
     /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
     readonly PATH_PARAM_TYPE_NAMES: "path-param-type-names";
     /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -1474,22 +1495,6 @@ declare const DEPRECATION_CODES: {
 };
 type DeprecationCode = (typeof DEPRECATION_CODES)[keyof typeof DEPRECATION_CODES];
 
-/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
-type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
-/**
- * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
- * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
- */
-interface Logger {
-    /**
-     * A debug line, with how long the step took when it was measured. A line without a group is
-     * written whenever debug output is on.
-     */
-    debug(message: string, group?: DebugGroup, durationMs?: number): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-
 /**
  * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
  * @param {string|URL|object|Readable} source OpenAPI schema source:
@@ -1498,6 +1503,8 @@ interface Logger {
  *   - URL: URL to a YAML or JSON file (local or remote)
  *   - Readable: Readable stream of YAML or JSON
  */
+declare function openapiTS(source: SchemaSource, options?: OpenAPITSOptions): Promise<IrDeclaration[]>;
+/** Convert an OpenAPI schema to IR declarations, with either form of the options. */
 declare function openapiTS(source: SchemaSource, options?: GeneratorOptions): Promise<IrDeclaration[]>;
 
 /**
@@ -1526,14 +1533,17 @@ declare const ERROR_CODES: {
     readonly ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY";
     readonly CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE";
     readonly OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN";
+    readonly OPTION_INVALID: "OPTION_INVALID";
     readonly TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND";
     readonly CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED";
+    readonly CLI_FLAG_INVALID: "CLI_FLAG_INVALID";
     readonly CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED";
     readonly CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND";
     readonly CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID";
     readonly CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING";
     readonly CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING";
     readonly CLI_INPUT_MISSING: "CLI_INPUT_MISSING";
+    readonly CLI_INPUT_EXTRA: "CLI_INPUT_EXTRA";
     readonly CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT";
     readonly CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE";
     readonly CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID";
@@ -1849,6 +1859,7 @@ declare function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclar
 /** Every warning code. */
 declare const WARNING_CODES: {
     readonly CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED";
+    readonly CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED";
     readonly CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN";
     readonly DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID";
     readonly DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED";

package/dist/index.d.ts

@@ -4,6 +4,22 @@ import { Config } from '@redocly/openapi-core';
 import * as TypeScript from 'typescript';
 import colors from 'ansi-colors';
 
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+interface Logger {
+    /**
+     * A debug line, with how long the step took when it was measured. A line without a group is
+     * written whenever debug output is on.
+     */
+    debug(message: string, group?: DebugGroup, durationMs?: number): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
@@ -268,6 +284,11 @@ declare const FIX: {
     readonly ARRAY_LENGTH_TUPLES: "array-length-tuples";
     /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
     readonly DEDUPE_ENUM_NAMES: "dedupe-enum-names";
+    /**
+     * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+     * by the words `parameters` and `requestBody` anywhere in a schema's location.
+     */
+    readonly DEFAULT_INPUT_LOCATIONS: "default-input-locations";
     /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
     readonly DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required";
     /**
@@ -280,8 +301,8 @@ declare const FIX: {
     readonly EXPLODED_QUERY_OBJECTS: "exploded-query-objects";
     /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
     readonly NULLABLE_ENUMS: "nullable-enums";
-    /** A parameter with `content` instead of `schema` is typed by the schema of its media type. */
-    readonly PARAMETER_CONTENT: "parameter-content";
+    /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+    readonly PARAMETER_HEADER_CONTENT: "parameter-header-content";
     /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
     readonly PATH_PARAM_TYPE_NAMES: "path-param-type-names";
     /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -1474,22 +1495,6 @@ declare const DEPRECATION_CODES: {
 };
 type DeprecationCode = (typeof DEPRECATION_CODES)[keyof typeof DEPRECATION_CODES];
 
-/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
-type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
-/**
- * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
- * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
- */
-interface Logger {
-    /**
-     * A debug line, with how long the step took when it was measured. A line without a group is
-     * written whenever debug output is on.
-     */
-    debug(message: string, group?: DebugGroup, durationMs?: number): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-
 /**
  * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
  * @param {string|URL|object|Readable} source OpenAPI schema source:
@@ -1498,6 +1503,8 @@ interface Logger {
  *   - URL: URL to a YAML or JSON file (local or remote)
  *   - Readable: Readable stream of YAML or JSON
  */
+declare function openapiTS(source: SchemaSource, options?: OpenAPITSOptions): Promise<IrDeclaration[]>;
+/** Convert an OpenAPI schema to IR declarations, with either form of the options. */
 declare function openapiTS(source: SchemaSource, options?: GeneratorOptions): Promise<IrDeclaration[]>;
 
 /**
@@ -1526,14 +1533,17 @@ declare const ERROR_CODES: {
     readonly ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY";
     readonly CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE";
     readonly OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN";
+    readonly OPTION_INVALID: "OPTION_INVALID";
     readonly TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND";
     readonly CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED";
+    readonly CLI_FLAG_INVALID: "CLI_FLAG_INVALID";
     readonly CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED";
     readonly CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND";
     readonly CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID";
     readonly CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING";
     readonly CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING";
     readonly CLI_INPUT_MISSING: "CLI_INPUT_MISSING";
+    readonly CLI_INPUT_EXTRA: "CLI_INPUT_EXTRA";
     readonly CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT";
     readonly CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE";
     readonly CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID";
@@ -1849,6 +1859,7 @@ declare function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclar
 /** Every warning code. */
 declare const WARNING_CODES: {
     readonly CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED";
+    readonly CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED";
     readonly CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN";
     readonly DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID";
     readonly DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-typesafe",
   "description": "Convert OpenAPI 3.0, 3.1 & 3.2 schemas to TypeScript",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "Fedor Chishchin",
     "url": "https://github.com/fedorello"

package/src/adapters/node-file-system/node-file-system.ts

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import type {
   ClaimedFile,
   DirectoryCheck,
+  FileCheck,
   FileClaims,
   FileIdentity,
   FileReader,
@@ -110,7 +111,9 @@ function typedWrite<T>(file: URL, step: () => T): T {
   }
 }
 
-class NodeFileSystem implements FileReader, FileWriter, FileIdentity, DirectoryCheck, FileClaims {
+class NodeFileSystem
+  implements FileReader, FileWriter, FileIdentity, DirectoryCheck, FileCheck, FileClaims
+{
   readText(file: URL): string {
     try {
       return fs.readFileSync(file, "utf8");
@@ -144,6 +147,15 @@ class NodeFileSystem implements FileReader, FileWriter, FileIdentity, DirectoryC
     }
   }
 
+  isFile(file: URL): boolean {
+    try {
+      return fs.statSync(file).isFile();
+    } catch {
+      // Missing or unreadable: no file; the read that follows reports a failure.
+      return false;
+    }
+  }
+
   isSameFile(left: URL, right: URL): boolean {
     const leftPath = fileURLToPath(left);
     const rightPath = fileURLToPath(right);
@@ -166,6 +178,7 @@ export function createNodeFileSystem(): FileReader &
   FileWriter &
   FileIdentity &
   DirectoryCheck &
+  FileCheck &
   FileClaims {
   return new NodeFileSystem();
 }

package/src/adapters/pipe-safe-writer/pipe-safe-writer.ts

@@ -0,0 +1,29 @@
+import type { Writable } from "node:stream";
+
+/**
+ * A writer for the CLI's stdout that stops when the reader closes the pipe (`| head`): the write
+ * fails with `EPIPE`, which Node raises as an unhandled `error` event and a crash with exit code
+ * 1. The reader has all it wanted, so the rest is dropped and the run ends as it would have.
+ * Every other write error is thrown again, as before.
+ */
+
+const BROKEN_PIPE = "EPIPE";
+
+function isBrokenPipe(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === BROKEN_PIPE;
+}
+
+/**
+ * The text writer of the stream. After `EPIPE` the stream is destroyed, so later writes are
+ * dropped by the stream itself and raise no second error.
+ */
+export function createPipeSafeWriter(stream: Writable): (text: string) => void {
+  stream.on("error", (error: Error) => {
+    if (!isBrokenPipe(error)) {
+      throw error;
+    }
+  });
+  return (text) => {
+    stream.write(text);
+  };
+}

package/src/adapters/redocly-loader/bundled-mapping-copies.ts

@@ -1,5 +1,6 @@
-import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
-import { findRefHolders } from "./ref-holders.js";
+import { childPointer } from "../../domain/openapi/json-pointer.js";
+import { type ComponentSchemas, componentSchemasOf, SCHEMAS_POINTER } from "./component-schemas.js";
+import { findMappings, findRefHolders } from "./ref-holders.js";
 
 /**
  * Redocly 1.x bundles every discriminator `mapping` value as if it were an external `$ref`: it
@@ -11,27 +12,13 @@ import { findRefHolders } from "./ref-holders.js";
  * and the mapping values and `$ref`s that name it point at the original.
  */
 
-type Schemas = Record<string, unknown>;
-
-const SCHEMAS_POINTER = childPointer(childPointer(ROOT_POINTER, "components"), "schemas");
-
-function isContainer(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function schemasOf(document: unknown): Schemas | undefined {
-  const components = isContainer(document) ? document.components : undefined;
-  const schemas = isContainer(components) ? components.schemas : undefined;
-  return isContainer(schemas) ? schemas : undefined;
-}
-
 /** The keys of `components.schemas` before bundling: the bundle edits the document in place. */
 export function schemaKeysOf(document: unknown): ReadonlySet<string> {
-  return new Set(Object.keys(schemasOf(document) ?? {}));
+  return new Set(Object.keys(componentSchemasOf(document) ?? {}));
 }
 
 /** Each key the bundle added as a copy, with the pointer of the schema it copies. */
-function copiesIn(schemas: Schemas, keysBefore: ReadonlySet<string>): Map<string, string> {
+function copiesIn(schemas: ComponentSchemas, keysBefore: ReadonlySet<string>): Map<string, string> {
   const originals = new Map<unknown, string>();
   for (const key of keysBefore) {
     if (Object.hasOwn(schemas, key) && !originals.has(schemas[key])) {
@@ -49,39 +36,17 @@ function copiesIn(schemas: Schemas, keysBefore: ReadonlySet<string>): Map<string
   return copies;
 }
 
-/** Every `discriminator.mapping` object of the document; the walk has its own stack. */
-function mappingsOf(document: unknown): Record<string, unknown>[] {
-  const mappings: Record<string, unknown>[] = [];
-  const visited = new WeakSet<object>();
-  const pending: unknown[] = [document];
-  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
-    if (!isContainer(next) || visited.has(next)) {
-      continue;
-    }
-    visited.add(next);
-    const mapping = isContainer(next.discriminator) ? next.discriminator.mapping : undefined;
-    if (isContainer(mapping)) {
-      mappings.push(mapping);
-    }
-    // One push per child: spreading an array of millions of children overflows the stack.
-    for (const child of Object.values(next)) {
-      pending.push(child);
-    }
-  }
-  return mappings;
-}
-
 /** Remove the bundle's copies of the document's own schemas, in place. */
 export function removeBundledMappingCopies(
   bundled: unknown,
   keysBefore: ReadonlySet<string>,
 ): void {
-  const schemas = schemasOf(bundled);
+  const schemas = componentSchemasOf(bundled);
   const copies = schemas === undefined ? new Map<string, string>() : copiesIn(schemas, keysBefore);
   if (copies.size === 0) {
     return;
   }
-  for (const mapping of mappingsOf(bundled)) {
+  for (const mapping of findMappings(bundled)) {
     for (const [name, value] of Object.entries(mapping)) {
       const original = typeof value === "string" ? copies.get(value) : undefined;
       if (original !== undefined) {

package/src/adapters/redocly-loader/component-schemas.ts

@@ -0,0 +1,19 @@
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
+
+/** `components.schemas` of a parsed document, which the loader repairs in place. */
+
+export type ComponentSchemas = Record<string, unknown>;
+
+/** `#/components/schemas`. */
+export const SCHEMAS_POINTER = childPointer(childPointer(ROOT_POINTER, "components"), "schemas");
+
+function isContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** The `components.schemas` object of a document, when it has one. */
+export function componentSchemasOf(document: unknown): ComponentSchemas | undefined {
+  const components = isContainer(document) ? document.components : undefined;
+  const schemas = isContainer(components) ? components.schemas : undefined;
+  return isContainer(schemas) ? schemas : undefined;
+}

package/src/adapters/redocly-loader/mapping-schema-names.ts

@@ -0,0 +1,25 @@
+import { childPointer } from "../../domain/openapi/json-pointer.js";
+import { componentSchemasOf, SCHEMAS_POINTER } from "./component-schemas.js";
+import { findMappings } from "./ref-holders.js";
+
+/**
+ * A discriminator `mapping` value may be a schema name (`cat: Cat`) or a URI reference. Redocly
+ * reads every value as a `$ref`, so a name failed with "Can't resolve $ref". OpenAPI 3.1.1
+ * (§4.8.25) leaves a value that is both to the implementation and recommends the schema name; a
+ * relative URI is then written `./Cat`. So a value that is a key of the document's
+ * `components.schemas` becomes the pointer to that schema, in place, before the `$ref`s are
+ * resolved. Any other value stays a URI reference.
+ */
+export function pointMappingNamesAtSchemas(document: unknown): void {
+  const schemas = componentSchemasOf(document);
+  if (schemas === undefined) {
+    return;
+  }
+  for (const mapping of findMappings(document)) {
+    for (const [name, value] of Object.entries(mapping)) {
+      if (typeof value === "string" && Object.hasOwn(schemas, value)) {
+        mapping[name] = childPointer(SCHEMAS_POINTER, value);
+      }
+    }
+  }
+}

package/src/adapters/redocly-loader/query-document-names.ts

@@ -0,0 +1,79 @@
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/**
+ * Which loaded document with a query each node comes from, and the names Redocly and the loader
+ * give that document. Redocly names a component after the text behind the last `/` of the URL,
+ * query included, so `pet.json?ref=feature/new-api` and `owner.yaml?ref=feature/new-api` both give
+ * `new-api`: the name alone cannot tell the documents apart, the node can.
+ */
+
+const REMOTE_URL_RE = /^https?:\/\//;
+const PATH_SEPARATOR_RE = /[/\\]/;
+const EXTENSION_RE = /\.[^.]+$/;
+
+/** The base name Redocly gives a document and the one without the query. */
+export interface DocumentNames {
+  readonly named: string;
+  readonly clean: string;
+}
+
+/** The base name Redocly 1.34 gives a document (`refBaseName`): the last segment, no extension. */
+function redoclyBaseName(ref: string): string {
+  return (ref.split(PATH_SEPARATOR_RE).at(-1) ?? "").replace(EXTENSION_RE, "");
+}
+
+/**
+ * The base name of the URL without its query and fragment. A URL with no last segment
+ * (`https://host/?key=…`) is named after its host, so the name is never empty.
+ */
+function queryFreeBaseName(url: URL): string {
+  const withoutQuery = new URL(url.pathname, url.origin).href;
+  return redoclyBaseName(withoutQuery) || url.hostname;
+}
+
+/** The names of a remote document with a query whose Redocly name keeps it; else undefined. */
+function documentNamesOf(ref: string): DocumentNames | undefined {
+  const url = REMOTE_URL_RE.test(ref) && URL.canParse(ref) ? new URL(ref) : undefined;
+  if (url === undefined || url.search === "") {
+    return undefined;
+  }
+  const names = { named: redoclyBaseName(ref), clean: queryFreeBaseName(url) };
+  return names.named === names.clean ? undefined : names;
+}
+
+function isNode(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** Every object and array of a parsed document, each once (a YAML alias can repeat one). */
+function nodesOf(parsed: unknown): object[] {
+  const visited = new Set<object>();
+  const pending = isNode(parsed) ? [parsed] : [];
+  for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+    if (!visited.has(node)) {
+      visited.add(node);
+      pending.push(...Object.values(node).filter(isNode));
+    }
+  }
+  return [...visited];
+}
+
+/**
+ * The names of the document each node of a loaded document with a query belongs to. The bundle
+ * keeps the nodes of the loaded documents as its components, so a component finds its document.
+ */
+export function queryDocumentNames(
+  documents: readonly LoadedDocument[],
+): ReadonlyMap<object, DocumentNames> {
+  const byNode = new Map<object, DocumentNames>();
+  for (const { source, parsed } of documents) {
+    const names = documentNamesOf(source);
+    if (names === undefined) {
+      continue;
+    }
+    for (const node of nodesOf(parsed)) {
+      byNode.set(node, names);
+    }
+  }
+  return byNode;
+}