@gleanql/codegen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Liljengard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @gleanql/codegen
+
+The schema generator for [GleanQL](https://github.com/gleanql/gleanql) — GraphQL
+without writing GraphQL. From a GraphQL schema (SDL or introspection) it
+generates:
+
+- the **schema model** the compiler and runtime share,
+- **branded TypeScript types** for every schema type — so API drift (a
+  removed field, a tightened nullability) becomes a type error in your
+  components,
+- the typed **`glean` accessor** your components read from.
+
+You normally don't install this directly — the
+[`@gleanql/vite`](https://github.com/gleanql/gleanql/tree/main/packages/vite)
+plugin runs it on every build from your `schema.graphql`.
+
+## Docs
+
+Full documentation lives in the [GleanQL repo](https://github.com/gleanql/gleanql).
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,119 @@
+//#region src/introspection.d.ts
+/**
+ * GraphQL introspection model + type-ref helpers.
+ *
+ * We consume the standard introspection result (`data.__schema`) directly rather
+ * than depend on graphql-js at runtime — the shape is stable and small. These
+ * structural types match what `introspectionFromSchema()` produces, so a real
+ * introspection drops straight in.
+ */
+type IntrospectionTypeKind = "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT" | "LIST" | "NON_NULL";
+type IntrospectionTypeRef = {
+  readonly kind: "NON_NULL";
+  readonly ofType: IntrospectionTypeRef;
+} | {
+  readonly kind: "LIST";
+  readonly ofType: IntrospectionTypeRef;
+} | {
+  readonly kind: "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT";
+  readonly name: string;
+  readonly ofType?: null;
+};
+interface IntrospectionInputValue {
+  readonly name: string;
+  readonly type: IntrospectionTypeRef;
+  readonly defaultValue?: string | null;
+}
+interface IntrospectionField {
+  readonly name: string;
+  readonly args: readonly IntrospectionInputValue[];
+  readonly type: IntrospectionTypeRef;
+}
+interface IntrospectionType {
+  readonly kind: IntrospectionTypeKind;
+  readonly name: string;
+  readonly description?: string | null;
+  readonly fields?: readonly IntrospectionField[] | null;
+  readonly inputFields?: readonly IntrospectionInputValue[] | null;
+  readonly interfaces?: readonly IntrospectionTypeRef[] | null;
+  readonly enumValues?: ReadonlyArray<{
+    readonly name: string;
+  }> | null;
+  readonly possibleTypes?: readonly IntrospectionTypeRef[] | null;
+}
+interface IntrospectionSchema {
+  readonly queryType: {
+    readonly name: string;
+  };
+  readonly mutationType?: {
+    readonly name: string;
+  } | null;
+  readonly subscriptionType?: {
+    readonly name: string;
+  } | null;
+  readonly types: readonly IntrospectionType[];
+}
+/** The named type at the bottom of a (possibly list/non-null) type ref. */
+declare function namedTypeName(ref: IntrospectionTypeRef): string;
+/** True if a LIST appears anywhere in the type ref. */
+declare function isListType(ref: IntrospectionTypeRef): boolean;
+/** True if the outermost wrapper is NON_NULL. */
+declare function isNonNull(ref: IntrospectionTypeRef): boolean;
+/** Render a GraphQL SDL type ref string, e.g. `[Product!]!`. */
+declare function renderGraphQLType(ref: IntrospectionTypeRef): string;
+/** Introspection meta types (`__Schema`, `__Type`, …) we never generate. */
+declare function isInternalType(name: string): boolean;
+//#endregion
+//#region src/schema-model.d.ts
+interface GenerateSchemaModelOptions {
+  /** Exported const name for the SchemaModel. Default: `schema`. */
+  readonly exportName?: string;
+}
+declare function generateSchemaModel(schema: IntrospectionSchema, options?: GenerateSchemaModelOptions): string;
+//#endregion
+//#region src/ts-render.d.ts
+/** Shared TypeScript-type rendering for branded types and the graph accessors. */
+declare const DEFAULT_SCALAR_TYPES: Record<string, string>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Generate branded TypeScript types from introspection.
+ *
+ * To app code these read as ordinary schema types (`Product`, `Image`, …); the
+ * compiler recognizes them via the `__typename` brand. Nullability, lists,
+ * callable fields (field arguments), enums, interfaces, unions and input objects
+ * all surface — so TypeScript catches API drift (a removed/renamed field, a
+ * tightened nullability) at compile time.
+ */
+interface GenerateTypesOptions {
+  /** TS type for each GraphQL scalar. Unlisted custom scalars default to `string`. */
+  readonly scalarTypes?: Record<string, string>;
+}
+declare function generateTypes(schema: IntrospectionSchema, options?: GenerateTypesOptions): string;
+//#endregion
+//#region src/graph.d.ts
+/**
+ * Generate the `graph` accessor object: one method per Query root field plus the
+ * `components(...)` registry helper. At build time the compiler reads these to
+ * learn the root fields and their types; at runtime they are backed by the
+ * runtime's bound graph (see `@gleanql/react`'s `bindGraph`). The generated bodies
+ * are typed stubs — the real values are proxies.
+ */
+interface GenerateGraphOptions {
+  readonly scalarTypes?: Record<string, string>;
+  /** Import path for the generated branded types. Default: `./schema.js`. */
+  readonly schemaImportPath?: string;
+}
+declare function generateGraph(schema: IntrospectionSchema, options?: GenerateGraphOptions): string;
+//#endregion
+//#region src/index.d.ts
+interface GeneratedSchemaPackage {
+  readonly schemaModel: string;
+  readonly types: string;
+  readonly graph: string;
+}
+interface GenerateSchemaPackageOptions extends GenerateSchemaModelOptions, GenerateTypesOptions, GenerateGraphOptions {}
+/** Generate all three source files from an introspection schema. */
+declare function generateSchemaPackage(schema: IntrospectionSchema, options?: GenerateSchemaPackageOptions): GeneratedSchemaPackage;
+//#endregion
+export { DEFAULT_SCALAR_TYPES, GenerateGraphOptions, GenerateSchemaModelOptions, GenerateSchemaPackageOptions, GenerateTypesOptions, GeneratedSchemaPackage, IntrospectionField, IntrospectionInputValue, IntrospectionSchema, IntrospectionType, IntrospectionTypeKind, IntrospectionTypeRef, generateGraph, generateSchemaModel, generateSchemaPackage, generateTypes, isInternalType, isListType, isNonNull, namedTypeName, renderGraphQLType };

package/dist/index.mjs

@@ -0,0 +1,243 @@
+//#region src/introspection.ts
+/** The named type at the bottom of a (possibly list/non-null) type ref. */
+function namedTypeName(ref) {
+	let cur = ref;
+	while (cur.kind === "LIST" || cur.kind === "NON_NULL") cur = cur.ofType;
+	return cur.name;
+}
+/** True if a LIST appears anywhere in the type ref. */
+function isListType(ref) {
+	let cur = ref;
+	while (cur.kind === "LIST" || cur.kind === "NON_NULL") {
+		if (cur.kind === "LIST") return true;
+		cur = cur.ofType;
+	}
+	return false;
+}
+/** True if the outermost wrapper is NON_NULL. */
+function isNonNull(ref) {
+	return ref.kind === "NON_NULL";
+}
+/** Render a GraphQL SDL type ref string, e.g. `[Product!]!`. */
+function renderGraphQLType(ref) {
+	switch (ref.kind) {
+		case "NON_NULL": return `${renderGraphQLType(ref.ofType)}!`;
+		case "LIST": return `[${renderGraphQLType(ref.ofType)}]`;
+		default: return ref.name;
+	}
+}
+/** Introspection meta types (`__Schema`, `__Type`, …) we never generate. */
+function isInternalType(name) {
+	return name.startsWith("__");
+}
+//#endregion
+//#region src/ts-render.ts
+/** Shared TypeScript-type rendering for branded types and the graph accessors. */
+const DEFAULT_SCALAR_TYPES = {
+	String: "string",
+	ID: "string",
+	Int: "number",
+	Float: "number",
+	Boolean: "boolean"
+};
+/** Render a TS type from a GraphQL type ref, honoring list + nullability nesting. */
+function renderTs(ref, scalars) {
+	if (ref.kind === "NON_NULL") return renderTsInner(ref.ofType, scalars);
+	return `${renderTsInner(ref, scalars)} | null`;
+}
+function renderTsInner(ref, scalars) {
+	if (ref.kind === "NON_NULL") return renderTsInner(ref.ofType, scalars);
+	if (ref.kind === "LIST") {
+		const el = renderTs(ref.ofType, scalars);
+		return `${el.includes(" ") ? `(${el})` : el}[]`;
+	}
+	if (ref.kind === "SCALAR") return scalars[ref.name] ?? "string";
+	return ref.name;
+}
+/** A bare property key when safe, else a quoted key. */
+function propKey(name) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/** Indent every non-empty line of `text` by `spaces` columns. */
+function indent(text, spaces) {
+	const pad = " ".repeat(spaces);
+	return text.split("\n").map((line) => line ? pad + line : line).join("\n");
+}
+//#endregion
+//#region src/schema-model.ts
+/**
+* Generate the `SchemaModel` source (`defineSchema({...})`) the compiler and
+* runtime consume. This is the machine-generated equivalent of the previously
+* hand-authored `schema-model.ts`.
+*/
+const KIND_MAP = {
+	SCALAR: "scalar",
+	OBJECT: "object",
+	INTERFACE: "interface",
+	UNION: "union",
+	ENUM: "enum",
+	INPUT_OBJECT: "input"
+};
+function generateSchemaModel(schema, options = {}) {
+	const exportName = options.exportName ?? "schema";
+	const types = schema.types.filter((t) => !isInternalType(t.name)).map((t) => renderType(t)).filter((s) => s !== void 0);
+	const lines = [];
+	lines.push(`import { defineSchema, type SchemaModel } from "@gleanql/core";`);
+	lines.push("");
+	lines.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+	lines.push(`export const ${exportName}: SchemaModel = defineSchema({`);
+	lines.push(`  queryType: ${JSON.stringify(schema.queryType.name)},`);
+	if (schema.mutationType) lines.push(`  mutationType: ${JSON.stringify(schema.mutationType.name)},`);
+	if (schema.subscriptionType) lines.push(`  subscriptionType: ${JSON.stringify(schema.subscriptionType.name)},`);
+	lines.push(`  types: [`);
+	for (const t of types) lines.push(indent(t, 4) + ",");
+	lines.push(`  ],`);
+	lines.push(`});`);
+	return lines.join("\n") + "\n";
+}
+function renderType(type) {
+	const kind = KIND_MAP[type.kind];
+	if (!kind) return void 0;
+	const parts = [`name: ${JSON.stringify(type.name)}`, `kind: ${JSON.stringify(kind)}`];
+	if ((type.kind === "OBJECT" || type.kind === "INTERFACE") && type.fields) {
+		const fields = type.fields.map((f) => `${propKey(f.name)}: ${renderField(f)}`);
+		parts.push(`fields: { ${fields.join(", ")} }`);
+	}
+	if (type.kind === "UNION" && type.possibleTypes) {
+		const names = type.possibleTypes.map((p) => JSON.stringify(namedTypeName(p)));
+		parts.push(`possibleTypes: [${names.join(", ")}]`);
+	}
+	return `{ ${parts.join(", ")} }`;
+}
+function renderField(field) {
+	const parts = [`name: ${JSON.stringify(field.name)}`, `type: ${JSON.stringify(namedTypeName(field.type))}`];
+	if (isListType(field.type)) parts.push(`list: true`);
+	if (isNonNull(field.type)) parts.push(`nonNull: true`);
+	if (field.args.length > 0) {
+		const args = field.args.map((a) => `{ name: ${JSON.stringify(a.name)}, type: ${JSON.stringify(renderGraphQLType(a.type))} }`);
+		parts.push(`args: [${args.join(", ")}]`);
+	}
+	return `{ ${parts.join(", ")} }`;
+}
+//#endregion
+//#region src/types.ts
+function generateTypes(schema, options = {}) {
+	const ctx = { scalars: {
+		...DEFAULT_SCALAR_TYPES,
+		...options.scalarTypes
+	} };
+	const blocks = [];
+	blocks.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+	for (const type of schema.types) {
+		if (isInternalType(type.name) || type.kind === "SCALAR") continue;
+		const block = renderTypeBlock(type, ctx);
+		if (block) blocks.push(block);
+	}
+	return blocks.join("\n\n") + "\n";
+}
+function renderTypeBlock(type, ctx) {
+	switch (type.kind) {
+		case "OBJECT": return renderObjectLike(type, ctx, JSON.stringify(type.name));
+		case "INTERFACE": return renderObjectLike(type, ctx, typenameUnionOf(type));
+		case "UNION": return renderUnion(type);
+		case "ENUM": return renderEnum(type);
+		case "INPUT_OBJECT": return renderInputObject(type, ctx);
+		default: return;
+	}
+}
+/** An interface's `__typename` is the union of its possible types; an object's is its own name. */
+function typenameUnionOf(type) {
+	return type.possibleTypes && type.possibleTypes.length > 0 ? type.possibleTypes.map((p) => JSON.stringify(namedTypeName(p))).join(" | ") : "string";
+}
+function renderObjectLike(type, ctx, typenameTs) {
+	const members = [`  __typename: ${typenameTs};`];
+	for (const field of type.fields ?? []) members.push("  " + renderFieldMember(field.name, field.args, field.type, ctx));
+	return `export interface ${type.name} {\n${members.join("\n")}\n}`;
+}
+function renderUnion(type) {
+	const members = (type.possibleTypes ?? []).map((p) => namedTypeName(p));
+	const body = members.length > 0 ? members.join(" | ") : "never";
+	return `export type ${type.name} = ${body};`;
+}
+function renderEnum(type) {
+	const values = (type.enumValues ?? []).map((v) => JSON.stringify(v.name));
+	const body = values.length > 0 ? values.join(" | ") : "never";
+	return `export type ${type.name} = ${body};`;
+}
+function renderInputObject(type, ctx) {
+	const members = (type.inputFields ?? []).map((f) => "  " + renderInputMember(f, ctx));
+	return `export interface ${type.name} {\n${members.join("\n")}\n}`;
+}
+/** A field is callable when it declares arguments; otherwise it is a property. */
+function renderFieldMember(name, args, type, ctx) {
+	const ret = renderTs(type, ctx.scalars);
+	if (args.length > 0) {
+		const argList = args.map((a) => renderInputMember(a, ctx)).join(" ");
+		return `${propKey(name)}(args: { ${argList} }): ${ret};`;
+	}
+	return `${propKey(name)}: ${ret};`;
+}
+function renderInputMember(input, ctx) {
+	const optional = input.type.kind !== "NON_NULL";
+	return `${propKey(input.name)}${optional ? "?" : ""}: ${renderTs(input.type, ctx.scalars)};`;
+}
+//#endregion
+//#region src/graph.ts
+function generateGraph(schema, options = {}) {
+	const scalars = {
+		...DEFAULT_SCALAR_TYPES,
+		...options.scalarTypes
+	};
+	const schemaImportPath = options.schemaImportPath ?? "./schema.js";
+	const rootFields = schema.types.find((t) => t.name === schema.queryType.name)?.fields ?? [];
+	const emitted = /* @__PURE__ */ new Map();
+	for (const t of schema.types) if (!isInternalType(t.name) && t.kind !== "SCALAR") emitted.set(t.name, t.kind);
+	const imports = /* @__PURE__ */ new Set();
+	const collect = (ref) => {
+		const name = namedTypeName(ref);
+		if (emitted.has(name)) imports.add(name);
+	};
+	for (const field of rootFields) {
+		collect(field.type);
+		for (const arg of field.args) collect(arg.type);
+	}
+	const lines = [];
+	lines.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+	if (imports.size > 0) {
+		const names = [...imports].sort().join(", ");
+		lines.push(`import type { ${names} } from ${JSON.stringify(schemaImportPath)};`);
+		lines.push("");
+	}
+	lines.push(`export const glean = {`);
+	for (const field of rootFields) lines.push(indent(renderRoot(field, scalars), 2));
+	lines.push(`  components<T extends Record<string, unknown>>(map: T): T {`);
+	lines.push(`    return map;`);
+	lines.push(`  },`);
+	lines.push(`};`);
+	return lines.join("\n") + "\n";
+}
+function renderRoot(field, scalars) {
+	const ret = renderTs(field.type, scalars);
+	const params = field.args.length > 0 ? `args: { ${field.args.map((a) => renderArg(a.name, a.type, scalars)).join(" ")} }` : "";
+	return [
+		`${propKey(field.name)}(${params}): ${ret} {`,
+		`  return undefined as unknown as ${ret};`,
+		`},`
+	].join("\n");
+}
+function renderArg(name, type, scalars) {
+	const optional = type.kind !== "NON_NULL";
+	return `${propKey(name)}${optional ? "?" : ""}: ${renderTs(type, scalars)};`;
+}
+//#endregion
+//#region src/index.ts
+/** Generate all three source files from an introspection schema. */
+function generateSchemaPackage(schema, options = {}) {
+	return {
+		schemaModel: generateSchemaModel(schema, options),
+		types: generateTypes(schema, options),
+		graph: generateGraph(schema, options)
+	};
+}
+//#endregion
+export { DEFAULT_SCALAR_TYPES, generateGraph, generateSchemaModel, generateSchemaPackage, generateTypes, isInternalType, isListType, isNonNull, namedTypeName, renderGraphQLType };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@gleanql/codegen",
+  "version": "0.1.0",
+  "description": "Glean's schema codegen: introspection to schema model, branded types and graph accessors",
+  "license": "MIT",
+  "author": "Alexander Liljengard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gleanql/gleanql.git",
+    "directory": "packages/codegen"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gleanql/core": "0.1.0"
+  },
+  "homepage": "https://gleanql.com",
+  "bugs": "https://github.com/gleanql/gleanql/issues",
+  "keywords": [
+    "graphql",
+    "codegen",
+    "typescript",
+    "introspection"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts.eager"
+  }
+}

package/src/graph.ts

@@ -0,0 +1,78 @@
+import {
+  isInternalType,
+  namedTypeName,
+  type IntrospectionField,
+  type IntrospectionSchema,
+  type IntrospectionTypeRef,
+} from "./introspection.js";
+import { DEFAULT_SCALAR_TYPES, indent, propKey, renderTs } from "./ts-render.js";
+
+/**
+ * Generate the `graph` accessor object: one method per Query root field plus the
+ * `components(...)` registry helper. At build time the compiler reads these to
+ * learn the root fields and their types; at runtime they are backed by the
+ * runtime's bound graph (see `@gleanql/react`'s `bindGraph`). The generated bodies
+ * are typed stubs — the real values are proxies.
+ */
+
+export interface GenerateGraphOptions {
+  readonly scalarTypes?: Record<string, string>;
+  /** Import path for the generated branded types. Default: `./schema.js`. */
+  readonly schemaImportPath?: string;
+}
+
+export function generateGraph(schema: IntrospectionSchema, options: GenerateGraphOptions = {}): string {
+  const scalars = { ...DEFAULT_SCALAR_TYPES, ...options.scalarTypes };
+  const schemaImportPath = options.schemaImportPath ?? "./schema.js";
+
+  const queryType = schema.types.find((t) => t.name === schema.queryType.name);
+  const rootFields = queryType?.fields ?? [];
+
+  // Which named types are emitted in schema.ts (so we can import them).
+  const emitted = new Map<string, string>();
+  for (const t of schema.types) {
+    if (!isInternalType(t.name) && t.kind !== "SCALAR") emitted.set(t.name, t.kind);
+  }
+
+  const imports = new Set<string>();
+  const collect = (ref: IntrospectionTypeRef): void => {
+    const name = namedTypeName(ref);
+    if (emitted.has(name)) imports.add(name);
+  };
+  for (const field of rootFields) {
+    collect(field.type);
+    for (const arg of field.args) collect(arg.type);
+  }
+
+  const lines: string[] = [];
+  lines.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+  if (imports.size > 0) {
+    const names = [...imports].sort().join(", ");
+    lines.push(`import type { ${names} } from ${JSON.stringify(schemaImportPath)};`);
+    lines.push("");
+  }
+  lines.push(`export const glean = {`);
+  for (const field of rootFields) {
+    lines.push(indent(renderRoot(field, scalars), 2));
+  }
+  lines.push(`  components<T extends Record<string, unknown>>(map: T): T {`);
+  lines.push(`    return map;`);
+  lines.push(`  },`);
+  lines.push(`};`);
+  return lines.join("\n") + "\n";
+}
+
+function renderRoot(field: IntrospectionField, scalars: Record<string, string>): string {
+  const ret = renderTs(field.type, scalars);
+  const params = field.args.length > 0 ? `args: { ${field.args.map((a) => renderArg(a.name, a.type, scalars)).join(" ")} }` : "";
+  return [
+    `${propKey(field.name)}(${params}): ${ret} {`,
+    `  return undefined as unknown as ${ret};`,
+    `},`,
+  ].join("\n");
+}
+
+function renderArg(name: string, type: IntrospectionTypeRef, scalars: Record<string, string>): string {
+  const optional = type.kind !== "NON_NULL";
+  return `${propKey(name)}${optional ? "?" : ""}: ${renderTs(type, scalars)};`;
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import type { IntrospectionSchema } from "./introspection.js";
+import { generateSchemaModel, type GenerateSchemaModelOptions } from "./schema-model.js";
+import { generateTypes, type GenerateTypesOptions } from "./types.js";
+import { generateGraph, type GenerateGraphOptions } from "./graph.js";
+
+/**
+ * `@gleanql/codegen` — generate a schema package from GraphQL introspection.
+ *
+ * The brief: "Generate a schema package from GraphQL introspection when the API
+ * changes." This produces the three files the rest of the system consumes —
+ * machine-generated equivalents of what was previously hand-authored:
+ *
+ *   schema-model.ts  the SchemaModel the compiler + runtime read
+ *   schema.ts        branded TS types (so TypeScript catches API drift)
+ *   graph.ts         the `graph.product(...)` accessors + `components(...)`
+ *
+ * Consume a real introspection result (`introspectionFromSchema(schema).__schema`
+ * or the `data.__schema` from an introspection query).
+ */
+export * from "./introspection.js";
+export * from "./schema-model.js";
+export * from "./types.js";
+export * from "./graph.js";
+
+export interface GeneratedSchemaPackage {
+  readonly schemaModel: string;
+  readonly types: string;
+  readonly graph: string;
+}
+
+export interface GenerateSchemaPackageOptions
+  extends GenerateSchemaModelOptions,
+    GenerateTypesOptions,
+    GenerateGraphOptions {}
+
+/** Generate all three source files from an introspection schema. */
+export function generateSchemaPackage(
+  schema: IntrospectionSchema,
+  options: GenerateSchemaPackageOptions = {},
+): GeneratedSchemaPackage {
+  return {
+    schemaModel: generateSchemaModel(schema, options),
+    types: generateTypes(schema, options),
+    graph: generateGraph(schema, options),
+  };
+}

package/src/introspection.ts

@@ -0,0 +1,84 @@
+/**
+ * GraphQL introspection model + type-ref helpers.
+ *
+ * We consume the standard introspection result (`data.__schema`) directly rather
+ * than depend on graphql-js at runtime — the shape is stable and small. These
+ * structural types match what `introspectionFromSchema()` produces, so a real
+ * introspection drops straight in.
+ */
+
+export type IntrospectionTypeKind = "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT" | "LIST" | "NON_NULL";
+
+export type IntrospectionTypeRef =
+  | { readonly kind: "NON_NULL"; readonly ofType: IntrospectionTypeRef }
+  | { readonly kind: "LIST"; readonly ofType: IntrospectionTypeRef }
+  | { readonly kind: "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT"; readonly name: string; readonly ofType?: null };
+
+export interface IntrospectionInputValue {
+  readonly name: string;
+  readonly type: IntrospectionTypeRef;
+  readonly defaultValue?: string | null;
+}
+
+export interface IntrospectionField {
+  readonly name: string;
+  readonly args: readonly IntrospectionInputValue[];
+  readonly type: IntrospectionTypeRef;
+}
+
+export interface IntrospectionType {
+  readonly kind: IntrospectionTypeKind;
+  readonly name: string;
+  readonly description?: string | null;
+  readonly fields?: readonly IntrospectionField[] | null;
+  readonly inputFields?: readonly IntrospectionInputValue[] | null;
+  readonly interfaces?: readonly IntrospectionTypeRef[] | null;
+  readonly enumValues?: ReadonlyArray<{ readonly name: string }> | null;
+  readonly possibleTypes?: readonly IntrospectionTypeRef[] | null;
+}
+
+export interface IntrospectionSchema {
+  readonly queryType: { readonly name: string };
+  readonly mutationType?: { readonly name: string } | null;
+  readonly subscriptionType?: { readonly name: string } | null;
+  readonly types: readonly IntrospectionType[];
+}
+
+/** The named type at the bottom of a (possibly list/non-null) type ref. */
+export function namedTypeName(ref: IntrospectionTypeRef): string {
+  let cur: IntrospectionTypeRef = ref;
+  while (cur.kind === "LIST" || cur.kind === "NON_NULL") cur = cur.ofType;
+  return cur.name;
+}
+
+/** True if a LIST appears anywhere in the type ref. */
+export function isListType(ref: IntrospectionTypeRef): boolean {
+  let cur: IntrospectionTypeRef = ref;
+  while (cur.kind === "LIST" || cur.kind === "NON_NULL") {
+    if (cur.kind === "LIST") return true;
+    cur = cur.ofType;
+  }
+  return false;
+}
+
+/** True if the outermost wrapper is NON_NULL. */
+export function isNonNull(ref: IntrospectionTypeRef): boolean {
+  return ref.kind === "NON_NULL";
+}
+
+/** Render a GraphQL SDL type ref string, e.g. `[Product!]!`. */
+export function renderGraphQLType(ref: IntrospectionTypeRef): string {
+  switch (ref.kind) {
+    case "NON_NULL":
+      return `${renderGraphQLType(ref.ofType)}!`;
+    case "LIST":
+      return `[${renderGraphQLType(ref.ofType)}]`;
+    default:
+      return ref.name;
+  }
+}
+
+/** Introspection meta types (`__Schema`, `__Type`, …) we never generate. */
+export function isInternalType(name: string): boolean {
+  return name.startsWith("__");
+}

package/src/schema-model.ts

@@ -0,0 +1,81 @@
+import {
+  isInternalType,
+  isListType,
+  isNonNull,
+  namedTypeName,
+  renderGraphQLType,
+  type IntrospectionField,
+  type IntrospectionSchema,
+  type IntrospectionType,
+} from "./introspection.js";
+import { indent, propKey } from "./ts-render.js";
+
+/**
+ * Generate the `SchemaModel` source (`defineSchema({...})`) the compiler and
+ * runtime consume. This is the machine-generated equivalent of the previously
+ * hand-authored `schema-model.ts`.
+ */
+
+const KIND_MAP: Record<string, string> = {
+  SCALAR: "scalar",
+  OBJECT: "object",
+  INTERFACE: "interface",
+  UNION: "union",
+  ENUM: "enum",
+  INPUT_OBJECT: "input",
+};
+
+export interface GenerateSchemaModelOptions {
+  /** Exported const name for the SchemaModel. Default: `schema`. */
+  readonly exportName?: string;
+}
+
+export function generateSchemaModel(schema: IntrospectionSchema, options: GenerateSchemaModelOptions = {}): string {
+  const exportName = options.exportName ?? "schema";
+  const types = schema.types
+    .filter((t) => !isInternalType(t.name))
+    .map((t) => renderType(t))
+    .filter((s): s is string => s !== undefined);
+
+  const lines: string[] = [];
+  lines.push(`import { defineSchema, type SchemaModel } from "@gleanql/core";`);
+  lines.push("");
+  lines.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+  lines.push(`export const ${exportName}: SchemaModel = defineSchema({`);
+  lines.push(`  queryType: ${JSON.stringify(schema.queryType.name)},`);
+  if (schema.mutationType) lines.push(`  mutationType: ${JSON.stringify(schema.mutationType.name)},`);
+  if (schema.subscriptionType) lines.push(`  subscriptionType: ${JSON.stringify(schema.subscriptionType.name)},`);
+  lines.push(`  types: [`);
+  for (const t of types) lines.push(indent(t, 4) + ",");
+  lines.push(`  ],`);
+  lines.push(`});`);
+  return lines.join("\n") + "\n";
+}
+
+function renderType(type: IntrospectionType): string | undefined {
+  const kind = KIND_MAP[type.kind];
+  if (!kind) return undefined; // LIST/NON_NULL never appear at top level
+
+  const parts: string[] = [`name: ${JSON.stringify(type.name)}`, `kind: ${JSON.stringify(kind)}`];
+
+  if ((type.kind === "OBJECT" || type.kind === "INTERFACE") && type.fields) {
+    const fields = type.fields.map((f) => `${propKey(f.name)}: ${renderField(f)}`);
+    parts.push(`fields: { ${fields.join(", ")} }`);
+  }
+  if (type.kind === "UNION" && type.possibleTypes) {
+    const names = type.possibleTypes.map((p) => JSON.stringify(namedTypeName(p)));
+    parts.push(`possibleTypes: [${names.join(", ")}]`);
+  }
+  return `{ ${parts.join(", ")} }`;
+}
+
+function renderField(field: IntrospectionField): string {
+  const parts: string[] = [`name: ${JSON.stringify(field.name)}`, `type: ${JSON.stringify(namedTypeName(field.type))}`];
+  if (isListType(field.type)) parts.push(`list: true`);
+  if (isNonNull(field.type)) parts.push(`nonNull: true`);
+  if (field.args.length > 0) {
+    const args = field.args.map((a) => `{ name: ${JSON.stringify(a.name)}, type: ${JSON.stringify(renderGraphQLType(a.type))} }`);
+    parts.push(`args: [${args.join(", ")}]`);
+  }
+  return `{ ${parts.join(", ")} }`;
+}

package/src/ts-render.ts

@@ -0,0 +1,41 @@
+import type { IntrospectionTypeRef } from "./introspection.js";
+
+/** Shared TypeScript-type rendering for branded types and the graph accessors. */
+
+export const DEFAULT_SCALAR_TYPES: Record<string, string> = {
+  String: "string",
+  ID: "string",
+  Int: "number",
+  Float: "number",
+  Boolean: "boolean",
+};
+
+/** Render a TS type from a GraphQL type ref, honoring list + nullability nesting. */
+export function renderTs(ref: IntrospectionTypeRef, scalars: Record<string, string>): string {
+  if (ref.kind === "NON_NULL") return renderTsInner(ref.ofType, scalars);
+  return `${renderTsInner(ref, scalars)} | null`;
+}
+
+function renderTsInner(ref: IntrospectionTypeRef, scalars: Record<string, string>): string {
+  if (ref.kind === "NON_NULL") return renderTsInner(ref.ofType, scalars);
+  if (ref.kind === "LIST") {
+    const el = renderTs(ref.ofType, scalars);
+    return `${el.includes(" ") ? `(${el})` : el}[]`;
+  }
+  if (ref.kind === "SCALAR") return scalars[ref.name] ?? "string";
+  return ref.name; // OBJECT / INTERFACE / UNION / ENUM / INPUT_OBJECT
+}
+
+/** A bare property key when safe, else a quoted key. */
+export function propKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+/** Indent every non-empty line of `text` by `spaces` columns. */
+export function indent(text: string, spaces: number): string {
+  const pad = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? pad + line : line))
+    .join("\n");
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+import {
+  isInternalType,
+  namedTypeName,
+  type IntrospectionInputValue,
+  type IntrospectionSchema,
+  type IntrospectionType,
+  type IntrospectionTypeRef,
+} from "./introspection.js";
+import { DEFAULT_SCALAR_TYPES, propKey, renderTs } from "./ts-render.js";
+
+export { DEFAULT_SCALAR_TYPES } from "./ts-render.js";
+
+/**
+ * Generate branded TypeScript types from introspection.
+ *
+ * To app code these read as ordinary schema types (`Product`, `Image`, …); the
+ * compiler recognizes them via the `__typename` brand. Nullability, lists,
+ * callable fields (field arguments), enums, interfaces, unions and input objects
+ * all surface — so TypeScript catches API drift (a removed/renamed field, a
+ * tightened nullability) at compile time.
+ */
+
+export interface GenerateTypesOptions {
+  /** TS type for each GraphQL scalar. Unlisted custom scalars default to `string`. */
+  readonly scalarTypes?: Record<string, string>;
+}
+
+export function generateTypes(schema: IntrospectionSchema, options: GenerateTypesOptions = {}): string {
+  const scalars = { ...DEFAULT_SCALAR_TYPES, ...options.scalarTypes };
+  const ctx = { scalars };
+
+  const blocks: string[] = [];
+  blocks.push(`/** Generated from GraphQL introspection. Do not edit by hand. */`);
+
+  for (const type of schema.types) {
+    if (isInternalType(type.name) || type.kind === "SCALAR") continue;
+    const block = renderTypeBlock(type, ctx);
+    if (block) blocks.push(block);
+  }
+  return blocks.join("\n\n") + "\n";
+}
+
+interface Ctx {
+  readonly scalars: Record<string, string>;
+}
+
+function renderTypeBlock(type: IntrospectionType, ctx: Ctx): string | undefined {
+  switch (type.kind) {
+    case "OBJECT":
+      return renderObjectLike(type, ctx, JSON.stringify(type.name));
+    case "INTERFACE":
+      return renderObjectLike(type, ctx, typenameUnionOf(type));
+    case "UNION":
+      return renderUnion(type);
+    case "ENUM":
+      return renderEnum(type);
+    case "INPUT_OBJECT":
+      return renderInputObject(type, ctx);
+    default:
+      return undefined;
+  }
+}
+
+/** An interface's `__typename` is the union of its possible types; an object's is its own name. */
+function typenameUnionOf(type: IntrospectionType): string {
+  return type.possibleTypes && type.possibleTypes.length > 0
+    ? type.possibleTypes.map((p) => JSON.stringify(namedTypeName(p))).join(" | ")
+    : "string";
+}
+
+function renderObjectLike(type: IntrospectionType, ctx: Ctx, typenameTs: string): string {
+  const members: string[] = [`  __typename: ${typenameTs};`];
+  for (const field of type.fields ?? []) {
+    members.push("  " + renderFieldMember(field.name, field.args, field.type, ctx));
+  }
+  return `export interface ${type.name} {\n${members.join("\n")}\n}`;
+}
+
+function renderUnion(type: IntrospectionType): string {
+  const members = (type.possibleTypes ?? []).map((p) => namedTypeName(p));
+  const body = members.length > 0 ? members.join(" | ") : "never";
+  return `export type ${type.name} = ${body};`;
+}
+
+function renderEnum(type: IntrospectionType): string {
+  const values = (type.enumValues ?? []).map((v) => JSON.stringify(v.name));
+  const body = values.length > 0 ? values.join(" | ") : "never";
+  return `export type ${type.name} = ${body};`;
+}
+
+function renderInputObject(type: IntrospectionType, ctx: Ctx): string {
+  const members = (type.inputFields ?? []).map((f) => "  " + renderInputMember(f, ctx));
+  return `export interface ${type.name} {\n${members.join("\n")}\n}`;
+}
+
+/** A field is callable when it declares arguments; otherwise it is a property. */
+function renderFieldMember(
+  name: string,
+  args: readonly IntrospectionInputValue[],
+  type: IntrospectionTypeRef,
+  ctx: Ctx,
+): string {
+  const ret = renderTs(type, ctx.scalars);
+  if (args.length > 0) {
+    const argList = args.map((a) => renderInputMember(a, ctx)).join(" ");
+    return `${propKey(name)}(args: { ${argList} }): ${ret};`;
+  }
+  return `${propKey(name)}: ${ret};`;
+}
+
+function renderInputMember(input: IntrospectionInputValue, ctx: Ctx): string {
+  const optional = input.type.kind !== "NON_NULL";
+  return `${propKey(input.name)}${optional ? "?" : ""}: ${renderTs(input.type, ctx.scalars)};`;
+}