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

package/src/codegen/spec-path.ts

@@ -0,0 +1,115 @@
+/**
+ * Spec path resolution — the seam between a production spec mirror and a
+ * local working copy of one (dev-time only).
+ *
+ * Every SDK package reads its specs from `packages/<pkg>/specs/`. In
+ * production that directory holds a submodule of the package's mirror
+ * repository, `distilled-mirror/spec-mirror-<pkg>`, whose layout is fixed:
+ *
+ *   packages/<pkg>/specs/spec-mirror-<pkg>/
+ *   ├── .meta/          fetch-specs.ts + its package.json
+ *   └── specs/          what the generator reads
+ *
+ * A contributor adding a provider cannot create that repository — it lives in
+ * an org they have no write access to, and it is only created once the
+ * `distilled-submodules` stack deploys on merge to main. So `pnpm specs:local
+ * <pkg>` runs the same `fetch-specs.ts` into a gitignored directory shaped
+ * exactly like the mirror:
+ *
+ *   packages/<pkg>/specs/.local/
+ *   ├── .meta/
+ *   └── specs/
+ *
+ * Setting {@link LOCAL_ENV} then re-roots every spec read into it. Nothing in
+ * the package's source changes — the `specPath` a `convert.ts` declares stays
+ * the production one — so there is no `.local` reference that could be
+ * committed by accident, and the switch is impossible to leave on: it lives
+ * in the environment of one command, never in a file.
+ *
+ * The opt-in is deliberate rather than a fallback-when-missing. A silent
+ * fallback would regenerate an SDK from a stale `.local` copy the moment a
+ * submodule failed to check out, and the result — committed, formatted,
+ * plausible — would be indistinguishable from a real regeneration.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Set to a non-empty value to read specs from `specs/.local` instead. */
+export const LOCAL_ENV = "DISTILLED_SPECS_LOCAL";
+
+/** The local working copy of a mirror, relative to a package root. */
+export const LOCAL_DIR = path.join("specs", ".local");
+
+/** Repository name of the mirror feeding `packages/<pkg>`. */
+export const mirrorRepositoryName = (pkg: string) => `spec-mirror-${pkg}`;
+
+/** Whether this process reads specs from `specs/.local`. */
+export const isLocalSpecs = (): boolean =>
+  (process.env[LOCAL_ENV] ?? "").trim() !== "";
+
+let announced = false;
+
+/**
+ * The path within a mirror's `specs/` directory that `specPath` names.
+ *
+ * Spec paths take one of two shapes — `specs/<mirror>/specs/<tail>` for a
+ * submodule and `specs/<tail>` for a committed file — and in both the tail is
+ * everything after the LAST `specs` segment. That one rule covers the
+ * submodule form, the committed form, the nested forms
+ * (`specs/<mirror>/specs/models/<service>/...`) and the directory form
+ * (`specs/<mirror>/specs`, whose tail is empty — the mirror's `specs/`
+ * directory itself) without needing to know which it was handed.
+ *
+ * `undefined` means there is no `specs` segment at all, which local mode
+ * cannot interpret.
+ */
+const tailWithinSpecs = (specPath: string): string | undefined => {
+  const segments = specPath.split(/[/\\]/).filter((s) => s !== "" && s !== ".");
+  const last = segments.lastIndexOf("specs");
+  if (last === -1) return undefined;
+  return segments.slice(last + 1).join(path.sep);
+};
+
+/**
+ * Resolve a package-relative spec path to an absolute one.
+ *
+ * @param root      absolute package root (`path.resolve(import.meta.dir, "..")`)
+ * @param specPath  the production path, relative to `root` (or absolute)
+ */
+export const resolveSpecPath = (root: string, specPath: string): string => {
+  const production = path.resolve(root, specPath);
+  if (!isLocalSpecs() || path.isAbsolute(specPath)) return production;
+
+  const tail = tailWithinSpecs(specPath);
+  if (tail === undefined) {
+    throw new Error(
+      `${LOCAL_ENV} is set, but "${specPath}" has no \`specs/\` segment to ` +
+        `re-root. Local mode only understands paths under the package's ` +
+        `specs/ directory.`,
+    );
+  }
+
+  if (!announced) {
+    announced = true;
+    // stderr, not stdout: generate-all captures stdout per package and only
+    // prints it on failure, and this is exactly the line you need to see on
+    // a run that succeeded against the wrong specs.
+    console.error(
+      `⚠  ${LOCAL_ENV} — reading specs from ${LOCAL_DIR}, not the mirror submodule.`,
+    );
+  }
+
+  const local = path.join(root, LOCAL_DIR, "specs", tail);
+  if (!fs.existsSync(local)) {
+    // A missing local spec is a setup mistake, not a generator bug, and the
+    // ENOENT the caller would otherwise raise names a path nobody recognises.
+    throw new Error(
+      `${local} does not exist. Materialise this package's mirror first:\n` +
+        `  pnpm specs:local ${path.basename(root)}\n` +
+        `If that succeeds and this path is still missing, the package's ` +
+        `declared spec path (${specPath}) is not mirror-shaped yet — it must ` +
+        `read \`specs/<mirror>/specs/<file>\` for local mode to find it.`,
+    );
+  }
+  return local;
+};

package/src/errors.ts

@@ -33,7 +33,7 @@ export const DurationSchema = Schema.declare<Duration.Duration>(
 /**
  * Unauthorized - Authentication failure (401).
  */
-export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
   "Unauthorized",
   { message: Schema.String },
 ).pipe(Category.withAuthError) {}
@@ -41,37 +41,35 @@ export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
 /**
  * Forbidden - Access denied (403).
  */
-export class Forbidden extends Schema.TaggedErrorClass<Forbidden>()(
-  "Forbidden",
-  { message: Schema.String },
-).pipe(Category.withAuthError) {}
+export class Forbidden extends Schema.TaggedError<Forbidden>()("Forbidden", {
+  message: Schema.String,
+}).pipe(Category.withAuthError) {}
 
 /**
  * NotFound - Resource not found (404).
  */
-export class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+export class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
   message: Schema.String,
 }).pipe(Category.withNotFoundError) {}
 
 /**
  * BadRequest - Invalid request (400).
  */
-export class BadRequest extends Schema.TaggedErrorClass<BadRequest>()(
-  "BadRequest",
-  { message: Schema.String },
-).pipe(Category.withBadRequestError) {}
+export class BadRequest extends Schema.TaggedError<BadRequest>()("BadRequest", {
+  message: Schema.String,
+}).pipe(Category.withBadRequestError) {}
 
 /**
  * Conflict - Resource conflict (409).
  */
-export class Conflict extends Schema.TaggedErrorClass<Conflict>()("Conflict", {
+export class Conflict extends Schema.TaggedError<Conflict>()("Conflict", {
   message: Schema.String,
 }).pipe(Category.withConflictError) {}
 
 /**
  * UnprocessableEntity - Validation error (422).
  */
-export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEntity>()(
+export class UnprocessableEntity extends Schema.TaggedError<UnprocessableEntity>()(
   "UnprocessableEntity",
   { message: Schema.String },
 ).pipe(Category.withBadRequestError) {}
@@ -79,7 +77,7 @@ export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEn
 /**
  * TooManyRequests - Rate limited (429).
  */
-export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
+export class TooManyRequests extends Schema.TaggedError<TooManyRequests>()(
   "TooManyRequests",
   {
     message: Schema.String,
@@ -93,7 +91,7 @@ export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
 /**
  * Locked - Resource locked (423).
  */
-export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
+export class Locked extends Schema.TaggedError<Locked>()("Locked", {
   message: Schema.String,
   retryAfter: Schema.optional(DurationSchema),
 }).pipe(Category.withLockedError, Category.withRetryable()) {}
@@ -106,7 +104,7 @@ export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
  * 200 envelope carrying `{ code: 10002, message: "An unknown error has
  * occurred" }` for transient backend failures on some endpoints).
  */
-export class InternalServerError extends Schema.TaggedErrorClass<InternalServerError>()(
+export class InternalServerError extends Schema.TaggedError<InternalServerError>()(
   "InternalServerError",
   {
     message: Schema.String,
@@ -118,18 +116,15 @@ export class InternalServerError extends Schema.TaggedErrorClass<InternalServerE
 /**
  * BadGateway - Bad gateway (502).
  */
-export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
-  "BadGateway",
-  {
-    message: Schema.String,
-    retryAfter: Schema.optional(DurationSchema),
-  },
-).pipe(Category.withServerError, Category.withRetryable()) {}
+export class BadGateway extends Schema.TaggedError<BadGateway>()("BadGateway", {
+  message: Schema.String,
+  retryAfter: Schema.optional(DurationSchema),
+}).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
  * ServiceUnavailable - Service unavailable (503).
  */
-export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailable>()(
+export class ServiceUnavailable extends Schema.TaggedError<ServiceUnavailable>()(
   "ServiceUnavailable",
   {
     message: Schema.String,
@@ -140,7 +135,7 @@ export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailab
 /**
  * GatewayTimeout - Gateway timeout (504).
  */
-export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
+export class GatewayTimeout extends Schema.TaggedError<GatewayTimeout>()(
   "GatewayTimeout",
   {
     message: Schema.String,
@@ -151,7 +146,7 @@ export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
 /**
  * Configuration error - missing or invalid configuration.
  */
-export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()(
+export class ConfigError extends Schema.TaggedError<ConfigError>()(
   "ConfigError",
   { message: Schema.String },
 ).pipe(Category.withConfigurationError) {}

package/src/graphql.fixture.ts

@@ -0,0 +1,371 @@
+import * as Schema from "effect/Schema";
+import * as G from "./graphql.ts";
+import type { GraphQLField, GraphQLModel } from "./codegen/graphql-client.ts";
+
+export class ProjectNotFound extends Schema.TaggedError<ProjectNotFound>()(
+  "ProjectNotFound",
+  G.errorFields,
+) {}
+export class ServicesUnavailable extends Schema.TaggedError<ServicesUnavailable>()(
+  "ServicesUnavailable",
+  G.errorFields,
+) {}
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
+  "Unauthorized",
+  G.errorFields,
+) {}
+export class ProjectDescriptionUnavailable extends Schema.TaggedError<ProjectDescriptionUnavailable>()(
+  "ProjectDescriptionUnavailable",
+  G.errorFields,
+) {}
+export class ServiceDescriptionUnavailable extends Schema.TaggedError<ServiceDescriptionUnavailable>()(
+  "ServiceDescriptionUnavailable",
+  G.errorFields,
+) {}
+export class PageInfoUnavailable extends Schema.TaggedError<PageInfoUnavailable>()(
+  "PageInfoUnavailable",
+  G.errorFields,
+) {}
+
+export const errorClasses = {
+  ProjectNotFound,
+  ServicesUnavailable,
+  Unauthorized,
+  ProjectDescriptionUnavailable,
+  ServiceDescriptionUnavailable,
+  PageInfoUnavailable,
+};
+
+export type FixtureSchema = {
+  query: "Query";
+  mutation: "Mutation";
+  subscription: never;
+  globalErrors: "Unauthorized";
+  errors: {
+    ProjectNotFound: ProjectNotFound;
+    ServicesUnavailable: ServicesUnavailable;
+    Unauthorized: Unauthorized;
+    ProjectDescriptionUnavailable: ProjectDescriptionUnavailable;
+    ServiceDescriptionUnavailable: ServiceDescriptionUnavailable;
+    PageInfoUnavailable: PageInfoUnavailable;
+  };
+  scalars: {
+    ID: string;
+    String: string;
+    Int: number;
+    Boolean: boolean;
+    JSON: unknown;
+    Status: "ACTIVE" | "ARCHIVED";
+  };
+  possibleTypes: {
+    Node: "Project" | "Service";
+    SearchResult: "Project" | "Service";
+  };
+  types: {
+    Query: {
+      project: G.Field<{ id: string }, "Project", "ProjectNotFound">;
+      projects: G.Field<
+        {
+          filter?: {
+            name?: string | null;
+            statuses?: Array<"ACTIVE" | "ARCHIVED"> | null;
+            metadata?: unknown;
+          } | null;
+        },
+        "[Project]!"
+      >;
+      node: G.Field<{ id: string }, "Node">;
+      search: G.Field<{ text: string }, "[SearchResult!]!">;
+      services: G.Field<
+        { first?: number | null; after?: string | null },
+        "ServiceConnection!",
+        "ServicesUnavailable"
+      >;
+      ping: G.Field<{}, "Boolean!">;
+    };
+    Mutation: {
+      editProject: G.Field<
+        { id: string; name: string },
+        "Project!",
+        "ProjectNotFound"
+      >;
+      deleteProject: G.Field<{ id: string }, "Boolean!", "ProjectNotFound">;
+    };
+    Project: {
+      id: G.Field<{}, "ID!">;
+      name: G.Field<{}, "String!">;
+      description: G.Field<{}, "String", "ProjectDescriptionUnavailable">;
+      parent: G.Field<{}, "Project">;
+      services: G.Field<
+        {
+          first?: number | null;
+          after?: string | null;
+          filter?: { name?: string | null } | null;
+        },
+        "ServiceConnection",
+        "ServicesUnavailable"
+      >;
+    };
+    Service: {
+      id: G.Field<{}, "ID!">;
+      parent: G.Field<{}, "Project">;
+      name: G.Field<{}, "String!">;
+      description: G.Field<{}, "String", "ServiceDescriptionUnavailable">;
+      project: G.Field<{}, "Project!">;
+      status: G.Field<{}, "Status!">;
+    };
+    ServiceConnection: {
+      edges: G.Field<{}, "[ServiceEdge!]!">;
+      pageInfo: G.Field<{}, "PageInfo!">;
+    };
+    ServiceEdge: {
+      cursor: G.Field<{}, "String!">;
+      node: G.Field<{}, "Service!">;
+    };
+    PageInfo: {
+      endCursor: G.Field<{}, "String">;
+      hasNextPage: G.Field<{}, "Boolean!", "PageInfoUnavailable">;
+    };
+    Node: { id: G.Field<{}, "ID!">; parent: G.Field<{}, "Project"> };
+    SearchResult: {};
+  };
+};
+
+const field = (
+  type: string,
+  args: Record<string, { type: string; defaultValue?: string }> = {},
+  errors: string[] = [],
+): GraphQLField => ({ type, args, errors });
+
+export const fixtureModel: GraphQLModel = {
+  version: 1,
+  queryType: "Query",
+  mutationType: "Mutation",
+  errors: {
+    ProjectNotFound: { matchers: [{ code: "NOT_FOUND" }] },
+    ServicesUnavailable: { matchers: [{ code: "UNAVAILABLE" }] },
+    ProjectDescriptionUnavailable: {
+      matchers: [{ code: "DESCRIPTION_UNAVAILABLE" }],
+    },
+    ServiceDescriptionUnavailable: {
+      matchers: [{ code: "DESCRIPTION_UNAVAILABLE" }],
+    },
+    PageInfoUnavailable: { matchers: [{ code: "PAGE_INFO_UNAVAILABLE" }] },
+    Unauthorized: {
+      matchers: [
+        { code: "UNAUTHENTICATED" },
+        { code: "INTERNAL_SERVER_ERROR", message: "Not Authorized" },
+      ],
+    },
+  },
+  globalErrors: ["Unauthorized"],
+  types: {
+    ID: { kind: "SCALAR", scalar: "string" },
+    String: { kind: "SCALAR", scalar: "string" },
+    Int: { kind: "SCALAR", scalar: "number" },
+    Boolean: { kind: "SCALAR", scalar: "boolean" },
+    JSON: { kind: "SCALAR", scalar: "unknown" },
+    Status: { kind: "ENUM", enumValues: ["ACTIVE", "ARCHIVED"] },
+    ProjectFilter: {
+      kind: "INPUT_OBJECT",
+      inputFields: {
+        name: { type: "String" },
+        statuses: { type: "[Status!]", defaultValue: "[ACTIVE]" },
+        metadata: { type: "JSON" },
+      },
+    },
+    Query: {
+      kind: "OBJECT",
+      fields: {
+        project: field("Project", { id: { type: "ID!" } }, ["ProjectNotFound"]),
+        projects: field("[Project]!", { filter: { type: "ProjectFilter" } }),
+        node: field("Node", { id: { type: "ID!" } }),
+        search: field("[SearchResult!]!", { text: { type: "String!" } }),
+        services: field(
+          "ServiceConnection!",
+          {
+            first: { type: "Int", defaultValue: "20" },
+            after: { type: "String" },
+          },
+          ["ServicesUnavailable"],
+        ),
+        ping: field("Boolean!"),
+      },
+    },
+    Mutation: {
+      kind: "OBJECT",
+      fields: {
+        editProject: field(
+          "Project!",
+          { id: { type: "ID!" }, name: { type: "String!" } },
+          ["ProjectNotFound"],
+        ),
+        deleteProject: field("Boolean!", { id: { type: "ID!" } }, [
+          "ProjectNotFound",
+        ]),
+      },
+    },
+    Project: {
+      kind: "OBJECT",
+      interfaces: ["Node"],
+      fields: {
+        id: field("ID!"),
+        name: field("String!"),
+        description: field("String", {}, ["ProjectDescriptionUnavailable"]),
+        parent: field("Project"),
+        services: field(
+          "ServiceConnection",
+          {
+            first: { type: "Int", defaultValue: "20" },
+            after: { type: "String" },
+            filter: { type: "ProjectFilter" },
+          },
+          ["ServicesUnavailable"],
+        ),
+      },
+    },
+    Service: {
+      kind: "OBJECT",
+      interfaces: ["Node"],
+      fields: {
+        id: field("ID!"),
+        parent: field("Project"),
+        name: field("String!"),
+        description: field("String", {}, ["ServiceDescriptionUnavailable"]),
+        project: field("Project!"),
+        status: field("Status!"),
+      },
+    },
+    ServiceConnection: {
+      kind: "OBJECT",
+      fields: { edges: field("[ServiceEdge!]!"), pageInfo: field("PageInfo!") },
+    },
+    ServiceEdge: {
+      kind: "OBJECT",
+      fields: { cursor: field("String!"), node: field("Service!") },
+    },
+    PageInfo: {
+      kind: "OBJECT",
+      fields: {
+        endCursor: field("String"),
+        hasNextPage: field("Boolean!", {}, ["PageInfoUnavailable"]),
+      },
+    },
+    Node: {
+      kind: "INTERFACE",
+      fields: { id: field("ID!"), parent: field("Project") },
+      possibleTypes: ["Project", "Service"],
+    },
+    SearchResult: { kind: "UNION", possibleTypes: ["Project", "Service"] },
+  },
+};
+
+/** A deliberately small recursive schema for GraphQL compiler/runtime tests. */
+export const fixtureSDL = /* GraphQL */ `
+  scalar JSON
+
+  enum Status {
+    ACTIVE
+    ARCHIVED
+  }
+
+  input ProjectFilter {
+    name: String
+    statuses: [Status!] = [ACTIVE]
+    metadata: JSON
+  }
+
+  interface Node {
+    id: ID!
+    parent: Project
+  }
+
+  type Project implements Node {
+    id: ID!
+    name: String!
+    description: String
+    parent: Project
+    services(
+      first: Int = 20
+      after: String
+      filter: ProjectFilter
+    ): ServiceConnection
+  }
+
+  type Service implements Node {
+    id: ID!
+    parent: Project
+    name: String!
+    description: String
+    project: Project!
+    status: Status!
+  }
+
+  type ServiceConnection {
+    edges: [ServiceEdge!]!
+    pageInfo: PageInfo!
+  }
+
+  type ServiceEdge {
+    cursor: String!
+    node: Service!
+  }
+
+  type PageInfo {
+    endCursor: String
+    hasNextPage: Boolean!
+  }
+
+  union SearchResult = Project | Service
+
+  type Query {
+    project(id: ID!): Project
+    projects(filter: ProjectFilter): [Project]!
+    node(id: ID!): Node
+    search(text: String!): [SearchResult!]!
+    services(first: Int = 20, after: String): ServiceConnection!
+    ping: Boolean!
+  }
+
+  type Mutation {
+    editProject(id: ID!, name: String!): Project!
+    deleteProject(id: ID!): Boolean!
+  }
+`;
+
+/** Includes characters that must travel in variables, never in GraphQL text. */
+export const adversarialArgument = 'quoted "value" \\ path\nline\t\u0000 😀';
+
+export const partialProjectEnvelope = {
+  data: {
+    project: { id: "p1", services: null },
+    ping: true,
+  },
+  errors: [
+    {
+      message: "Services temporarily unavailable",
+      path: ["project", "services"],
+      locations: [{ line: 1, column: 25 }],
+      extensions: { code: "UNAVAILABLE", incident: "incident-1" },
+    },
+  ],
+} as const;
+
+export const multipleErrorEnvelope = {
+  data: {
+    production: null,
+    staging: { id: "p2", services: null },
+  },
+  errors: [
+    {
+      message: "Project not found",
+      path: ["production"],
+      extensions: { code: "NOT_FOUND" },
+    },
+    {
+      message: "Services temporarily unavailable",
+      path: ["staging", "services"],
+      extensions: { code: "UNAVAILABLE" },
+    },
+  ],
+} as const;