@distilled.cloud/core 0.30.3 → 1.0.0-rc.10

package/src/graphql.types.ts

@@ -0,0 +1,185 @@
+/** Compile-only contract checks. The coordinator runs these with noCheck=false. */
+import type * as G from "./graphql.ts";
+import type * as Stream from "effect/Stream";
+import type {
+  FixtureSchema,
+  ProjectNotFound,
+  ServicesUnavailable,
+  Unauthorized,
+  PageInfoUnavailable,
+} from "./graphql.fixture.ts";
+
+type Assert<T extends true> = T;
+type Assignable<A, B> = [A] extends [B] ? true : false;
+type Equal<A, B> = Assignable<A, B> extends true ? Assignable<B, A> : false;
+
+type IdentitySelection = {
+  project: { where: { id: "p1" }; select: { id: true } };
+};
+type DetailedSelection = {
+  project: {
+    where: { id: "p1" };
+    select: {
+      id: true;
+      services: { select: { edges: { node: { id: true } } } };
+    };
+  };
+};
+type AliasSelection = {
+  __alias: {
+    production: { project: { where: { id: "p1" }; select: { id: true } } };
+  };
+};
+type SearchSelection = {
+  search: {
+    where: { text: "prod" };
+    select: {
+      __typename: true;
+      __on: { Project: { name: true }; Service: { status: true } };
+    };
+  };
+};
+
+type Identity = G.Result<FixtureSchema, "Query!", IdentitySelection>;
+type _Identity = Assert<Equal<Identity, { project: { id: string } | null }>>;
+type _UnselectedFieldsAbsent = Assert<
+  Equal<keyof NonNullable<Identity["project"]>, "id">
+>;
+
+type Alias = G.Result<FixtureSchema, "Query!", AliasSelection>;
+type _Alias = Assert<Equal<Alias, { production: { id: string } | null }>>;
+
+type Search = G.Result<FixtureSchema, "Query!", SearchSelection>;
+type _Union = Assert<
+  Equal<
+    Search["search"][number],
+    | { __typename: "Project"; name: string }
+    | { __typename: "Service"; status: "ACTIVE" | "ARCHIVED" }
+  >
+>;
+
+type IdentityErrors = G.Errors<FixtureSchema, "Query", IdentitySelection>;
+type DetailedErrors = G.Errors<FixtureSchema, "Query", DetailedSelection>;
+type _RootErrorIncluded = Assert<Assignable<ProjectNotFound, IdentityErrors>>;
+type _GlobalErrorIncluded = Assert<Assignable<Unauthorized, IdentityErrors>>;
+type _NestedErrorIncluded = Assert<
+  Assignable<ServicesUnavailable, DetailedErrors>
+>;
+type _UnselectedErrorExcluded = Assert<
+  Equal<Extract<IdentityErrors, { _tag: "ServicesUnavailable" }>, never>
+>;
+
+type ConditionalRoot = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    ping: { $include: boolean; select: true };
+  }
+>;
+type _ConditionalRoot = Assert<Equal<ConditionalRoot, { ping?: boolean }>>;
+type ConditionalNested = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    project: {
+      where: { id: string };
+      select: {
+        id: true;
+        name: { $skip: boolean; select: true };
+      };
+    };
+  }
+>;
+type _ConditionalNested = Assert<
+  Equal<
+    ConditionalNested,
+    {
+      project: { id: string; name?: string } | null;
+    }
+  >
+>;
+type ConditionalAlias = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    __alias: { healthy: { ping: { $include: boolean; select: true } } };
+  }
+>;
+type _ConditionalAlias = Assert<Equal<ConditionalAlias, { healthy?: boolean }>>;
+
+type MergedInterface = G.Result<
+  FixtureSchema,
+  "Node!",
+  {
+    __typename: true;
+    parent: { id: true };
+    __on: { Project: { parent: { name: true } } };
+  }
+>;
+type _MergedInterface = Assert<
+  Equal<
+    Extract<MergedInterface, { __typename: "Project" }>["parent"],
+    { id: string; name: string } | null
+  >
+>;
+
+// These assignments exercise user-facing argument and nested selection validation.
+const validSelection: G.Selection<FixtureSchema, "Query"> = {
+  project: {
+    where: { id: "p1" },
+    select: {
+      services: {
+        where: { first: 10 },
+        select: { edges: { node: { id: true } } },
+      },
+    },
+  },
+};
+const missingArgument: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error Required GraphQL field arguments cannot be omitted.
+  project: { select: { id: true } },
+};
+const wrongArgument: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error GraphQL argument types follow the schema.
+  project: { where: { id: 42 }, select: { id: true } },
+};
+const unknownField: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error Unknown nested fields cannot be selected.
+  project: { where: { id: "p1" }, select: { invented: true } },
+};
+// @ts-expect-error Fields returning objects require a projection.
+const noProjection: G.Selection<FixtureSchema, "Query"> = { project: true };
+
+void [
+  validSelection,
+  missingArgument,
+  wrongArgument,
+  unknownField,
+  noProjection,
+];
+
+// Named operations retain projection and pagination constraints during inference.
+declare const inferredClient: ReturnType<
+  typeof G.makeClient<FixtureSchema, never>
+>;
+
+// @ts-expect-error An object-returning operation always requires a projection.
+inferredClient.operation("query", "project")({ id: "p1" });
+// @ts-expect-error Non-connection object queries do not expose pages.
+inferredClient.operation("query", "project").pages;
+// @ts-expect-error Scalar queries do not expose connection pagination.
+inferredClient.operation("query", "ping").items;
+// @ts-expect-error Mutations cannot be paginated.
+inferredClient.operation("mutation", "editProject").pages;
+
+const selectivePages = inferredClient
+  .operation("query", "services")
+  .pages({}, { edges: { node: { id: true } } });
+type PageErrors = Stream.Error<typeof selectivePages>;
+type PageIssues =
+  Extract<PageErrors, G.GraphQLFailure> extends G.GraphQLFailure<infer E>
+    ? E
+    : never;
+type _HiddenPaginationErrorIncluded = Assert<
+  Assignable<PageInfoUnavailable, PageIssues>
+>;

package/src/json-patch.ts

@@ -1,20 +1,15 @@
 /**
  * JSON Patch (RFC 6902) Implementation
  *
- * Provides a unified spec patching system for all SDKs.
- * Patches are applied to OpenAPI/Discovery/Smithy specs before code generation
- * to add error types, fix nullable fields, mark sensitive data, etc.
+ * Provides a unified spec patching system for all SDKs. Patches apply in
+ * `convert` so `.generated-specs` is the patched Smithy model. generate does
+ * not patch. Prefer `operationNaming: "verbNoun"` for operationId renames —
+ * JSON pointers at `/paths/~1foo/operationId` go stale when upstream prefixes
+ * paths.
  *
- * @example
- * ```ts
- * import { applyAllPatches } from "@distilled.cloud/core/json-patch";
- *
- * const spec = JSON.parse(fs.readFileSync("openapi.json", "utf-8"));
- * const { applied, errors } = applyAllPatches(spec, "./patches");
- * ```
+ * Pure functions only — callers load patch files themselves (the generators
+ * use Effect's FileSystem) and hand the parsed operations to `applyPatch`.
  */
-import * as fs from "fs";
-import * as path from "path";
 
 // ============================================================================
 // Types
@@ -30,7 +25,7 @@ export interface JsonPatchOperation {
 export type JsonPatch = JsonPatchOperation[];
 
 export interface PatchFile {
-  description: string;
+  description?: string;
   patches: JsonPatch;
 }
 
@@ -38,9 +33,7 @@ export interface PatchFile {
 // JSON Pointer (RFC 6901)
 // ============================================================================
 
-/**
- * Parse a JSON Pointer (RFC 6901) path into segments.
- */
+/** Parse a JSON Pointer (RFC 6901) path into segments. */
 export function parseJsonPointer(pointer: string): string[] {
   if (pointer === "") return [];
   if (!pointer.startsWith("/")) {
@@ -52,31 +45,52 @@ export function parseJsonPointer(pointer: string): string[] {
     .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 }
 
+/** Get a value at a JSON Pointer path. */
 /**
- * Get a value at a JSON Pointer path.
+ * The target location of a patch operation is absent from the document —
+ * spec drift (renamed/removed upstream), not a malformed patch.
  */
+export class StaleTargetError extends Error {
+  override readonly name = "StaleTargetError";
+}
+
 export function getValueAtPath(obj: unknown, pointer: string): unknown {
   const segments = parseJsonPointer(pointer);
   let current: unknown = obj;
 
   for (const segment of segments) {
-    if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing (at '${segment}'): not an object`,
+      );
     }
     if (Array.isArray(current)) {
       const index = segment === "-" ? current.length : parseInt(segment, 10);
+      if (index < 0 || index >= current.length) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing index '${segment}'`,
+        );
+      }
       current = current[index];
     } else {
-      current = (current as Record<string, unknown>)[segment];
+      const record = current as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing key '${segment}'`,
+        );
+      }
+      current = record[segment];
     }
   }
 
   return current;
 }
 
-/**
- * Set a value at a JSON Pointer path.
- */
+/** Set a value at a JSON Pointer path. */
 export function setValueAtPath(
   obj: unknown,
   pointer: string,
@@ -92,11 +106,12 @@ export function setValueAtPath(
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
-      const index = parseInt(segment, 10);
-      current = current[index];
+      current = current[parseInt(segment, 10)];
     } else {
       current = (current as Record<string, unknown>)[segment];
     }
@@ -104,27 +119,23 @@ export function setValueAtPath(
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot set value at path ${pointer}: parent is not an object`,
     );
   }
 
   if (Array.isArray(current)) {
-    const index =
-      lastSegment === "-" ? current.length : parseInt(lastSegment, 10);
     if (lastSegment === "-") {
       current.push(value);
     } else {
-      current[index] = value;
+      current[parseInt(lastSegment, 10)] = value;
     }
   } else {
     (current as Record<string, unknown>)[lastSegment] = value;
   }
 }
 
-/**
- * Remove a value at a JSON Pointer path.
- */
+/** Remove a value at a JSON Pointer path. */
 export function removeValueAtPath(obj: unknown, pointer: string): void {
   const segments = parseJsonPointer(pointer);
   if (segments.length === 0) {
@@ -136,7 +147,9 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
       current = current[parseInt(segment, 10)];
@@ -147,15 +160,28 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot remove at path ${pointer}: parent is not an object`,
     );
   }
 
+  // RFC 6902 §4.2: the target location MUST exist.
   if (Array.isArray(current)) {
-    current.splice(parseInt(lastSegment, 10), 1);
+    const index = parseInt(lastSegment, 10);
+    if (Number.isNaN(index) || index < 0 || index >= current.length) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing index '${lastSegment}'`,
+      );
+    }
+    current.splice(index, 1);
   } else {
-    delete (current as Record<string, unknown>)[lastSegment];
+    const record = current as Record<string, unknown>;
+    if (!Object.prototype.hasOwnProperty.call(record, lastSegment)) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing key '${lastSegment}'`,
+      );
+    }
+    delete record[lastSegment];
   }
 }
 
@@ -163,9 +189,7 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
 // Patch Operations
 // ============================================================================
 
-/**
- * Apply a single JSON Patch operation.
- */
+/** Apply a single JSON Patch operation (mutates `obj` in place). */
 export function applyOperation(
   obj: unknown,
   operation: JsonPatchOperation,
@@ -177,14 +201,24 @@ export function applyOperation(
     case "remove":
       removeValueAtPath(obj, operation.path);
       break;
-    case "replace":
-      // For replace, the path must exist
-      getValueAtPath(obj, operation.path); // throws if doesn't exist
+    case "replace": {
+      const existing = getValueAtPath(obj, operation.path);
+      if (existing === undefined) {
+        throw new StaleTargetError(
+          `JSON pointer ${operation.path} does not exist`,
+        );
+      }
       setValueAtPath(obj, operation.path, operation.value);
       break;
+    }
     case "move": {
       if (!operation.from) throw new Error("move operation requires 'from'");
       const moveValue = getValueAtPath(obj, operation.from);
+      if (moveValue === undefined) {
+        throw new StaleTargetError(
+          `Cannot move from path ${operation.from}: not an object`,
+        );
+      }
       removeValueAtPath(obj, operation.from);
       setValueAtPath(obj, operation.path, moveValue);
       break;
@@ -213,9 +247,7 @@ export function applyOperation(
   }
 }
 
-/**
- * Apply a JSON Patch to an object (mutates in place).
- */
+/** Apply a JSON Patch to an object (mutates in place). */
 export function applyPatch(obj: unknown, patch: JsonPatch): void {
   for (const operation of patch) {
     applyOperation(obj, operation);
@@ -223,84 +255,25 @@ export function applyPatch(obj: unknown, patch: JsonPatch): void {
 }
 
 /**
- * Whether a per-operation failure is caused by the target location being
- * absent from the spec (i.e. vendor spec drift — the operation/schema the
- * patch targets was renamed or removed upstream) as opposed to a malformed
- * patch. Stale targets are skipped with a warning rather than aborting the
- * whole generate; a patch that only adds an error response to an operation
- * that no longer exists is harmless to drop.
+ * Whether a per-operation failure is a {@link StaleTargetError} (the
+ * operation/shape the patch targets was renamed or removed upstream) as
+ * opposed to a malformed patch. Accepts the thrown value or its message.
+ * Convert fails the run on these by default (`onStalePatch: "fail"`);
+ * `"warn"` restores skip-and-continue.
  */
-function isStaleTargetError(message: string): boolean {
+export function isStaleTargetError(error: unknown): boolean {
+  if (error instanceof StaleTargetError) return true;
+  const message =
+    typeof error === "string"
+      ? error
+      : error instanceof Error
+        ? error.message
+        : "";
   return (
     message.includes("not an object") ||
-    message.includes("parent is not an object")
+    message.includes("parent is not an object") ||
+    message.includes("missing key") ||
+    message.includes("missing index") ||
+    message.includes("does not exist")
   );
 }
-
-/**
- * Load and apply all patches from a directory.
- * Finds all *.patch.json files and applies them.
- *
- * Each operation within a patch file is applied independently. Operations
- * whose target path no longer exists in the spec (vendor spec drift) are
- * collected as `skipped` warnings and do not abort generation. Only genuine
- * failures (malformed JSON, invalid pointers, failed `test` ops) are reported
- * as `errors`.
- */
-export function applyAllPatches(
-  spec: unknown,
-  patchDir: string,
-): { applied: string[]; skipped: string[]; errors: string[] } {
-  const applied: string[] = [];
-  const skipped: string[] = [];
-  const errors: string[] = [];
-
-  if (!fs.existsSync(patchDir)) {
-    return { applied, skipped, errors };
-  }
-
-  // Find all .patch.json files
-  const files = fs
-    .readdirSync(patchDir)
-    .filter((f) => f.endsWith(".patch.json"))
-    .sort(); // Sort for deterministic application order
-
-  for (const file of files) {
-    const filePath = path.join(patchDir, file);
-    let patchFile: PatchFile;
-    try {
-      const content = fs.readFileSync(filePath, "utf-8");
-      patchFile = JSON.parse(content);
-    } catch (error) {
-      errors.push(
-        `${file}: ${error instanceof Error ? error.message : String(error)}`,
-      );
-      continue;
-    }
-
-    let appliedAny = false;
-    for (const operation of patchFile.patches) {
-      try {
-        applyOperation(spec, operation);
-        appliedAny = true;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (isStaleTargetError(message)) {
-          skipped.push(
-            `${file} [${operation.op} ${operation.path}]: ${message}`,
-          );
-        } else {
-          errors.push(
-            `${file} [${operation.op} ${operation.path}]: ${message}`,
-          );
-        }
-      }
-    }
-
-    if (appliedAny) {
-      applied.push(`${file}: ${patchFile.description}`);
-    }
-  }
-
-  return { applied, skipped, errors };
-}