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

package/src/api/legacy-callback-warning.ts

@@ -1,5 +1,7 @@
-import type { GlobalContext, LegacyCallbackName } from "../types.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import type { LegacyCallbackName } from "../types.js";
 import { defaultLogger } from "./default-ports.js";
+import type { RunContext } from "./run-context.js";
 
 /** Where the IR callbacks are documented; the warning points users there. */
 export const IR_CALLBACKS_GUIDE_URL =
@@ -19,11 +21,13 @@ function message(name: LegacyCallbackName): string {
 }
 
 /** Warn once per run and callback; `silent` runs record the use but print nothing. */
-export function warnLegacyCallback(ctx: GlobalContext, name: LegacyCallbackName): void {
+export function warnLegacyCallback(ctx: RunContext, name: LegacyCallbackName): void {
   ctx.legacyCallbackWarnings ??= new Set();
   if (ctx.legacyCallbackWarnings.has(name)) {
     return;
   }
   ctx.legacyCallbackWarnings.add(name);
-  (ctx.logger ?? defaultLogger(ctx.silent)).warn(message(name));
+  (ctx.logger ?? defaultLogger(ctx.silent)).warn(
+    warningText(message(name), WARNING_CODES.LEGACY_CALLBACK_DEPRECATED),
+  );
 }

package/src/api/legacy-ts-helpers.ts

@@ -103,7 +103,7 @@ export function tsDedupe(types: TypeInput[]): ts.TypeNode[] {
 }
 
 /** @deprecated The generator keeps its own enum registry per run; kept for 1.x (ADR-004). */
-export const enumCache = new Map<string, ts.EnumDeclaration>();
+export const enumCache: Map<string, ts.EnumDeclaration> = new Map();
 
 /**
  * Create a TS enum (with sanitized name and members)
@@ -114,7 +114,7 @@ export function tsEnum(
   members: (string | number)[],
   metadata?: { name?: string; description?: string | null }[],
   options?: { export?: boolean; shouldCache?: boolean },
-) {
+): ts.EnumDeclaration {
   const ts = loadTypeScript();
   let enumName = sanitizeMemberName(name);
   enumName = `${enumName.charAt(0).toUpperCase()}${enumName.substring(1)}`;
@@ -149,7 +149,7 @@ export function tsArrayLiteralExpression(
   elementType: TypeInput,
   values: (string | number)[],
   options?: { export?: boolean; readonly?: boolean; injectFooter?: FooterEntry[] },
-) {
+): ts.VariableStatement {
   const ts = loadTypeScript();
   let variableName = sanitizeMemberName(name);
   variableName = `${variableName.charAt(0).toLowerCase()}${variableName.substring(1)}`;
@@ -223,7 +223,7 @@ function enumMemberName(value: string | number, explicitName: string | undefined
 export function tsEnumMember(
   value: string | number,
   metadata: { name?: string; description?: string | null } = {},
-) {
+): ts.EnumMember {
   const ts = loadTypeScript();
   const name = enumMemberName(value, metadata.name);
   const member = ts.factory.createEnumMember(name, toValueExpression(ts, value));
@@ -281,7 +281,9 @@ export function tsModifiers(modifiers: { readonly?: boolean; export?: boolean })
  * Create a valid property index
  * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
  */
-export function tsPropertyIndex(index: string | number) {
+export function tsPropertyIndex(
+  index: string | number,
+): ts.Identifier | ts.NumericLiteral | ts.StringLiteral {
   const ts = loadTypeScript();
   if (
     (typeof index === "number" && !(index < 0)) ||

package/src/api/legacy-utils.ts

@@ -90,7 +90,7 @@ export type { ResolveRefOptions } from "./document-refs.js";
  * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
  */
 export function resolveRef<T>(
-  schema: any,
+  schema: unknown,
   $ref: string,
   options: ResolveRefOptions,
 ): T | undefined {

package/src/api/openapi-ts.ts

@@ -3,6 +3,7 @@ import { withStackOverflowReported } from "../application/stack-overflow.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
 import {
+  DEFAULT_REMOTE_DOCUMENT_LIMITS,
   defaultLogger,
   defaultRedoclyConfig,
   monotonicNow,
@@ -42,6 +43,7 @@ export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<
     logger,
     now: monotonicNow,
     remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,
+    remoteDocumentLimits: DEFAULT_REMOTE_DOCUMENT_LIMITS,
   });
   return { loader, logger, redoc, now: monotonicNow };
 }

package/src/api/path-template-warnings.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "../application/ports/logger.js";
+import { findIdenticalPathTemplates } from "../domain/openapi/path-templates.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/cli.md#pathparamsastypes";
+const SPEC_RULE =
+  "OpenAPI does not allow this (Paths Object): templated paths with the same hierarchy but " +
+  "different templated names MUST NOT exist as they are identical";
+
+/** `"/a"`, `"/a" and "/b"`, `"/a", "/b" and "/c"`. */
+function quotedList(urls: readonly string[]): string {
+  const quoted = urls.map((url) => `"${url}"`);
+  const last = quoted.pop();
+  return quoted.length === 0 ? (last ?? "") : `${quoted.join(", ")} and ${last}`;
+}
+
+/**
+ * Warn once per group of paths that differ only in parameter names, which the spec forbids: a URL
+ * cannot tell them apart, and `--path-params-as-types` gives them the same key type.
+ */
+export function warnIdenticalPathTemplates(document: unknown, logger: Logger): void {
+  for (const urls of findIdenticalPathTemplates(document)) {
+    const message = `Paths ${quotedList(urls)} differ only in their parameter names. ${SPEC_RULE}`;
+    logger.warn(warningText(`${message}. See ${DOCS_URL}`, WARNING_CODES.PATH_TEMPLATES_IDENTICAL));
+  }
+}

package/src/api/run-context.ts

@@ -0,0 +1,34 @@
+import type { Logger } from "../application/ports/logger.js";
+import type { DocumentFooter } from "../application/transform/transform-context.js";
+import type { GlobalContext, LegacyCallbackName, SchemaObject } from "../types.js";
+
+/**
+ * The context the generator builds for a run: the public `GlobalContext` plus the run's own
+ * state. The state is not part of the public type, so it can change in a minor release; every
+ * field is optional, so a context a user builds by hand is a valid `RunContext` without it.
+ * Callbacks receive this object as `options.ctx` and may spread it; the state travels with it.
+ */
+export interface RunContext extends GlobalContext {
+  readonly discriminators: GlobalContext["discriminators"] & {
+    /**
+     * With the `discriminator-values` fix: for each enum the scan added to a member and each
+     * inherited discriminator object, the enum of the owner's property and the location it is
+     * typed at.
+     */
+    readonly enumParents?: ReadonlyMap<
+      object,
+      { readonly schema: SchemaObject; readonly path: string }
+    >;
+    /**
+     * With the `discriminator-values` fix: for each schema, the properties of the discriminators
+     * it inherits besides `objects[ref]`, which it redefines too.
+     */
+    readonly otherProperties?: Readonly<Record<string, readonly string[]>>;
+  };
+  /** Footer state of this run (enum registry and enum naming), created on first use. */
+  runFooter?: DocumentFooter;
+  /** The deprecated callback forms this run has warned about (once each). */
+  legacyCallbackWarnings?: Set<LegacyCallbackName>;
+  /** Where this run reports warnings and debug output; without it, the terminal. */
+  logger?: Logger;
+}

package/src/api/transform-context.ts

@@ -1,6 +1,9 @@
 import * as changeCase from "change-case";
 import { RunFooter } from "../application/transform/footer/document-footer.js";
-import type { SchemaLocation } from "../application/transform/schema/schema-context.js";
+import type {
+  DiscriminatorEnumParent,
+  SchemaLocation,
+} from "../application/transform/schema/schema-context.js";
 import type {
   DocumentFooter,
   NameCasing,
@@ -8,22 +11,24 @@ import type {
   TransformDiagnostics,
   TransformOptions,
 } from "../application/transform/transform-context.js";
-import type { GlobalContext, TransformNodeOptions } from "../types.js";
+import type { TransformNodeOptions } from "../types.js";
 import { defaultLogger, monotonicNow } from "./default-ports.js";
 import { ContextFooterSink } from "./footer-sink.js";
+import type { RunContext } from "./run-context.js";
 import { schemaCallbacks } from "./schema-callbacks.js";
 
 /**
- * Builds the ported transformers' context from the original `GlobalContext`: options, refs,
- * discriminators, the run footer and the user callbacks (see `schema-callbacks.ts`).
+ * Builds the ported transformers' context from the original `GlobalContext` (in a run, a
+ * `RunContext`): options, refs, discriminators, the run footer and the user callbacks (see
+ * `schema-callbacks.ts`).
  */
 
-function transformOptions(ctx: GlobalContext): TransformOptions {
+function transformOptions(ctx: RunContext): TransformOptions {
   return {
     additionalProperties: ctx.additionalProperties,
     alphabetize: ctx.alphabetize,
     arrayLength: ctx.arrayLength,
-    binaryAsBlob: ctx.binaryAsBlob,
+    binaryAsBlob: ctx.binaryAsBlob ?? false,
     conditionalEnums: ctx.conditionalEnums,
     dedupeEnums: ctx.dedupeEnums,
     defaultNonNullable: ctx.defaultNonNullable,
@@ -47,7 +52,7 @@ function transformOptions(ctx: GlobalContext): TransformOptions {
 }
 
 /** One footer per run: it holds the enum registry, so it lives on the run's context. */
-function runFooter(ctx: GlobalContext): DocumentFooter {
+function runFooter(ctx: RunContext): DocumentFooter {
   ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);
   return ctx.runFooter;
 }
@@ -57,7 +62,7 @@ const CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) }
 /**
  * A monotonic clock and the run's logger (the default one for a user's own context), "ts" group.
  */
-function diagnostics(ctx: GlobalContext): TransformDiagnostics {
+function diagnostics(ctx: RunContext): TransformDiagnostics {
   const logger = ctx.logger ?? defaultLogger(ctx.silent);
   return {
     now: monotonicNow,
@@ -66,13 +71,16 @@ function diagnostics(ctx: GlobalContext): TransformDiagnostics {
 }
 
 /** The ported transformers' context for one call from a legacy transformer. */
-export function createTransformContext(ctx: GlobalContext): TransformContext {
+export function createTransformContext(ctx: RunContext): TransformContext {
   return {
     options: transformOptions(ctx),
     refs: { resolve: (ref) => ctx.resolve(ref) },
     discriminators: {
       objectAt: (ref) => ctx.discriminators.objects[ref],
       isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      enumParentOf: (schema) =>
+        ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,
     },
     footer: runFooter(ctx),
     callbacks: schemaCallbacks(ctx),

package/src/api/transform-schema.ts

@@ -1,11 +1,22 @@
 import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
 import { documentBody, documentClosing } from "../application/transform/document/document.js";
-import { renameAliasesTakenByFooter } from "../application/transform/document/root-type-aliases.js";
+import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
+import { RunFooter } from "../application/transform/footer/document-footer.js";
+import { checkedEnumValues } from "../application/transform/footer/enum-values-check.js";
+import {
+  SharedEnumNameRecorder,
+  type SharedEnumNames,
+} from "../application/transform/footer/shared-enum-names.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { DocumentObject } from "../domain/openapi/document-object.js";
+import { OutputFix } from "../domain/output-fixes.js";
 import type { GlobalContext, OpenAPI3 } from "../types.js";
+import { FirstSchemaNameRecorder } from "./discriminator-enum-names.js";
 import { documentDeclarations, type TransformedDocument } from "./document-declarations.js";
+import { excludedValuesWarning } from "./enum-values-warnings.js";
 import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+import { ContextFooterSink } from "./footer-sink.js";
+import type { RunContext } from "./run-context.js";
 import { createTransformContext } from "./transform-context.js";
 
 const OPERATIONS_NAME = "operations";
@@ -18,15 +29,89 @@ function isOperations(entry: FooterEntry): boolean {
   return name === OPERATIONS_NAME;
 }
 
+/** Drops a message: the first pass must not repeat the run's warnings or debug lines. */
+const dropMessage = (): void => undefined;
+const DROPPED_MESSAGES = { debug: dropMessage, warn: dropMessage, error: dropMessage };
+
+/** A shared enum name recorder of a first pass, and the names it gives the second. */
+interface EnumNameRecorder extends SharedEnumNames {
+  chosenNames(): SharedEnumNames;
+}
+
+/**
+ * The names of shared enums, known only at the end: a first pass transforms the document into a
+ * scratch footer that `recorder` watches; its output is dropped. User callbacks run in both
+ * passes. The `dedupe-enum-names` fix (ADR-021, upstream #1683) names an enum by all of its
+ * schemas; `discriminator-values` keeps the first declaring schema's name
+ * (`FirstSchemaNameRecorder`).
+ */
+function sharedEnumNamesOf(
+  document: DocumentObject,
+  ctx: RunContext,
+  recorder: EnumNameRecorder,
+): SharedEnumNames {
+  const injectFooter: FooterEntry[] = [];
+  const scratch: RunContext = {
+    ...ctx,
+    injectFooter,
+    runFooter: new RunFooter(new ContextFooterSink(injectFooter), true, recorder),
+    logger: DROPPED_MESSAGES,
+    legacyCallbackWarnings: new Set(),
+  };
+  const scratchContext = createTransformContext(scratch);
+  documentBody(document, scratchContext, () => injectFooter.filter(isIrDeclaration));
+  return recorder.chosenNames();
+}
+
+/** The recorder of the run's fixes, or null where the first schema's name needs no first pass. */
+function enumNameRecorderOf(ctx: GlobalContext): EnumNameRecorder | null {
+  if (ctx.fix?.includes(OutputFix.DEDUPE_ENUM_NAMES)) {
+    return new SharedEnumNameRecorder();
+  }
+  return ctx.fix?.includes(OutputFix.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
+}
+
+/** With a naming fix, `--enum` and `--dedupe-enums`, the run's footer names shared enums. */
+function withSharedEnumNames(document: DocumentObject, ctx: RunContext): void {
+  const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
+  if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
+    return;
+  }
+  const names = sharedEnumNamesOf(document, ctx, recorder);
+  ctx.runFooter = new RunFooter(new ContextFooterSink(ctx.injectFooter), true, names);
+}
+
+/**
+ * With `--enum-values`, arrays whose location type does not hold their values are typed by their
+ * values (ADR-027); a location that excludes listed values is a contradiction of the document.
+ */
+function enumValuesChecked(
+  body: readonly IrDeclaration[],
+  footer: FooterEntry[],
+  ctx: RunContext,
+): FooterEntry[] {
+  if (!ctx.enumValues) {
+    return footer;
+  }
+  const checked = checkedEnumValues(footer, body, isIrDeclaration);
+  for (const retype of checked.retyped) {
+    if (retype.kind === "excluded") {
+      ctx.logger?.warn(excludedValuesWarning(retype.name, retype.excluded));
+    }
+  }
+  return checked.footer;
+}
+
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
-export function transformDocument(schema: OpenAPI3, ctx: GlobalContext): TransformedDocument {
+export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
+  withSharedEnumNames(document, ctx);
   const context = createTransformContext(ctx);
   // documentBody registers the enums in the footer, so the footer is read after it.
-  const rawBody = documentBody(document, context);
-  const footer: FooterEntry[] = [...ctx.injectFooter];
-  const body = renameAliasesTakenByFooter(rawBody, footer.filter(isIrDeclaration));
+  const rawBody = documentBody(document, context, () => ctx.injectFooter.filter(isIrDeclaration));
+  const footer = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
   const closing = documentClosing(document, context, footer.some(isOperations));
+  const body = renameTakenAliases(rawBody, footer.filter(isIrDeclaration), closing);
   return { body, footer, closing };
 }
 

package/src/api/unsupported-feature-warnings.ts

@@ -3,6 +3,7 @@ import {
   findUnsupportedFeatures,
   UnsupportedFeature,
 } from "../domain/openapi/unsupported-features.js";
+import { WARNING_CODES, type WarningCode, warningText } from "../domain/warnings.js";
 
 const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
 const SUPPORT_DOCS_URL = `${DOCS_BASE_URL}/introduction.md#openapi-3-2-support`;
@@ -15,12 +16,18 @@ const REASONS: Readonly<Record<UnsupportedFeature, string>> = {
     "generated types",
 };
 
+/** The warning code of each feature. */
+const CODES: Readonly<Record<UnsupportedFeature, WarningCode>> = {
+  [UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY]: WARNING_CODES.QUERYSTRING_NEXT_TO_QUERY,
+};
+
 /**
  * Warn once per use of an OpenAPI 3.2 feature that the generated types leave out, so a missing
  * parameter is never silent (CODING_PRINCIPLES §8.7).
  */
 export function warnUnsupportedFeatures(document: unknown, logger: Logger): void {
   for (const { feature, pointer } of findUnsupportedFeatures(document)) {
-    logger.warn(`${pointer} ${REASONS[feature]}. See ${SUPPORT_DOCS_URL}`);
+    const message = `${pointer} ${REASONS[feature]}. See ${SUPPORT_DOCS_URL}`;
+    logger.warn(warningText(message, CODES[feature]));
   }
 }

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

@@ -10,7 +10,11 @@ export interface RedoclyConfigSource {
    * from the working directory. Undefined when there is none.
    */
   find(explicitPath: string | undefined): string | undefined;
+  /** The config of a file; fails with `CLI_CONFIG_INVALID` when it or its ignore file is bad. */
   load(configPath: string): Promise<RedoclyConfig>;
-  /** The config used when there is no file: the minimal rules. */
+  /**
+   * The config used when there is no file: the minimal rules. Fails with `CLI_CONFIG_INVALID`
+   * when the ignore file of the working directory is bad.
+   */
   createDefault(): Promise<RedoclyConfig>;
 }

package/src/application/print/type-printer.ts

@@ -1,4 +1,5 @@
 import { assertNever } from "../../domain/assert-never.js";
+import { DEFAULT_STRING_ENCODING } from "../../domain/ir/constructors.js";
 import type {
   IrIndexedAccessType,
   IrMember,
@@ -135,6 +136,12 @@ function writeTupleElement(writer: TextWriter, element: IrTupleElement): void {
   if (element.isRest) {
     writer.write("...");
   }
+  if (element.isOptional) {
+    // TypeScript parenthesizes an optional element as a postfix operand (`(A | B)?`).
+    writeTypeIn(writer, element.type, needsParensAsPostfixOperand);
+    writer.write("?");
+    return;
+  }
   writeType(writer, element.type);
 }
 
@@ -190,7 +197,7 @@ function printLeafType(type: IrLeafType): string {
     case "keyword":
       return type.keyword;
     case "stringLiteral":
-      return printStringLiteral(type.value, type.encoding);
+      return printStringLiteral(type.value, type.encoding ?? DEFAULT_STRING_ENCODING);
     case "numberLiteral":
       return printNumberLiteral(type.value);
     case "booleanLiteral":

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

@@ -0,0 +1,203 @@
+import type { IrObjectType, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { indexSignaturesOf, nameOf, propertiesOf } from "./type-resolution.js";
+
+/**
+ * What the `--path-params-as-types` overlap check knows about one type where another is expected.
+ * `assignable` and `rejected` are proofs of what TypeScript decides (`strict`, without
+ * `exactOptionalPropertyTypes`); `undecided` is a pair the check does not model, such as a utility
+ * type or raw text. Only a rejection changes the output, so an undecided pair keeps the original.
+ */
+export type Assignability = "assignable" | "rejected" | "undecided";
+
+/**
+ * All of the relations: rejected when one is, assignable when each is. The relations are computed
+ * lazily, so a rejection stops the rest.
+ */
+export function everyOf<T>(
+  items: readonly T[],
+  relate: (item: T, index: number) => Assignability,
+): Assignability {
+  let result: Assignability = "assignable";
+  for (const [index, item] of items.entries()) {
+    const each = relate(item, index);
+    if (each === "rejected") {
+      return "rejected";
+    }
+    if (each === "undecided") {
+      result = "undecided";
+    }
+  }
+  return result;
+}
+
+/** One of the relations: assignable when one is, rejected when each is. */
+export function someOf<T>(items: readonly T[], relate: (item: T) => Assignability): Assignability {
+  let result: Assignability = "rejected";
+  for (const item of items) {
+    const each = relate(item);
+    if (each === "assignable") {
+      return "assignable";
+    }
+    if (each === "undecided") {
+      result = "undecided";
+    }
+  }
+  return result;
+}
+
+/** Assignable when the condition holds, rejected when it does not. */
+export function provenBy(condition: boolean): Assignability {
+  return condition ? "assignable" : "rejected";
+}
+
+/**
+ * The kinds of resolved types the check tells apart. A type of one kind is never assignable to a
+ * type of another, except that a primitive or a list may fit an object type (`string` fits
+ * `{ length: number }`), which the check models only in part. `opaque` is any type it cannot
+ * read.
+ */
+type TypeCategory = "primitive" | "list" | "object" | "opaque";
+
+function categoryOf(type: IrType): TypeCategory {
+  switch (type.kind) {
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+      return "primitive";
+    case "array":
+    case "tuple":
+    case "readonly":
+      return "list";
+    case "object":
+      return "object";
+    default:
+      return "opaque";
+  }
+}
+
+/** Keywords that are no object: `{}` rejects them under `strictNullChecks`. */
+const NO_OBJECT_KEYWORDS: ReadonlySet<string> = new Set(["null", "undefined", "unknown", "never"]);
+
+/**
+ * The members of `ReadonlyArray` and `Array` in the TypeScript libraries up to ESNext. An object
+ * type that needs a property of another name is no list; a numeric name may be a tuple element.
+ */
+const ARRAY_MEMBER_NAMES: ReadonlySet<string> = new Set([
+  "length",
+  "toString",
+  "toLocaleString",
+  "pop",
+  "push",
+  "concat",
+  "join",
+  "reverse",
+  "shift",
+  "slice",
+  "sort",
+  "splice",
+  "unshift",
+  "indexOf",
+  "lastIndexOf",
+  "every",
+  "some",
+  "forEach",
+  "map",
+  "filter",
+  "reduce",
+  "reduceRight",
+  "find",
+  "findIndex",
+  "fill",
+  "copyWithin",
+  "entries",
+  "keys",
+  "values",
+  "includes",
+  "flatMap",
+  "flat",
+  "at",
+  "findLast",
+  "findLastIndex",
+  "toReversed",
+  "toSorted",
+  "toSpliced",
+  "with",
+]);
+
+const ARRAY_LENGTH = "length";
+/** A tuple element's name: `"0"`, `"1"`. */
+const ELEMENT_NAME_RE = /^\d+$/;
+
+function isListMemberName(name: string): boolean {
+  return ARRAY_MEMBER_NAMES.has(name) || ELEMENT_NAME_RE.test(name);
+}
+
+/**
+ * Whether a list fits an object type. It does not when the object needs a property no list has
+ * (TS2741), or when the object is a weak type and no list has one of its properties (TS2559).
+ */
+function listToObject(target: IrObjectType): Assignability {
+  const properties = [...propertiesOf(target).values()];
+  const isForeign = (property: IrPropertySignature) => !isListMemberName(nameOf(property));
+  const needsForeign = properties.some((property) => !property.isOptional && isForeign(property));
+  const isWeak =
+    properties.length > 0 &&
+    indexSignaturesOf(target).length === 0 &&
+    properties.every((property) => property.isOptional);
+  return needsForeign || (isWeak && properties.every(isForeign)) ? "rejected" : "undecided";
+}
+
+/**
+ * Whether a primitive fits an object type: `null`, `undefined` and `unknown` never do; any other
+ * may (`{}`, `{ length: number }`), which is not modelled.
+ */
+function primitiveToObject(source: IrType): Assignability {
+  const isNoObject = source.kind === "keyword" && NO_OBJECT_KEYWORDS.has(source.keyword);
+  return isNoObject ? "rejected" : "undecided";
+}
+
+/** An object type fits an array only with all of its members; `length` is the first it needs. */
+function objectToList(source: IrObjectType): Assignability {
+  return propertiesOf(source).has(ARRAY_LENGTH) ? "undecided" : "rejected";
+}
+
+/**
+ * The relation of two types of different categories, or null when they are of the same one.
+ * Primitive and list targets accept nothing of another category; see `TypeCategory`.
+ */
+export function crossCategoryRelation(source: IrType, target: IrType): Assignability | null {
+  const from = categoryOf(source);
+  const to = categoryOf(target);
+  if (from === "opaque" || to === "opaque") {
+    return "undecided";
+  }
+  if (from === to) {
+    return null;
+  }
+  if (to !== "object") {
+    return source.kind === "object" && to === "list" ? objectToList(source) : "rejected";
+  }
+  return from === "primitive" ? primitiveToObject(source) : listToObject(target as IrObjectType);
+}
+
+/** The keyword a literal type belongs to. */
+const LITERAL_KEYWORDS = {
+  stringLiteral: "string",
+  numberLiteral: "number",
+  booleanLiteral: "boolean",
+} as const;
+
+/**
+ * The relation of two primitive types written differently (the same text is assignable). A
+ * literal fits its keyword; any other pair is rejected: different keywords, different literals,
+ * a keyword for one literal (a union of literals is compared in `type-assignability.ts`), and
+ * anything for `never`.
+ */
+export function primitiveRelation(source: IrType, target: IrType): Assignability {
+  if (target.kind !== "keyword" || source.kind === "keyword") {
+    return "rejected";
+  }
+  const keyword = (LITERAL_KEYWORDS as Partial<Record<IrType["kind"], string>>)[source.kind];
+  return provenBy(keyword === target.keyword);
+}