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

package/src/application/transform/footer/type-indexing.ts

@@ -0,0 +1,152 @@
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import {
+  type Evaluated,
+  type Evaluation,
+  intersectionType,
+  isNullish,
+  MISSING,
+  NEVER,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+import { declaredFirst, isNeverIntersection, type TypeExpansion } from "./type-rules.js";
+
+/**
+ * Indexed access (`T["key"]`, `T[number]`) on the generated types, as TypeScript reads it, for
+ * the evaluator of the `--enum-values` check (ADR-027).
+ */
+
+/** The part of the evaluator that indexed access uses. */
+export interface IndexedTypes extends TypeExpansion {
+  expand(value: Evaluated): Evaluation;
+  index(value: Evaluated, index: IrType): Evaluation;
+}
+
+/** `value[index]` for a string literal, `string` or `number` index. */
+export function indexType(types: IndexedTypes, value: Evaluated, index: IrType): Evaluation {
+  const owner = types.expand(value);
+  if (owner.kind !== "type") {
+    return owner;
+  }
+  if (types.membersOf(owner).length > 1) {
+    return unionIndex(types, owner, index);
+  }
+  const { type } = owner;
+  switch (type.kind) {
+    case "object":
+      return memberType(types, owner, type.members, index);
+    case "intersection":
+      return partsIndex(types, owner, type.types, index);
+    case "union":
+      return unionIndex(types, owner, index);
+    case "array":
+      return isNumberIndex(index) ? flattened(types, owner, type.element) : builtInIndex(index);
+    case "keyword":
+      return type.keyword === "never" ? owner : builtInIndex(index);
+    default:
+      return builtInIndex(index);
+  }
+}
+
+function memberType(
+  types: IndexedTypes,
+  owner: Evaluated,
+  members: readonly IrMember[],
+  index: IrType,
+): Evaluation {
+  const key = indexKey(index);
+  const property = members.find(
+    (member) => member.kind === "property" && key !== null && propertyKey(member.name) === key,
+  );
+  if (property !== undefined) {
+    return flattened(types, owner, property.type);
+  }
+  const signature = members.find((member) => member.kind === "indexSignature");
+  if (signature !== undefined) {
+    return flattened(types, owner, signature.type);
+  }
+  return key === null || isObjectBuiltIn(key) ? OPAQUE : MISSING;
+}
+
+function partsIndex(
+  types: IndexedTypes,
+  owner: Evaluated,
+  parts: readonly IrType[],
+  index: IrType,
+): Evaluation {
+  if (isNeverIntersection(types, owner, parts)) {
+    return { ...owner, type: NEVER };
+  }
+  const found = parts.map((type) => types.index({ ...owner, type }, index));
+  if (found.some((part) => part.kind === "opaque")) {
+    return OPAQUE;
+  }
+  const read = parts.map((type, at) => ({ type, found: found[at] as Evaluation }));
+  const kept = declaredFirst(types, owner, indexKey(index), read).flatMap((part) =>
+    part.kind === "type" ? [part.type] : [],
+  );
+  return kept.length === 0 ? MISSING : { ...owner, type: intersectionType(kept) };
+}
+
+function unionIndex(types: IndexedTypes, owner: Evaluated, index: IrType): Evaluation {
+  const found = types
+    .membersOf(owner)
+    .map((member) => (member.kind === "type" ? types.index(member, index) : member));
+  if (found.some((member) => member.kind === "missing")) {
+    return MISSING;
+  }
+  if (found.some((member) => member.kind === "opaque")) {
+    return OPAQUE;
+  }
+  return { ...owner, type: unionType((found as Evaluated[]).map((member) => member.type)) };
+}
+
+/**
+ * A member read through `FlattenedDeepRequired`: a value that is only arrays (and `undefined` or
+ * `null`) is replaced by its elements, anything else loses `undefined` and `null`.
+ */
+function flattened(types: IndexedTypes, owner: Evaluated, type: IrType): Evaluation {
+  const member: Evaluated = { ...owner, type };
+  if (!owner.deep) {
+    return types.expand(member);
+  }
+  const members = types.membersOf(member);
+  if (members.some((candidate) => candidate.kind !== "type")) {
+    return OPAQUE;
+  }
+  const present = (members as Evaluated[]).filter((candidate) => !isNullish(candidate.type));
+  const elements = present.map((candidate) => arrayElement(candidate.type));
+  if (present.length > 0 && elements.every((element) => element !== null)) {
+    return types.expand({ ...owner, type: unionType(elements as IrType[]) });
+  }
+  return { ...owner, type: unionType(present.map((candidate) => candidate.type)) };
+}
+
+/** The element of an expanded member; expanding already dropped `readonly`. */
+function arrayElement(type: IrType): IrType | null {
+  return type.kind === "array" ? type.element : null;
+}
+
+function indexKey(index: IrType): string | null {
+  if (index.kind === "stringLiteral") {
+    return index.value;
+  }
+  return index.kind === "numberLiteral" ? String(index.value) : null;
+}
+
+function isNumberIndex(index: IrType): boolean {
+  const key = indexKey(index);
+  return (index.kind === "keyword" && index.keyword === "number") || /^\d+$/.test(key ?? "");
+}
+
+function isObjectBuiltIn(key: string): boolean {
+  return key in {};
+}
+
+/** A key of a primitive or an array: a built-in member is opaque, any other key is missing. */
+function builtInIndex(index: IrType): Evaluation {
+  const key = indexKey(index);
+  const isBuiltIn = key === null || key in String.prototype || key in Array.prototype;
+  return isBuiltIn || key in Number.prototype ? OPAQUE : MISSING;
+}

package/src/application/transform/footer/type-rules.ts

@@ -0,0 +1,269 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type {
+  IrMember,
+  IrObjectType,
+  IrPropertySignature,
+  IrType,
+} from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import {
+  type Evaluated,
+  type Evaluation,
+  MISSING,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+
+/**
+ * Rules of TypeScript about intersections, `Omit` and `Extract` that the `--enum-values` check
+ * needs (ADR-027). They read the types as written, before `FlattenedDeepRequired`.
+ */
+
+/** The part of the evaluator these rules use. */
+export interface TypeExpansion {
+  membersOf(value: Evaluated): readonly Evaluation[];
+}
+
+/** A unit value of a type: a literal, `null` or `undefined`. */
+type Unit = string;
+
+/**
+ * The parts an intersection is made of, nested intersections flattened: each object type, or
+ * `null` for a part that is not one.
+ */
+function objectParts(
+  types: TypeExpansion,
+  value: Evaluated,
+  parts: readonly IrType[],
+): (IrObjectType | null)[] {
+  return parts.flatMap((part) => {
+    const members = types.membersOf({ ...value, type: part });
+    const [only] = members;
+    if (members.length !== 1 || only?.kind !== "type") {
+      return [null];
+    }
+    if (only.type.kind === "intersection") {
+      return objectParts(types, only, only.type.types);
+    }
+    return [only.type.kind === "object" ? only.type : null];
+  });
+}
+
+function unitOf(type: IrType): Unit | null {
+  switch (type.kind) {
+    case "stringLiteral":
+      return `s:${type.value}`;
+    case "numberLiteral":
+      return `n:${type.value}`;
+    case "booleanLiteral":
+      return `b:${type.value}`;
+    case "keyword":
+      return type.keyword === "null" || type.keyword === "undefined" ? type.keyword : null;
+    default:
+      return null;
+  }
+}
+
+/** The unit values of a type made only of units, or `null` where it has other values. */
+function unitsOf(types: TypeExpansion, value: Evaluated, type: IrType): ReadonlySet<Unit> | null {
+  const units = types.membersOf({ ...value, type }).map((member) => {
+    return member.kind === "type" ? unitOf(member.type) : null;
+  });
+  return units.includes(null) ? null : new Set(units as Unit[]);
+}
+
+function propertiesNamed(objects: readonly IrObjectType[], key: string): IrPropertySignature[] {
+  return objects.flatMap((object) => {
+    const members: readonly IrMember[] = object.members;
+    return members.filter(
+      (member): member is IrPropertySignature =>
+        member.kind === "property" && propertyKey(member.name) === key,
+    );
+  });
+}
+
+/** Whether properties of the same name share no unit value, one of them required. */
+function isNeverProperty(
+  types: TypeExpansion,
+  value: Evaluated,
+  found: IrPropertySignature[],
+): boolean {
+  if (found.length < 2 || found.every((property) => property.isOptional)) {
+    return false;
+  }
+  const sets = found.map((property) => unitsOf(types, value, property.type));
+  if (sets.includes(null)) {
+    return false;
+  }
+  // At least two properties, so at least two sets.
+  const [first, ...rest] = sets as [ReadonlySet<Unit>, ...ReadonlySet<Unit>[]];
+  const shared = [...first].filter((unit) => rest.every((set) => set.has(unit)));
+  return shared.length === 0;
+}
+
+/** Whether an intersection has `null` or `undefined` next to an object: `null & { a: 1 }`. */
+function isNullishObject(types: TypeExpansion, value: Evaluated, parts: readonly IrType[]) {
+  const singles = parts.map((part) => {
+    const members = types.membersOf({ ...value, type: part });
+    const [only] = members;
+    return members.length === 1 && only?.kind === "type" ? only.type : null;
+  });
+  const isNullish = (type: IrType | null) =>
+    type?.kind === "keyword" && (type.keyword === "null" || type.keyword === "undefined");
+  return singles.some(isNullish) && singles.some((type) => type?.kind === "object");
+}
+
+/**
+ * Whether TypeScript reduces an intersection to `never`: `null` or `undefined` meets an object,
+ * or objects share a property with literal types that have no value in common, one of them
+ * requiring it (`{ a: "x" } & { a: "y" }`). Other properties are left alone, so the answer is
+ * sure where it is yes.
+ */
+export function isNeverIntersection(
+  types: TypeExpansion,
+  value: Evaluated,
+  parts: readonly IrType[],
+): boolean {
+  if (isNullishObject(types, value, parts)) {
+    return true;
+  }
+  const objects = objectParts(types, value, parts).filter((part) => part !== null);
+  if (objects.length < 2) {
+    return false;
+  }
+  const keys = new Set(
+    objects.flatMap((object) =>
+      object.members.flatMap((member) =>
+        member.kind === "property" ? [propertyKey(member.name)] : [],
+      ),
+    ),
+  );
+  const valueOfKeys = { ...value, deep: false };
+  return [...keys].some((key) =>
+    isNeverProperty(types, valueOfKeys, propertiesNamed(objects, key)),
+  );
+}
+
+/** Whether `key` reaches only an index signature of this object: it declares no such property. */
+function isSignatureOnly(types: TypeExpansion, value: Evaluated, key: string | null): boolean {
+  const members = types.membersOf(value);
+  const [only] = members;
+  if (
+    key === null ||
+    members.length !== 1 ||
+    only?.kind !== "type" ||
+    only.type.kind !== "object"
+  ) {
+    return false;
+  }
+  const { members: declared } = only.type;
+  const hasSignature = declared.some((member) => member.kind === "indexSignature");
+  return hasSignature && propertiesNamed([only.type], key).length === 0;
+}
+
+/**
+ * The parts of an intersection indexed by `index`, as TypeScript reads them: where one part
+ * declares the property, the index signatures of the others do not take part
+ * (`{ a: X } & { [key: string]: Y }` gives `X` for `a`).
+ */
+export function declaredFirst(
+  types: TypeExpansion,
+  value: Evaluated,
+  key: string | null,
+  parts: readonly { readonly type: IrType; readonly found: Evaluation }[],
+): Evaluation[] {
+  const bySignature = parts.map(({ type }) => isSignatureOnly(types, { ...value, type }, key));
+  const isDeclared = parts.some(({ found }, at) => found.kind === "type" && !bySignature[at]);
+  return parts.filter((_, at) => !(isDeclared && bySignature[at])).map(({ found }) => found);
+}
+
+/**
+ * Whether a member of `membersOf` has `key` as a property that `{ key: unknown }` accepts: written
+ * and, outside `FlattenedDeepRequired`, required. An index signature does not count, as in
+ * TypeScript. Such a member is expanded, parts included, so it is an object, an intersection of
+ * members, or a primitive or array type, which has no such property; a type the evaluator cannot
+ * read makes `membersOf` opaque instead.
+ */
+function hasKey(value: Evaluated, key: string): boolean {
+  const { type } = value;
+  if (type.kind === "intersection") {
+    return type.types.some((part) => hasKey({ ...value, type: part }, key));
+  }
+  if (type.kind !== "object") {
+    return false;
+  }
+  return propertiesNamed([type], key).some((property) => value.deep || !property.isOptional);
+}
+
+/**
+ * `Extract<T, { key: unknown }>`: the members of `T` that have `key`. When none has it the
+ * result is `never`; it is `missing` here, as the location then types nothing.
+ */
+export function extracted(types: TypeExpansion, value: Evaluated, key: string): Evaluation {
+  const members = types.membersOf(value);
+  if (members.some((member) => member.kind !== "type")) {
+    return OPAQUE;
+  }
+  const kept = (members as Evaluated[]).filter((member) => hasKey(member, key));
+  if (kept.length === 0) {
+    return MISSING;
+  }
+  return { ...value, type: unionType(kept.map((member) => member.type)) };
+}
+
+function omittedKeys(types: TypeExpansion, value: Evaluated, keys: IrType): Set<string> | null {
+  const members = types.membersOf({ ...value, type: keys });
+  const names = members.map((member) =>
+    member.kind === "type" && member.type.kind === "stringLiteral" ? member.type.value : null,
+  );
+  return names.includes(null) ? null : new Set(names as string[]);
+}
+
+/** Whether two members name the same property: merging them would need their intersection. */
+function hasSharedProperty(members: readonly IrMember[]): boolean {
+  const names = members.flatMap((member) =>
+    member.kind === "property" ? [propertyKey(member.name)] : [],
+  );
+  return new Set(names).size !== names.length;
+}
+
+/**
+ * `Omit<T, K>` for literal keys `K` over an object or an intersection of objects. A string index
+ * signature makes `keyof T` all strings, so only the index signatures are left.
+ */
+export function omitted(types: TypeExpansion, value: Evaluated, keys: IrType): Evaluation {
+  const names = omittedKeys(types, value, keys);
+  const objects = objectParts(types, value, [value.type]);
+  if (names === null || objects.length === 0 || objects.includes(null)) {
+    return OPAQUE;
+  }
+  const members = (objects as IrObjectType[]).flatMap((object) => object.members);
+  if (hasSharedProperty(members)) {
+    return OPAQUE;
+  }
+  const signatures = members.filter((member) => member.kind === "indexSignature");
+  const kept =
+    signatures.length > 0
+      ? signatures
+      : members.filter(
+          (member) => member.kind !== "property" || !names.has(propertyKey(member.name)),
+        );
+  return { ...value, type: { kind: "object", members: kept } };
+}
+
+/** The `--read-write-markers` types and their one member (`READ_WRITE_MARKER_TYPES`). */
+const READ_WRITE_MARKER_KEYS: ReadonlyMap<string, string> = new Map([
+  ["$Read", "$read"],
+  ["$Write", "$write"],
+]);
+
+/** `$Read<T>` is `{ readonly $read: T }`: an object, which holds no enum value. */
+export function markerObject(name: string, argument: Evaluated): Evaluated | null {
+  const key = READ_WRITE_MARKER_KEYS.get(name);
+  if (key === undefined) {
+    return null;
+  }
+  const member = irProperty(toPropertyName(key), argument.type, { isReadonly: true });
+  return { ...argument, type: irObject([member]) };
+}

package/src/application/transform/ref-pointer/generated-location.ts

@@ -0,0 +1,211 @@
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import { isJsonObject } from "./generated-shape.js";
+import {
+  leadingSegmentsOf,
+  type RefPointer,
+  refPointerOf,
+  startsInSchema,
+} from "./pointer-walk.js";
+
+/**
+ * Where the generator types the node a `$ref` points at: the location path it passes down, which
+ * also names the node's `--enum` declaration and `--enum-values` array. A target written inline
+ * (ADR-026) is typed there, so it shares the generator's enum instead of declaring a second one
+ * named after the pointer: two TypeScript enums with the same members are not assignable.
+ *
+ * The path follows the generator: `properties` is skipped; `allOf/N`, `items`, `prefixItems/N`,
+ * `patternProperties/P` and `additionalProperties` type their schema at the parent's location;
+ * the `schema` of a parameter, header or media type is typed at the container's; a positional
+ * parameter is named by `in` and `name`. A `$ref` crossed on the way continues at its target's
+ * location. A node under a schema keyword the generator does not type (`definitions/A`, `not`) is
+ * typed nowhere else, so it keeps its pointer as its location.
+ */
+
+export interface GeneratedLocation {
+  readonly path: string;
+  /** The node is an `additionalProperties` value, as `transformNested` is told. */
+  readonly isFromAdditionalProperties: boolean;
+}
+
+interface LocationWalk {
+  readonly path: readonly string[];
+  readonly node: unknown;
+  readonly isSchema: boolean;
+  readonly isFromAdditionalProperties: boolean;
+}
+
+/** One step: the segments it adds to the path, the node it moves to, the segments it reads. */
+interface Step {
+  readonly path: readonly string[];
+  readonly child: unknown;
+  readonly length: 1 | 2;
+  readonly isSchema: boolean;
+  readonly isFromAdditionalProperties?: boolean;
+}
+
+/** Keywords followed by a name or position whose schema is typed at the parent's location. */
+const PARENT_LOCATION_PAIRS: ReadonlySet<string> = new Set([
+  "allOf",
+  "prefixItems",
+  "patternProperties",
+]);
+/** Keywords whose schema is typed at the parent's location as a record value. */
+const RECORD_VALUE_KEYWORDS: ReadonlySet<string> = new Set([
+  "additionalProperties",
+  "unevaluatedProperties",
+]);
+/** Keywords followed by a name or position that both stay in the location. */
+const KEPT_PAIRS: ReadonlySet<string> = new Set(["anyOf", "oneOf", "$defs"]);
+/** The other schema keywords the generator types: at the parent's location. */
+const PARENT_LOCATION_KEYWORDS: ReadonlySet<string> = new Set(["items", ...RECORD_VALUE_KEYWORDS]);
+const INDEX_RE = /^\d+$/;
+
+function childOf(node: unknown, segment: string | undefined): unknown {
+  return (isJsonObject(node) || Array.isArray(node)) && segment !== undefined
+    ? (node as Readonly<Record<string, unknown>>)[segment]
+    : undefined;
+}
+
+function pairStep(value: unknown, next: string | undefined, path: readonly string[]): Step {
+  return { path, child: childOf(value, next), length: 2, isSchema: true };
+}
+
+/** The step through a schema keyword; null for a keyword the generator does not type. */
+function schemaStep(node: unknown, segment: string, next: string | undefined): Step | null {
+  const value = childOf(node, segment);
+  const named = next === undefined ? [] : [next];
+  if (segment === "properties") {
+    return pairStep(value, next, named);
+  }
+  if (PARENT_LOCATION_PAIRS.has(segment) || (segment === "items" && Array.isArray(value))) {
+    return pairStep(value, next, []);
+  }
+  if (KEPT_PAIRS.has(segment)) {
+    return pairStep(value, next, [segment, ...named]);
+  }
+  if (!PARENT_LOCATION_KEYWORDS.has(segment)) {
+    return null;
+  }
+  const isRecordValue = RECORD_VALUE_KEYWORDS.has(segment);
+  return {
+    path: [],
+    child: value,
+    length: 1,
+    isSchema: true,
+    isFromAdditionalProperties: isRecordValue,
+  };
+}
+
+/** A path item's own parameters sit under one more `parameters` segment (`pathItemType`). */
+function isPathItem(path: readonly string[]): boolean {
+  const [root, section] = path;
+  return (
+    (path.length === 2 && (root === "paths" || root === "webhooks")) ||
+    (path.length === 3 && root === "components" && section === "pathItems")
+  );
+}
+
+/** `parameters/N`: the parameter is named by `in` and `name` (a `$ref` one is crossed later). */
+function parameterStep(walk: LocationWalk, next: string): Step {
+  const entry = childOf(childOf(walk.node, "parameters"), next);
+  const where = isJsonObject(entry) ? [String(entry.in), String(entry.name)] : [];
+  const prefix = isPathItem(walk.path) ? ["parameters"] : [];
+  return { path: [...prefix, "parameters", ...where], child: entry, length: 2, isSchema: false };
+}
+
+function documentStep(walk: LocationWalk, segments: readonly string[], index: number): Step {
+  const segment = segments[index] as string;
+  const next = segments[index + 1];
+  const value = childOf(walk.node, segment);
+  if (segment === "schema") {
+    return { path: [], child: value, length: 1, isSchema: true };
+  }
+  if (segment === "parameters" && next !== undefined && INDEX_RE.test(next)) {
+    return parameterStep(walk, next);
+  }
+  // A header's `content` entries are typed at `headers/<name>/<media type>` (`headerType`).
+  if (segment === "content" && segments[index - 2] === "headers") {
+    const path = next === undefined ? [] : [next];
+    return { path, child: childOf(value, next), length: 2, isSchema: false };
+  }
+  return { path: [segment], child: value, length: 1, isSchema: false };
+}
+
+function stepAt(walk: LocationWalk, pointer: RefPointer, index: number): Step | null {
+  const { segments } = pointer;
+  const segment = segments[index] as string;
+  if (index < leadingSegmentsOf(pointer)) {
+    const child = childOf(walk.node, segment);
+    return { path: [segment], child, length: 1, isSchema: startsInSchema(pointer) };
+  }
+  return walk.isSchema
+    ? schemaStep(walk.node, segment, segments[index + 1])
+    : documentStep(walk, segments, index);
+}
+
+function refOf(node: unknown): string | null {
+  return isJsonObject(node) && typeof node.$ref === "string" ? node.$ref : null;
+}
+
+/**
+ * The walk at a crossed `$ref`'s target, through `$ref`s to `$ref`s; null where the target has
+ * no generated location. A cycle of `$ref`s has no node.
+ */
+function crossed(
+  walk: LocationWalk,
+  ref: string,
+  refs: RefResolver,
+  seen: readonly string[],
+): LocationWalk | null {
+  if (seen.includes(ref)) {
+    return { ...walk, node: undefined };
+  }
+  const target = walkTo(ref, refs, seen);
+  const inner = refOf(target?.node);
+  return target === null || inner === null ? target : crossed(target, inner, refs, [...seen, ref]);
+}
+
+function walkTo(ref: string, refs: RefResolver, seen: readonly string[]): LocationWalk | null {
+  const pointer = refPointerOf(ref);
+  if (pointer === null || seen.includes(ref)) {
+    return null;
+  }
+  const root = pointer.rootSegment;
+  let walk: LocationWalk = {
+    path: [root],
+    node: refs.resolve(`#/${root}`),
+    isSchema: false,
+    isFromAdditionalProperties: false,
+  };
+  for (let index = 0; index < pointer.segments.length; ) {
+    const step = stepAt(walk, pointer, index);
+    if (step === null) {
+      return null;
+    }
+    index += step.length;
+    walk = {
+      path: [...walk.path, ...step.path],
+      node: step.child,
+      isSchema: step.isSchema,
+      isFromAdditionalProperties: step.isFromAdditionalProperties === true,
+    };
+    const inner = refOf(walk.node);
+    const target = inner !== null && index < pointer.segments.length;
+    const next = target ? crossed(walk, inner, refs, [...seen, ref]) : walk;
+    if (next === null) {
+      return null;
+    }
+    walk = next;
+  }
+  return walk;
+}
+
+/** The location the generator types the node at `ref` with; see the module comment. */
+export function generatedLocationOf(ref: string, refs: RefResolver): GeneratedLocation {
+  const walk = walkTo(ref, refs, []);
+  return {
+    path: walk === null ? ref : createRef(walk.path),
+    isFromAdditionalProperties: walk?.isFromAdditionalProperties ?? false,
+  };
+}