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

package/src/api/transform-schema.ts

@@ -6,6 +6,10 @@ import {
   withEnumsRenamed,
 } from "../application/transform/document/enum-names-given-back.js";
 import { operationKeysWritten } from "../application/transform/document/operation-keys-written.js";
+import {
+  unmatchedTemplateKeys,
+  withTemplatePathRefs,
+} from "../application/transform/document/path-template-refs.js";
 import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
 import { RunFooter, type RunFooterNames } from "../application/transform/footer/document-footer.js";
 import { EnumNameClaims } from "../application/transform/footer/enum-name-claims.js";
@@ -144,6 +148,20 @@ function enumValuesChecked(
   return checked.footer;
 }
 
+/** The document with its references into templated paths indexed by their templates. */
+function withTemplateRefs(
+  { body, footer, closing }: TransformedDocument,
+  keys: ReadonlyMap<string, string>,
+): TransformedDocument {
+  return {
+    body: withTemplatePathRefs(body, keys),
+    footer: footer.map((entry) =>
+      isIrDeclaration(entry) ? (withTemplatePathRefs([entry], keys)[0] ?? entry) : entry,
+    ),
+    closing: withTemplatePathRefs(closing, keys),
+  };
+}
+
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
 export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
@@ -160,11 +178,8 @@ export function transformDocument(schema: OpenAPI3, ctx: RunContext): Transforme
   const rawClosing = documentClosing(document, context, rawFooter.some(isOperations));
   const parts = { body: rawBody, footer: rawFooter, closing: rawClosing };
   const { body, footer, closing } = withEnumNamesGivenBack(parts, names);
-  return {
-    body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing),
-    footer,
-    closing,
-  };
+  const named = { body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing), footer };
+  return withTemplateRefs({ ...named, closing }, unmatchedTemplateKeys(document.paths, context));
 }
 
 /**

package/src/application/ports/file-system.ts

@@ -29,6 +29,14 @@ export interface DirectoryCheck {
   isDirectory(file: URL): boolean;
 }
 
+/**
+ * Whether a `file:` location is an existing file. A schema argument with a `*` is a glob pattern
+ * only when no file has that name.
+ */
+export interface FileCheck {
+  isFile(file: URL): boolean;
+}
+
 /**
  * An output file that exists before its content is written: the claim created it, empty, when it
  * was missing, so the file system has given it its own identity.

package/src/application/ports/redocly-config-source.ts

@@ -17,4 +17,9 @@ export interface RedoclyConfigSource {
    * when the ignore file of the working directory is bad.
    */
   createDefault(): Promise<RedoclyConfig>;
+  /**
+   * The config one API of `config` is linted with: the API's own `rules` (and other lint
+   * settings) under `apis.<name>` in place of the root's, as `redocly lint <name>` reads them.
+   */
+  forApi(config: RedoclyConfig, apiName: string): RedoclyConfig;
 }

package/src/application/transform/declared-value-types.ts

@@ -0,0 +1,42 @@
+import { irKeyword, irReference } from "../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../domain/ir/nodes.js";
+import { HELPER_TYPES } from "./helper-types.js";
+import type { FooterDeclarations } from "./schema/schema-context.js";
+
+/** The footer part that declares the `PropertyValues` helper type. */
+export type PropertyValuesFooter = Pick<FooterDeclarations, "requirePropertyValues">;
+
+function memberValueTypes(member: IrMember): IrType[] {
+  if (member.kind === "indexSignature") {
+    return [member.type];
+  }
+  return member.isOptional ? [member.type, irKeyword("undefined")] : [member.type];
+}
+
+/**
+ * The value types a key of the type can have, read from its IR: the members of object types,
+ * through unions and intersections. A reference (a `$ref`, `Omit`, `WithRequired`) or a raw
+ * type is read with `PropertyValues`. Primitives, literals and arrays declare no keys.
+ */
+export function declaredValueTypes(type: IrType, footer: PropertyValuesFooter): IrType[] {
+  switch (type.kind) {
+    case "object":
+      return type.members.flatMap(memberValueTypes);
+    case "union":
+    case "intersection":
+      return type.types.flatMap((member) => declaredValueTypes(member, footer));
+    case "reference":
+    case "indexedAccess":
+    case "raw":
+      footer.requirePropertyValues();
+      return [irReference(HELPER_TYPES.propertyValues.name, [type])];
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "array":
+    case "tuple":
+    case "readonly":
+      return [];
+  }
+}

package/src/application/transform/document/document.ts

@@ -9,13 +9,14 @@ import type {
 } from "../../../domain/ir/nodes.js";
 import type { ComponentsObject } from "../../../domain/openapi/components-object.js";
 import type { DocumentObject } from "../../../domain/openapi/document-object.js";
-import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
+import type { OperationEntry, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { READ_WRITE_MARKER_TYPES } from "../helper-types.js";
 import type { TransformContext, TransformOptions } from "../transform-context.js";
 import { componentsType } from "./components.js";
 import { type DeclaredTypeLookup, declaredTypeLookup } from "./declared-types.js";
 import { defsRootType } from "./defs-root.js";
 import { keptDeprecatedComponents } from "./kept-deprecated.js";
+import { isIncludedOperation } from "./path-item.js";
 import { pathMembers, pathsObjectType } from "./paths.js";
 import { apiPathsEnumDeclaration } from "./paths-enum.js";
 import { webhooksType } from "./webhooks.js";
@@ -210,7 +211,8 @@ export function documentClosing(
     declarations.push(emptyAlias(OPERATIONS_NAME));
   }
   if (context.options.makePathsEnum && document.paths) {
-    declarations.push(apiPathsEnumDeclaration(document.paths));
+    const isIncluded = (operation: OperationEntry) => isIncludedOperation(operation, context);
+    declarations.push(apiPathsEnumDeclaration(document.paths, isIncluded));
   }
   return declarations;
 }

package/src/application/transform/document/exploded-query-values.ts

@@ -0,0 +1,88 @@
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import type { TransformContext } from "../transform-context.js";
+import { unionOf } from "../type-combinators.js";
+import type { ResolvedEntry } from "./parameter-entries.js";
+
+/**
+ * `exploded-query-objects` and index signatures. The keys of an exploded object are keys of
+ * `query`, next to the other parameters. TypeScript checks an index signature against every key
+ * of a value, so `{ page?: number } & { [key: string]: string }` admits no `page`, and no value
+ * with another parameter at all. An index signature of an exploded object therefore also takes
+ * the value types of the other keys of `query`: those keys carry their own values.
+ */
+
+function refOf(value: unknown): string | undefined {
+  const ref = (value as { $ref?: unknown } | undefined)?.$ref;
+  return typeof ref === "string" ? ref : undefined;
+}
+
+/** A schema `$ref` chain followed to its end, with the pointer where that schema is declared. */
+function declaredSchema(schema: Schema | undefined, ref: string, context: TransformContext) {
+  let declared = { schema, path: ref };
+  const seen = new Set<string>();
+  for (let next = refOf(schema); next !== undefined && !seen.has(next); ) {
+    seen.add(next);
+    declared = { schema: context.refs.resolve(next) as Schema | undefined, path: next };
+    next = refOf(declared.schema);
+  }
+  return declared;
+}
+
+/**
+ * The type of an exploded parameter whose own type is a reference (its `$ref`, or the `$ref` of
+ * its schema), written out where its schema is declared: the index signature of a referenced type
+ * cannot be changed. The location is the one `components` types it at, so the enums it declares
+ * are the ones the reference names. Null when no `$ref` is involved.
+ */
+export function declaredObjectType(entry: ResolvedEntry, context: TransformContext): IrType | null {
+  const { original, resolved } = entry;
+  const schemaRef = refOf(resolved.schema);
+  if (schemaRef !== undefined) {
+    const { schema, path } = declaredSchema(resolved.schema, schemaRef, context);
+    return transformSchema(schema, { path, schema }, context);
+  }
+  const parameterRef = refOf(original);
+  return parameterRef === undefined
+    ? null
+    : transformSchema(resolved.schema, { path: parameterRef, schema: resolved }, context);
+}
+
+function isIndexSignature(member: IrMember): boolean {
+  return member.kind === "indexSignature";
+}
+
+/** Whether the type has an index signature in its objects, through unions and intersections. */
+export function hasIndexSignature(type: IrType): boolean {
+  switch (type.kind) {
+    case "object":
+      return type.members.some(isIndexSignature);
+    case "union":
+    case "intersection":
+      return type.types.some(hasIndexSignature);
+    default:
+      return false;
+  }
+}
+
+function widenedMember(member: IrMember, values: readonly IrType[]): IrMember {
+  // `unknown` takes every value already.
+  const isUnknown = member.type.kind === "keyword" && member.type.keyword === "unknown";
+  return isIndexSignature(member) && !isUnknown
+    ? { ...member, type: unionOf([member.type, ...values]) }
+    : member;
+}
+
+/** The type with the values added to each index signature of its objects. */
+export function withIndexValues(type: IrType, values: readonly IrType[]): IrType {
+  switch (type.kind) {
+    case "object":
+      return { ...type, members: type.members.map((member) => widenedMember(member, values)) };
+    case "union":
+    case "intersection":
+      return { ...type, types: type.types.map((member) => withIndexValues(member, values)) };
+    default:
+      return type;
+  }
+}

package/src/application/transform/document/header.ts

@@ -2,6 +2,8 @@ import { irObject } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
 import type { HeaderObject } from "../../../domain/openapi/header-object.js";
 import { escapePointerSegment } from "../../../domain/openapi/json-pointer.js";
+import type { ContentMap } from "../../../domain/openapi/media-type-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { documentEntries } from "../document-entries.js";
 import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
@@ -10,8 +12,10 @@ import { documentMember } from "./document-member.js";
 import { contentEntryType } from "./media-type.js";
 
 /**
- * A header's type (OpenAPI 3.1 §4.8.21): its schema, else an object with one property per media
- * type in `content`, else `unknown`.
+ * A header's type (OpenAPI 3.1 §4.8.21): its schema, else the type of its `content`, else
+ * `unknown`. `content` holds one media type whose schema describes the value; the original typed
+ * it as an object with one property per media type, which the `parameter-header-content` fix
+ * replaces by the media type's type, as for a parameter.
  */
 export function headerType(
   header: HeaderObject,
@@ -24,11 +28,27 @@ export function headerType(
   if (!header.content) {
     return UNKNOWN_TYPE;
   }
+  if (context.options.fixes.has(FIX.PARAMETER_HEADER_CONTENT)) {
+    // The first media type in document order, as for a parameter: `--alphabetize` sorts only
+    // the members it writes.
+    const first = Object.entries(header.content)[0];
+    return first === undefined ? UNKNOWN_TYPE : mediaType(...first, location, context);
+  }
   const members = documentEntries(header.content, context.options).map(([contentType, entry]) => {
-    // Unlike other content maps, the original joins this path by hand: a missing path is `#`.
-    const path = `${location.path ?? "#"}/${escapePointerSegment(contentType)}`;
-    const type = contentEntryType(entry, { ...location, path }, context);
+    const type = mediaType(contentType, entry, location, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });
   return irObject(members);
 }
+
+/** The type of one media type of a header, at the path the original gave it. */
+function mediaType(
+  contentType: string,
+  entry: ContentMap[string],
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  // Unlike other content maps, the original joins this path by hand: a missing path is `#`.
+  const path = `${location.path ?? "#"}/${escapePointerSegment(contentType)}`;
+  return contentEntryType(entry, { ...location, path }, context);
+}

package/src/application/transform/document/parameter.ts

@@ -13,7 +13,7 @@ import { contentEntryType } from "./media-type.js";
 /**
  * A parameter typed by the schema of its one `content` media type. An `in: querystring` parameter
  * (OpenAPI 3.2) is the whole query string (ADR-020); without a media type it is `string`, the
- * query string as text. With the `parameter-content` fix, any other parameter with `content`
+ * query string as text. With the `parameter-header-content` fix, any other parameter with `content`
  * (OpenAPI 3.0 and later, for a JSON value in a query parameter) is typed the same way.
  */
 function contentParameterType(
@@ -34,14 +34,14 @@ function isTypedByContent(parameter: ParameterObject, context: SchemaContext): b
     return true;
   }
   const hasContent = parameter.schema === undefined && parameter.content !== undefined;
-  return hasContent && context.options.fixes.has(FIX.PARAMETER_CONTENT);
+  return hasContent && context.options.fixes.has(FIX.PARAMETER_HEADER_CONTENT);
 }
 
 /**
  * A parameter's type (OpenAPI 3.2 §4.8.12). Without a schema it is `string`, not `unknown`:
  * query, path, header and cookie values all arrive as text. `content` is read for
- * `in: querystring`, and with the `parameter-content` fix for every parameter; without the fix
- * other parameters with `content` keep the original's `string`.
+ * `in: querystring`, and with the `parameter-header-content` fix for every parameter; without
+ * the fix other parameters with `content` keep the original's `string`.
  */
 export function parameterType(
   parameter: ParameterObject,

package/src/application/transform/document/parameters.ts

@@ -16,10 +16,12 @@ import {
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
 import { FIX } from "../../../domain/output-fixes.js";
+import { declaredValueTypes } from "../declared-value-types.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { withSchemaComment } from "../schema-comment.js";
 import type { TransformContext } from "../transform-context.js";
 import { isExplodedQueryObject } from "./exploded-query.js";
+import { declaredObjectType, hasIndexSignature, withIndexValues } from "./exploded-query-values.js";
 import { parameterType } from "./parameter.js";
 import {
   type ParameterEntry,
@@ -126,17 +128,50 @@ function isExplodedEntry(entry: ResolvedEntry, context: TransformContext): boole
   );
 }
 
+/** An exploded object parameter with its type, typed in document order. */
+interface ExplodedEntry {
+  readonly entry: ResolvedEntry;
+  readonly type: IrType;
+}
+
 /**
- * An exploded object parameter's part of `query`: its object type. A parameter that may be left
- * out sends none of its keys then, so they are optional: `Partial<…>`.
+ * The object type of an exploded parameter, written out when it is a reference to a type with an
+ * index signature and `query` has other keys, which that signature must then admit. Without
+ * other keys the reference is kept.
  */
-function explodedPart(
-  entry: ResolvedEntry,
-  location: SchemaLocation,
+function explodedObjectType(
+  { entry, type }: ExplodedEntry,
+  hasOtherKeys: boolean,
   context: TransformContext,
 ): IrType {
-  const type = entryType(entry, location, context);
-  return entry.resolved.required ? type : irReference("Partial", [type]);
+  if (!hasOtherKeys) {
+    return type;
+  }
+  const declared = declaredObjectType(entry, context);
+  return declared !== null && hasIndexSignature(declared) ? declared : type;
+}
+
+/**
+ * The exploded object parameters' parts of `query`: their object types, each index signature
+ * widened by the value types of the other keys (see `exploded-query-values.ts`). A parameter that
+ * may be left out sends none of its keys then, so they are optional: `Partial<…>`.
+ */
+function explodedParts(
+  exploded: readonly ExplodedEntry[],
+  members: readonly IrPropertySignature[],
+  context: TransformContext,
+): IrType[] {
+  const hasOtherKeys = members.length > 0 || exploded.length > 1;
+  const types = exploded.map((part) => explodedObjectType(part, hasOtherKeys, context));
+  const others = (index: number) => [
+    ...(members.length > 0 ? [irObject(members)] : []),
+    ...types.filter((_type, other) => other !== index),
+  ];
+  return types.map((type, index) => {
+    const values = others(index).flatMap((other) => declaredValueTypes(other, context.footer));
+    const widened = withIndexValues(type, values);
+    return exploded[index]?.entry.resolved.required ? widened : irReference("Partial", [widened]);
+  });
 }
 
 /** A location's parameters as members, and the object types of its exploded parameters. */
@@ -153,11 +188,11 @@ function locationParts(
   context: TransformContext,
 ): LocationParts {
   const members: IrPropertySignature[] = [];
-  const exploded: IrType[] = [];
+  const exploded: ExplodedEntry[] = [];
   let isOptional = true;
   for (const entry of entries) {
     if (isExplodedEntry(entry, context)) {
-      exploded.push(explodedPart(entry, location, context));
+      exploded.push({ entry, type: entryType(entry, location, context) });
       isOptional &&= !entry.resolved.required;
       continue;
     }
@@ -165,7 +200,7 @@ function locationParts(
     members.push(member);
     isOptional &&= member.isOptional;
   }
-  return { members, exploded, isOptional };
+  return { members, exploded: explodedParts(exploded, members, context), isOptional };
 }
 
 /** The members' object, intersected with the exploded parameters' types; `never` for none. */

package/src/application/transform/document/path-item.ts

@@ -29,7 +29,7 @@ export function operationKeyOf(operationId: string): string {
 }
 
 /** Whether the method has an operation, not removed by `--exclude-deprecated`. */
-function isIncluded(
+export function isIncludedOperation(
   operation: OperationEntry | undefined,
   context: TransformContext,
 ): operation is OperationEntry {
@@ -94,7 +94,7 @@ function methodMember(
   context: TransformContext,
 ): IrPropertySignature {
   const operation = pathItem[method];
-  if (!isIncluded(operation, context)) {
+  if (!isIncludedOperation(operation, context)) {
     const isReadonly = context.options.immutable;
     return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
   }
@@ -113,7 +113,7 @@ function additionalOperationsMember(
 ): IrPropertySignature | null {
   const entries = documentEntries(pathItem.additionalOperations ?? {}, context.options);
   const members = entries
-    .filter(([, operation]) => isIncluded(operation, context))
+    .filter(([, operation]) => isIncludedOperation(operation, context))
     .map(([method, operation]) => {
       const path = appendPointer(location.path, [ADDITIONAL_OPERATIONS_KEY, method]);
       return operationMember({ name: method, operation, path }, pathItem, location, context);

package/src/application/transform/document/path-template-key.ts

@@ -0,0 +1,152 @@
+import { escapeTemplateText } from "../../../domain/ir/raw-text-escapes.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  type PathItemObject,
+  pathItemOperations,
+} from "../../../domain/openapi/path-item-object.js";
+import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
+import type { TransformContext } from "../transform-context.js";
+import type { PathKeyPart, PathPlaceholder } from "./path-key-overlaps.js";
+import {
+  type PathParameterMatch,
+  placeholderText,
+  replacedTemplateParts,
+} from "./path-template-replace.js";
+
+/** The `--path-params-as-types` key of a path: its URL with a placeholder per parameter. */
+
+/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
+const PATH_PARAMETER_RE = /\{[^{}]+\}/g;
+
+/** Placeholders by parameter schema type; anything else is a string placeholder. */
+const PLACEHOLDERS: ReadonlyMap<unknown, PathPlaceholder> = new Map([
+  ["number", "number"],
+  ["integer", "number"],
+  ["boolean", "boolean"],
+]);
+const STRING_PLACEHOLDER: PathPlaceholder = "string";
+
+function resolvedParameter(
+  parameter: ParameterOrReference,
+  context: TransformContext,
+): ParameterObject | undefined {
+  return "$ref" in parameter && parameter.$ref
+    ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
+    : (parameter as ParameterObject);
+}
+
+function addPathParameters(
+  parameters: readonly ParameterOrReference[],
+  byName: Map<string, ParameterObject>,
+  context: TransformContext,
+): void {
+  for (const parameter of parameters) {
+    const resolved = resolvedParameter(parameter, context);
+    if (resolved && resolved.in === "path") {
+      byName.set(resolved.name, resolved);
+    }
+  }
+}
+
+/** Path parameters of the path item and of its operations; later definitions win. */
+function pathParameters(
+  pathItem: PathItemObject,
+  context: TransformContext,
+): Map<string, ParameterObject> {
+  const byName = new Map<string, ParameterObject>();
+  addPathParameters(pathItem.parameters ?? [], byName, context);
+  for (const { operation: entry } of pathItemOperations(pathItem)) {
+    const operation = (entry as ReferenceSchema).$ref
+      ? (context.refs.resolve((entry as ReferenceSchema).$ref) as OperationObject | undefined)
+      : (entry as OperationObject);
+    addPathParameters(operation?.parameters ?? [], byName, context);
+  }
+  return byName;
+}
+
+/** Each `{name}` of the URL and its own placeholder, from the URL split at the matches. */
+function splitTemplateParts(url: string, matches: readonly PathParameterMatch[]): PathKeyPart[] {
+  return url.split(PATH_PARAMETER_RE).flatMap((text, index): PathKeyPart[] => {
+    const type = matches[index]?.type;
+    const textPart: PathKeyPart = { kind: "text", text };
+    return type === undefined ? [textPart] : [textPart, { kind: "placeholder", type }];
+  });
+}
+
+/**
+ * `--path-params-as-types`: the URL as template parts, each `{name}` replaced by a placeholder for
+ * its parameter's type, the way the original replaces them unless the `path-param-type-names` fix
+ * is on (see `replacedTemplateParts`). Null when the URL has no complete `{…}` placeholder.
+ */
+export function pathTemplateParts(
+  url: string,
+  pathItem: PathItemObject,
+  context: TransformContext,
+): PathKeyPart[] | null {
+  const found = url.match(PATH_PARAMETER_RE);
+  if (!found) {
+    return null;
+  }
+  const parameters = pathParameters(pathItem, context);
+  const matches = found.map((match): PathParameterMatch => {
+    const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
+    return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
+  });
+  return context.options.fixes.has(FIX.PATH_PARAM_TYPE_NAMES)
+    ? splitTemplateParts(url, matches)
+    : replacedTemplateParts(url, matches);
+}
+
+/**
+ * The template literal type of the parts. The original escaped only backticks: a backslash or
+ * `${` in the URL could end the literal or open a placeholder, and add code to the generated file
+ * (intentional fix). So the text parts are escaped.
+ */
+export function templateText(parts: readonly PathKeyPart[]): string {
+  const text = parts
+    .map((part) =>
+      part.kind === "text" ? escapeTemplateText(part.text) : placeholderText(part.type),
+    )
+    .join("");
+  return `\`${text}\``;
+}
+
+const BOOLEAN_TEXTS = ["true", "false"] as const;
+
+const isBooleanPlaceholder = (part: PathKeyPart): boolean =>
+  part.kind === "placeholder" && part.type === "boolean";
+
+/**
+ * The keys of a template whose only placeholders are `${boolean}`, with each written as `true`
+ * and as `false`. Such a template is a union of literals, and an index signature takes none
+ * (TS1337), so the original's `` [path: `/flags/${boolean}`] `` did not compile. A path with n
+ * boolean parameters gets 2ⁿ plain URLs (`/flags/true`), all with the same path item type. Next to
+ * another placeholder the template is a pattern, a valid signature that admits the same URLs, so
+ * those parts stay one key.
+ */
+export function booleanExpandedKeys(parts: readonly PathKeyPart[]): PathKeyPart[][] {
+  const isBooleanOnly = parts.every((part) => part.kind === "text" || isBooleanPlaceholder(part));
+  if (!isBooleanOnly) {
+    return [[...parts]];
+  }
+  return parts.reduce<PathKeyPart[][]>(
+    (keys, part) => {
+      const choices: readonly PathKeyPart[] = isBooleanPlaceholder(part)
+        ? BOOLEAN_TEXTS.map((text) => ({ kind: "text", text }))
+        : [part];
+      return keys.flatMap((key) => choices.map((choice) => [...key, choice]));
+    },
+    [[]],
+  );
+}
+
+/** The URL of parts without placeholders; null when one is left. */
+export function plainUrlOf(parts: readonly PathKeyPart[]): string | null {
+  const texts = parts.map((part) => (part.kind === "text" ? part.text : null));
+  return texts.includes(null) ? null : texts.join("");
+}