openapi-typesafe 1.0.0-rc.0 → 1.0.0-rc.1

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

@@ -14,18 +14,26 @@ import {
   pathItemOperations,
 } from "../../../domain/openapi/path-item-object.js";
 import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
+import { type DeclaredTypeLookup, NO_DECLARED_TYPES } from "./declared-types.js";
 import { documentMember } from "./document-member.js";
 import { pathItemType } from "./path-item.js";
-import { isCoveredPathItemRejected } from "./path-item-conflicts.js";
 import {
+  type CoverRejection,
   coveringTemplateKeys,
   type PathKey,
   type PathKeyPart,
   type PathPlaceholder,
 } from "./path-key-overlaps.js";
+import {
+  type PathParameterMatch,
+  placeholderText,
+  replacedTemplateParts,
+} from "./path-template-replace.js";
+import { assignabilityProof } from "./type-assignability.js";
 
 const PATH_PARAMETER_RE = /\{[^}]+\}/g;
 
@@ -37,11 +45,6 @@ const PLACEHOLDERS: ReadonlyMap<unknown, PathPlaceholder> = new Map([
 ]);
 const STRING_PLACEHOLDER: PathPlaceholder = "string";
 
-/** `${type}`: the text of a template literal type placeholder. */
-function placeholderText(type: PathPlaceholder): string {
-  return `\${${type}}`;
-}
-
 function resolvedParameter(
   parameter: ParameterOrReference,
   context: TransformContext,
@@ -80,29 +83,37 @@ function pathParameters(
   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. Null when the URL has no complete `{…}` placeholder.
+ * 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.
  */
 function pathTemplateParts(
   url: string,
   pathItem: PathItemObject,
   context: TransformContext,
 ): PathKeyPart[] | null {
-  const matches = url.match(PATH_PARAMETER_RE);
-  if (!matches) {
+  const found = url.match(PATH_PARAMETER_RE);
+  if (!found) {
     return null;
   }
   const parameters = pathParameters(pathItem, context);
-  const placeholders = matches.map((match) => {
+  const matches = found.map((match): PathParameterMatch => {
     const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
-    return PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER;
-  });
-  return url.split(PATH_PARAMETER_RE).flatMap((text, index): PathKeyPart[] => {
-    const type = placeholders[index];
-    const textPart: PathKeyPart = { kind: "text", text };
-    return type === undefined ? [textPart] : [textPart, { kind: "placeholder", type }];
+    return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
   });
+  return context.options.fixes.has(OutputFix.PATH_PARAM_TYPE_NAMES)
+    ? splitTemplateParts(url, matches)
+    : replacedTemplateParts(url, matches);
 }
 
 /**
@@ -120,7 +131,8 @@ function templateText(parts: readonly PathKeyPart[]): string {
 }
 
 /** A path's member, its key and its path item type for the overlap check. */
-interface PathMember {
+export interface PathMember {
+  readonly url: string;
   readonly member: IrMember;
   readonly key: PathKey;
   readonly type: IrType;
@@ -139,7 +151,7 @@ function pathItemMember(
       : null;
   if (parts === null) {
     const member = irProperty(toPropertyName(url), type, { isReadonly });
-    return { member, key: literalKey(url), type };
+    return { url, member, key: literalKey(url), type };
   }
   const member: IrMember = {
     kind: "indexSignature",
@@ -149,33 +161,75 @@ function pathItemMember(
     isReadonly,
     comments: [],
   };
-  return { member, key: { kind: "template", parts }, type };
+  return { url, member, key: { kind: "template", parts }, type };
 }
 
 function literalKey(url: string): PathKey {
   return { kind: "literal", url };
 }
 
+const PATHS_TYPE_NAME = "paths";
+
+/** The URL of `paths["/apps/{id}"]`, or null for any other type. */
+function pathsIndexOf(type: IrType): string | null {
+  if (type.kind !== "indexedAccess" || type.index.kind !== "stringLiteral") {
+    return null;
+  }
+  const { object } = type;
+  const isPaths =
+    object.kind === "reference" &&
+    object.name === PATHS_TYPE_NAME &&
+    object.typeArguments.length === 0;
+  return isPaths ? type.index.value : null;
+}
+
+/**
+ * The lookup, and `paths["/apps/{id}"]` as that path's item. The declarations cannot read it: a
+ * templated path is no property of `paths`, and TypeScript finds it through the signature.
+ */
+function withPathItems(
+  paths: readonly PathMember[],
+  lookup: DeclaredTypeLookup,
+): DeclaredTypeLookup {
+  const byUrl = new Map(paths.map((path) => [path.url, path.type]));
+  return (type) => {
+    const url = pathsIndexOf(type);
+    return (url === null ? undefined : byUrl.get(url)) ?? lookup(type);
+  };
+}
+
+/**
+ * The rejection of a covered path item: only one proven not assignable to the signature's type
+ * counts (ADR-028). A pair the proof cannot decide keeps the original output, which may well
+ * compile (`Record<string, never>` fits `{ [key: string]: unknown }`).
+ */
+function rejectionOf(paths: readonly PathMember[], lookup: DeclaredTypeLookup): CoverRejection {
+  const relate = assignabilityProof(withPathItems(paths, lookup));
+  return (coveringIndex, coveredIndex) => {
+    const coveringPath = paths[coveringIndex];
+    const coveredPath = paths[coveredIndex];
+    return (
+      coveringPath !== undefined &&
+      coveredPath !== undefined &&
+      relate(coveredPath.type, coveringPath.type) === "rejected"
+    );
+  };
+}
+
 /**
  * The members as one object type. When an index signature covers another key, TypeScript checks
  * the covered key's type against it. Where that check surely fails (TS2411, TS2413), each such
  * signature gets an object of its own in an intersection: an intersection does not check its parts
  * against each other, and every key has the type it had in the one object. Output that compiles
- * keeps the one object.
+ * keeps the one object. The lookup reads the types that path items reference; without it, a
+ * reference decides nothing.
  */
-function pathsObjectType(paths: readonly PathMember[]): IrType {
-  const covering = coveringTemplateKeys(
-    paths.map(({ key }) => key),
-    (coveringIndex, coveredIndex) => {
-      const coveringPath = paths[coveringIndex];
-      const coveredPath = paths[coveredIndex];
-      return (
-        coveringPath !== undefined &&
-        coveredPath !== undefined &&
-        isCoveredPathItemRejected(coveredPath.type, coveringPath.type)
-      );
-    },
-  );
+export function pathsObjectType(
+  paths: readonly PathMember[],
+  lookup: DeclaredTypeLookup = NO_DECLARED_TYPES,
+): IrType {
+  const keys = paths.map(({ key }) => key);
+  const covering = coveringTemplateKeys(keys, rejectionOf(paths, lookup));
   if (covering.size === 0) {
     return irObject(paths.map(({ member }) => member));
   }
@@ -186,8 +240,8 @@ function pathsObjectType(paths: readonly PathMember[]): IrType {
   return irIntersection([irObject(rest), ...own]);
 }
 
-/** The `paths` interface body (OpenAPI 3.1 §4.8.8): one member per path, by URL. */
-export function pathsType(paths: PathsObject, context: TransformContext): IrType {
+/** The members of the `paths` interface (OpenAPI 3.1 §4.8.8): one per path, by URL. */
+export function pathMembers(paths: PathsObject, context: TransformContext): PathMember[] {
   const members: PathMember[] = [];
   for (const [url, pathItem] of documentEntries(paths, context.options)) {
     if (!pathItem || typeof pathItem !== "object") {
@@ -196,7 +250,7 @@ export function pathsType(paths: PathsObject, context: TransformContext): IrType
     if ("$ref" in pathItem) {
       const options = { isReadonly: context.options.immutable };
       const member = documentMember(url, refType(pathItem.$ref), pathItem, options);
-      members.push({ member, key: literalKey(url), type: member.type });
+      members.push({ url, member, key: literalKey(url), type: member.type });
       continue;
     }
     const startedAt = context.diagnostics.now();
@@ -207,5 +261,13 @@ export function pathsType(paths: PathsObject, context: TransformContext): IrType
       context.diagnostics.debug(`Transformed path "${url}"`, context.diagnostics.now() - startedAt);
     }
   }
-  return pathsObjectType(members);
+  return members;
+}
+
+/**
+ * The `paths` interface body, with only the path items' own types for the overlap check. The
+ * document transform checks the overlaps again once the referenced types are declared.
+ */
+export function pathsType(paths: PathsObject, context: TransformContext): IrType {
+  return pathsObjectType(pathMembers(paths, context));
 }

package/src/application/transform/document/root-type-aliases.ts

@@ -2,6 +2,7 @@ import { irRaw } from "../../../domain/ir/constructors.js";
 import type { IrDeclaration, IrTypeAliasDeclaration } from "../../../domain/ir/nodes.js";
 import { escapeSingleQuotedText } from "../../../domain/ir/raw-text-escapes.js";
 import type { ComponentKind } from "../../../domain/openapi/components-object.js";
+import { globalTypeReferences } from "./global-type-references.js";
 
 /** The `--root-types` aliases: `export type Pet = components['schemas']['Pet'];`. */
 
@@ -66,37 +67,37 @@ function freeName(name: string, taken: ReadonlySet<string>): string {
 }
 
 /**
- * With the `root-type-numbering` fix (ADR-021, roadmap R13, backlog 30): the aliases that a later
- * schema of one exported name took the name from, numbered `Name_2`, `Name_3`, … in document order
- * with the next free number. The later schema keeps the name, so the fix only adds exports.
+ * Rename each root alias whose name an enum or a helper type of the footer also declares, or that
+ * shadows a TypeScript global type the output refers to (`Record` in `Record<string, never>`), to
+ * the next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses for its own conflicts). The
+ * footer and the globals keep their names, because the generated types refer to them. Before, the
+ * output did not compile (enums: upstream #2099, #2341, #2206; helpers: a schema named
+ * `WithRequired`, roadmap R11; globals: TS2315). Other declarations are returned unchanged.
+ *
+ * With the `root-type-numbering` fix (ADR-021, roadmap R13, backlog 30) the body also holds the
+ * aliases a later schema of one exported name took the name from, after the other aliases and
+ * under that same name. Each gets the next free number in body order, after the alias that kept
+ * the name got its own: so the fix only adds exports, and every other alias keeps the name it has
+ * without the fix.
  */
-export function numberDisplacedAliases(
-  displaced: readonly IrTypeAliasDeclaration[],
-  kept: readonly IrTypeAliasDeclaration[],
-): IrTypeAliasDeclaration[] {
-  const taken = new Set(kept.map((alias) => alias.name));
-  return displaced.map((alias) => {
-    const name = freeName(alias.name, taken);
-    taken.add(name);
-    return { ...alias, name };
-  });
-}
-
-/**
- * Rename each root alias whose name an enum or a helper type of the footer also declares, to the
- * next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses for its own conflicts). The
- * footer keeps its names, because the generated types refer to them. Before, both were declared
- * under one name, which does not compile (enums: upstream #2099, #2341, #2206; helpers: a schema
- * named `WithRequired`, roadmap R11). Other declarations are returned unchanged.
- */
-export function renameAliasesTakenByFooter(
-  body: readonly IrDeclaration[],
+export function renameTakenAliases<T extends IrDeclaration>(
+  body: readonly T[],
   footer: readonly IrDeclaration[],
-): IrDeclaration[] {
-  const footerNames = footerTypeNames(footer);
-  const taken = declaredNames([...body, ...footer]);
+  closing: readonly IrDeclaration[] = [],
+): T[] {
+  const reserved = footerTypeNames(footer);
+  for (const name of globalTypeReferences([...body, ...footer, ...closing])) {
+    reserved.add(name);
+  }
+  const taken = declaredNames([...body, ...footer, ...closing]);
+  const aliasNames = new Set<string>();
   return body.map((declaration) => {
-    if (!isRootTypeAlias(declaration) || !footerNames.has(declaration.name)) {
+    if (!isRootTypeAlias(declaration)) {
+      return declaration;
+    }
+    const isRepeated = aliasNames.has(declaration.name);
+    aliasNames.add(declaration.name);
+    if (!isRepeated && !reserved.has(declaration.name)) {
       return declaration;
     }
     const name = freeName(declaration.name, taken);

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

@@ -0,0 +1,183 @@
+/**
+ * Whether a key type is assignable to a template literal key type, decided the way TypeScript's
+ * checker decides it (`inferFromLiteralPartsToTemplateLiteral` and
+ * `isValidTypeForTemplateLiteralPlaceholder` in TypeScript 5 and 6). An index signature checks
+ * exactly the keys that are assignable to its key type, so the overlap check must match the
+ * checker, not the strings a template stands for: the checker matches each text of the target at
+ * its first occurrence, so it misses some keys a regular expression would match, and a key it
+ * misses is never checked against the signature.
+ */
+
+/** A placeholder type of a template, after `${boolean}` became the texts `true` and `false`. */
+export type TemplatePlaceholder = "string" | "number";
+
+/**
+ * A key type as TypeScript stores a template literal: texts around placeholders, one more text
+ * than placeholders. A string literal is one text and no placeholder.
+ */
+export interface TemplateShape {
+  readonly texts: readonly string[];
+  readonly types: readonly TemplatePlaceholder[];
+}
+
+/** The text at an index of the shape; every caller passes one of `0 .. types.length`. */
+function textAt(shape: TemplateShape, index: number): string {
+  return shape.texts[index] as string;
+}
+
+/** The type the checker infers for one target placeholder: a text, or a slice of the source. */
+type InferredMatch =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "template"; readonly shape: TemplateShape };
+
+/** TypeScript's `isValidNumberString(text, false)`: a text that converts to a finite number. */
+export function isNumberText(text: string): boolean {
+  return text !== "" && Number.isFinite(Number(text));
+}
+
+/** Whether the inferred type fits a placeholder: any string for `string`, a number for `number`. */
+function isValidMatch(match: InferredMatch, placeholder: TemplatePlaceholder): boolean {
+  if (placeholder === "string") {
+    return true;
+  }
+  if (match.kind === "text") {
+    return isNumberText(match.text);
+  }
+  const { texts, types } = match.shape;
+  return texts.length === 2 && texts[0] === "" && texts[1] === "" && types[0] === "number";
+}
+
+/** The state of the scan through the source: the current text and the position in it. */
+interface Cursor {
+  readonly segment: number;
+  readonly position: number;
+}
+
+/** The scan of `inferFromLiteralPartsToTemplateLiteral`, over one source and one target. */
+class LiteralPartsScan {
+  private readonly matches: InferredMatch[] = [];
+  private cursor: Cursor;
+  private readonly source: TemplateShape;
+  private readonly lastSourceIndex: number;
+  private readonly remainingEndText: string;
+
+  constructor(source: TemplateShape, startPosition: number, endTextLength: number) {
+    this.source = source;
+    this.lastSourceIndex = source.texts.length - 1;
+    const endText = textAt(source, this.lastSourceIndex);
+    this.remainingEndText = endText.slice(0, endText.length - endTextLength);
+    this.cursor = { segment: 0, position: startPosition };
+  }
+
+  /** The matches for the target's texts between its first and last; null when one is missing. */
+  run(delimiters: readonly string[]): readonly InferredMatch[] | null {
+    for (const delimiter of delimiters) {
+      if (!this.matchDelimiter(delimiter)) {
+        return null;
+      }
+    }
+    this.addMatch(this.lastSourceIndex, this.sourceText(this.lastSourceIndex).length);
+    return this.matches;
+  }
+
+  private matchDelimiter(delimiter: string): boolean {
+    const { segment, position } = this.cursor;
+    if (delimiter.length > 0) {
+      const found = this.find(delimiter);
+      if (found === null) {
+        return false;
+      }
+      this.addMatch(found.segment, found.position);
+      this.cursor = { ...this.cursor, position: this.cursor.position + delimiter.length };
+      return true;
+    }
+    if (position < this.sourceText(segment).length) {
+      this.addMatch(segment, position + 1);
+      return true;
+    }
+    if (segment < this.lastSourceIndex) {
+      this.addMatch(segment + 1, 0);
+      return true;
+    }
+    return false;
+  }
+
+  /** The first occurrence of the delimiter at or after the cursor, in this or a later text. */
+  private find(delimiter: string): Cursor | null {
+    let { segment, position } = this.cursor;
+    while (segment < this.source.texts.length) {
+      const index = this.sourceText(segment).indexOf(delimiter, position);
+      if (index >= 0) {
+        return { segment, position: index };
+      }
+      segment += 1;
+      position = 0;
+    }
+    return null;
+  }
+
+  private sourceText(index: number): string {
+    return index < this.lastSourceIndex ? textAt(this.source, index) : this.remainingEndText;
+  }
+
+  private addMatch(segment: number, position: number): void {
+    const start = this.cursor;
+    if (segment === start.segment) {
+      const text = this.sourceText(segment).slice(start.position, position);
+      this.matches.push({ kind: "text", text });
+    } else {
+      const texts = [
+        textAt(this.source, start.segment).slice(start.position),
+        ...this.source.texts.slice(start.segment + 1, segment),
+        this.sourceText(segment).slice(0, position),
+      ];
+      const types = this.source.types.slice(start.segment, segment);
+      this.matches.push({ kind: "template", shape: { texts, types } });
+    }
+    this.cursor = { segment, position };
+  }
+}
+
+/** The checker's inferences for the target's placeholders; null when the texts do not fit. */
+function inferMatches(
+  source: TemplateShape,
+  target: TemplateShape,
+): readonly InferredMatch[] | null {
+  const sourceStart = textAt(source, 0);
+  const sourceEnd = textAt(source, source.texts.length - 1);
+  const targetStart = textAt(target, 0);
+  const targetEnd = textAt(target, target.texts.length - 1);
+  const isTooShort =
+    source.texts.length === 1 && sourceStart.length < targetStart.length + targetEnd.length;
+  if (isTooShort || !sourceStart.startsWith(targetStart) || !sourceEnd.endsWith(targetEnd)) {
+    return null;
+  }
+  const scan = new LiteralPartsScan(source, targetStart.length, targetEnd.length);
+  return scan.run(target.texts.slice(1, -1));
+}
+
+function haveSameTexts(source: TemplateShape, target: TemplateShape): boolean {
+  return (
+    source.texts.length === target.texts.length &&
+    source.texts.every((text, index) => text === target.texts[index])
+  );
+}
+
+/**
+ * Whether the source key type is assignable to the target template. Templates with the same texts
+ * compare placeholder by placeholder (`inferTypesFromTemplateLiteralType`).
+ */
+export function isAssignableToTemplate(source: TemplateShape, target: TemplateShape): boolean {
+  if (source.types.length > 0 && haveSameTexts(source, target)) {
+    return source.types.every((type, index) => {
+      const placeholder = target.types[index];
+      return placeholder === "string" || type === placeholder;
+    });
+  }
+  const matches = inferMatches(source, target);
+  const isEveryMatchValid = matches?.every((match, index) => {
+    const placeholder = target.types[index];
+    return placeholder !== undefined && isValidMatch(match, placeholder);
+  });
+  return isEveryMatchValid === true;
+}