@soda-gql/builder 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -42,6 +42,7 @@ __soda_gql_core_runtime = __toESM(__soda_gql_core_runtime);
 let __soda_gql_runtime = require("@soda-gql/runtime");
 __soda_gql_runtime = __toESM(__soda_gql_runtime);
 let __swc_core = require("@swc/core");
+let graphql = require("graphql");
 let typescript = require("typescript");
 typescript = __toESM(typescript);
 let fast_glob = require("fast-glob");
@@ -63,6 +64,7 @@ const BuilderArtifactOperationSchema = zod.z.object({
 			"subscription"
 		]),
 		operationName: zod.z.string(),
+		schemaLabel: zod.z.string(),
 		document: zod.z.unknown(),
 		variableNames: zod.z.array(zod.z.string())
 	})
@@ -71,7 +73,11 @@ const BuilderArtifactFragmentSchema = zod.z.object({
 	id: zod.z.string(),
 	type: zod.z.literal("fragment"),
 	metadata: BuilderArtifactElementMetadataSchema,
-	prebuild: zod.z.object({ typename: zod.z.string() })
+	prebuild: zod.z.object({
+		typename: zod.z.string(),
+		key: zod.z.string().optional(),
+		schemaLabel: zod.z.string()
+	})
 });
 const BuilderArtifactElementSchema = zod.z.discriminatedUnion("type", [BuilderArtifactOperationSchema, BuilderArtifactFragmentSchema]);
 const BuilderArtifactMetaSchema = zod.z.object({
@@ -387,6 +393,12 @@ const builderErrors = {
 		message: `Internal invariant violated: ${message}`,
 		context,
 		cause
+	}),
+	schemaNotFound: (schemaLabel, canonicalId) => ({
+		code: "SCHEMA_NOT_FOUND",
+		message: `Schema not found for label "${schemaLabel}" (element: ${canonicalId})`,
+		schemaLabel,
+		canonicalId
 	})
 };
 /**
@@ -473,6 +485,10 @@ const formatBuilderError = (error) => {
 				lines.push(`  Context: ${error.context}`);
 			}
 			break;
+		case "SCHEMA_NOT_FOUND":
+			lines.push(`  Schema label: ${error.schemaLabel}`);
+			lines.push(`  Element: ${error.canonicalId}`);
+			break;
 	}
 	if ("cause" in error && error.cause && !["CONFIG_INVALID"].includes(error.code)) {
 		lines.push(`  Caused by: ${error.cause}`);
@@ -1378,6 +1394,363 @@ const createGraphqlSystemIdentifyHelper = (config) => {
 	};
 };
 
+//#endregion
+//#region packages/builder/src/prebuilt/emitter.ts
+/**
+* Prebuilt types emitter.
+*
+* Generates TypeScript type definitions for PrebuiltTypes registry
+* from field selection data and schema.
+*
+* ## Error Handling Strategy
+*
+* The emitter uses a partial failure approach for type calculation errors:
+*
+* **Recoverable errors** (result in warnings, element skipped):
+* - Type calculation failures (e.g., `calculateFieldsType` throws)
+* - Input type generation failures (e.g., `generateInputType` throws)
+* - These are caught per-element, logged as warnings, and the element is omitted
+*
+* **Fatal errors** (result in error result):
+* - `SCHEMA_NOT_FOUND`: Selection references non-existent schema
+* - `WRITE_FAILED`: Cannot write output file to disk
+*
+* This allows builds to succeed with partial type coverage when some elements
+* have issues, while providing visibility into problems via warnings.
+*
+* @module
+*/
+/**
+* Group field selections by schema.
+* Uses the schemaLabel from each selection to group them correctly.
+*
+* @returns Result containing grouped selections and warnings, or error if schema not found
+*/
+const groupBySchema = (fieldSelections, schemas) => {
+	const grouped = new Map();
+	const warnings = [];
+	for (const schemaName of Object.keys(schemas)) {
+		grouped.set(schemaName, {
+			fragments: [],
+			operations: [],
+			inputObjects: new Set()
+		});
+	}
+	for (const [canonicalId, selection] of fieldSelections) {
+		const schemaName = selection.schemaLabel;
+		const schema = schemas[schemaName];
+		const group = grouped.get(schemaName);
+		if (!schema || !group) {
+			return (0, neverthrow.err)(builderErrors.schemaNotFound(schemaName, canonicalId));
+		}
+		const outputFormatters = { scalarOutput: (name) => `ScalarOutput_${schemaName}<"${name}">` };
+		const inputFormatters = {
+			scalarInput: (name) => `ScalarInput_${schemaName}<"${name}">`,
+			inputObject: (name) => `Input_${schemaName}_${name}`
+		};
+		if (selection.type === "fragment") {
+			if (!selection.key) {
+				continue;
+			}
+			try {
+				const usedInputObjects = collectUsedInputObjectsFromSpecifiers(schema, selection.variableDefinitions);
+				for (const inputName of usedInputObjects) {
+					group.inputObjects.add(inputName);
+				}
+				const outputType = (0, __soda_gql_core.calculateFieldsType)(schema, selection.fields, outputFormatters);
+				const hasVariables = Object.keys(selection.variableDefinitions).length > 0;
+				const inputType = hasVariables ? (0, __soda_gql_core.generateInputTypeFromSpecifiers)(schema, selection.variableDefinitions, { formatters: inputFormatters }) : "void";
+				group.fragments.push({
+					key: selection.key,
+					inputType,
+					outputType
+				});
+			} catch (error) {
+				warnings.push(`[prebuilt] Failed to calculate type for fragment "${selection.key}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+		} else if (selection.type === "operation") {
+			try {
+				const usedInputObjects = collectUsedInputObjects(schema, selection.variableDefinitions);
+				for (const inputName of usedInputObjects) {
+					group.inputObjects.add(inputName);
+				}
+				const outputType = (0, __soda_gql_core.calculateFieldsType)(schema, selection.fields, outputFormatters);
+				const inputType = (0, __soda_gql_core.generateInputType)(schema, selection.variableDefinitions, inputFormatters);
+				group.operations.push({
+					key: selection.operationName,
+					inputType,
+					outputType
+				});
+			} catch (error) {
+				warnings.push(`[prebuilt] Failed to calculate type for operation "${selection.operationName}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+	}
+	return (0, neverthrow.ok)({
+		grouped,
+		warnings
+	});
+};
+/**
+* Calculate relative import path from one file to another.
+*/
+const toImportSpecifier = (from, to) => {
+	const fromDir = (0, node_path.dirname)(from);
+	let relativePath = (0, node_path.relative)(fromDir, to);
+	if (!relativePath.startsWith(".")) {
+		relativePath = `./${relativePath}`;
+	}
+	return relativePath.replace(/\.ts$/, "");
+};
+/**
+* Extract input object names from a GraphQL TypeNode.
+*/
+const extractInputObjectsFromType = (schema, typeNode, inputObjects) => {
+	switch (typeNode.kind) {
+		case graphql.Kind.NON_NULL_TYPE:
+			extractInputObjectsFromType(schema, typeNode.type, inputObjects);
+			break;
+		case graphql.Kind.LIST_TYPE:
+			extractInputObjectsFromType(schema, typeNode.type, inputObjects);
+			break;
+		case graphql.Kind.NAMED_TYPE: {
+			const name = typeNode.name.value;
+			if (!schema.scalar[name] && !schema.enum[name] && schema.input[name]) {
+				inputObjects.add(name);
+			}
+			break;
+		}
+	}
+};
+/**
+* Recursively collect nested input objects from schema definitions.
+* Takes a set of initial input names and expands to include all nested inputs.
+*/
+const collectNestedInputObjects = (schema, initialInputNames) => {
+	const inputObjects = new Set(initialInputNames);
+	const collectNested = (inputName, seen) => {
+		if (seen.has(inputName)) {
+			return;
+		}
+		seen.add(inputName);
+		const inputDef = schema.input[inputName];
+		if (!inputDef) {
+			return;
+		}
+		for (const field of Object.values(inputDef.fields)) {
+			if (field.kind === "input" && !inputObjects.has(field.name)) {
+				inputObjects.add(field.name);
+				collectNested(field.name, seen);
+			}
+		}
+	};
+	for (const inputName of Array.from(initialInputNames)) {
+		collectNested(inputName, new Set());
+	}
+	return inputObjects;
+};
+/**
+* Collect all input object types used in variable definitions.
+* Recursively collects nested input objects from the schema.
+*/
+const collectUsedInputObjects = (schema, variableDefinitions) => {
+	const directInputs = new Set();
+	for (const varDef of variableDefinitions) {
+		extractInputObjectsFromType(schema, varDef.type, directInputs);
+	}
+	return collectNestedInputObjects(schema, directInputs);
+};
+/**
+* Collect all input object types used in InputTypeSpecifiers.
+* Recursively collects nested input objects from the schema.
+*/
+const collectUsedInputObjectsFromSpecifiers = (schema, specifiers) => {
+	const directInputs = new Set();
+	for (const specifier of Object.values(specifiers)) {
+		if (specifier.kind === "input" && schema.input[specifier.name]) {
+			directInputs.add(specifier.name);
+		}
+	}
+	return collectNestedInputObjects(schema, directInputs);
+};
+/**
+* Generate type definitions for input objects.
+*/
+const generateInputObjectTypeDefinitions = (schema, schemaName, inputNames) => {
+	const lines = [];
+	const defaultDepth = schema.__defaultInputDepth ?? 3;
+	const depthOverrides = schema.__inputDepthOverrides ?? {};
+	const formatters = {
+		scalarInput: (name) => `ScalarInput_${schemaName}<"${name}">`,
+		inputObject: (name) => `Input_${schemaName}_${name}`
+	};
+	const sortedNames = Array.from(inputNames).sort();
+	for (const inputName of sortedNames) {
+		const typeString = (0, __soda_gql_core.generateInputObjectType)(schema, inputName, {
+			defaultDepth,
+			depthOverrides,
+			formatters
+		});
+		lines.push(`type Input_${schemaName}_${inputName} = ${typeString};`);
+	}
+	return lines;
+};
+/**
+* Generate the TypeScript code for prebuilt types.
+*/
+const generateTypesCode = (grouped, schemas, injects, outdir) => {
+	const typesFilePath = (0, node_path.join)(outdir, "prebuilt", "types.ts");
+	const lines = [
+		"/**",
+		" * Prebuilt type registry.",
+		" *",
+		" * This file is auto-generated by @soda-gql/builder.",
+		" * Do not edit manually.",
+		" *",
+		" * @module",
+		" * @generated",
+		" */",
+		"",
+		"import type { PrebuiltTypeRegistry } from \"@soda-gql/core\";"
+	];
+	for (const [schemaName, inject] of Object.entries(injects)) {
+		const relativePath = toImportSpecifier(typesFilePath, inject.scalars);
+		lines.push(`import type { scalar as scalar_${schemaName} } from "${relativePath}";`);
+	}
+	lines.push("");
+	for (const schemaName of Object.keys(injects)) {
+		lines.push(`type ScalarInput_${schemaName}<T extends keyof typeof scalar_${schemaName}> = ` + `typeof scalar_${schemaName}[T]["$type"]["input"];`);
+		lines.push(`type ScalarOutput_${schemaName}<T extends keyof typeof scalar_${schemaName}> = ` + `typeof scalar_${schemaName}[T]["$type"]["output"];`);
+	}
+	lines.push("");
+	for (const [schemaName, { fragments, operations, inputObjects }] of grouped) {
+		const schema = schemas[schemaName];
+		if (inputObjects.size > 0 && schema) {
+			lines.push("// Input object types");
+			const inputTypeLines = generateInputObjectTypeDefinitions(schema, schemaName, inputObjects);
+			lines.push(...inputTypeLines);
+			lines.push("");
+		}
+		const fragmentEntries = fragments.sort((a, b) => a.key.localeCompare(b.key)).map((f) => `    readonly "${f.key}": { readonly input: ${f.inputType}; readonly output: ${f.outputType} };`);
+		const operationEntries = operations.sort((a, b) => a.key.localeCompare(b.key)).map((o) => `    readonly "${o.key}": { readonly input: ${o.inputType}; readonly output: ${o.outputType} };`);
+		lines.push(`export type PrebuiltTypes_${schemaName} = {`);
+		lines.push("  readonly fragments: {");
+		if (fragmentEntries.length > 0) {
+			lines.push(...fragmentEntries);
+		}
+		lines.push("  };");
+		lines.push("  readonly operations: {");
+		if (operationEntries.length > 0) {
+			lines.push(...operationEntries);
+		}
+		lines.push("  };");
+		lines.push("} satisfies PrebuiltTypeRegistry;");
+		lines.push("");
+	}
+	return lines.join("\n");
+};
+/**
+* Emit prebuilt types to the prebuilt/types.ts file.
+*
+* This function uses a partial failure strategy: if type calculation fails for
+* individual elements (e.g., due to invalid field selections or missing schema
+* types), those elements are skipped and warnings are collected rather than
+* failing the entire emission. This allows builds to succeed even when some
+* elements have issues, while still reporting problems via warnings.
+*
+* @param options - Emitter options including schemas, field selections, and output directory
+* @returns Result containing output path and warnings, or error if a hard failure occurs
+*
+* @example
+* ```typescript
+* const result = await emitPrebuiltTypes({
+*   schemas: { mySchema: schema },
+*   fieldSelections,
+*   outdir: "./generated",
+*   injects: { mySchema: { scalars: "./scalars.ts" } },
+* });
+*
+* if (result.isOk()) {
+*   console.log(`Generated: ${result.value.path}`);
+*   if (result.value.warnings.length > 0) {
+*     console.warn("Warnings:", result.value.warnings);
+*   }
+* }
+* ```
+*/
+const emitPrebuiltTypes = async (options) => {
+	const { schemas, fieldSelections, outdir, injects } = options;
+	const groupResult = groupBySchema(fieldSelections, schemas);
+	if (groupResult.isErr()) {
+		return (0, neverthrow.err)(groupResult.error);
+	}
+	const { grouped, warnings } = groupResult.value;
+	const code = generateTypesCode(grouped, schemas, injects, outdir);
+	const typesPath = (0, node_path.join)(outdir, "prebuilt", "types.ts");
+	try {
+		await (0, node_fs_promises.writeFile)(typesPath, code, "utf-8");
+		return (0, neverthrow.ok)({
+			path: typesPath,
+			warnings
+		});
+	} catch (error) {
+		return (0, neverthrow.err)(builderErrors.writeFailed(typesPath, `Failed to write prebuilt types: ${error instanceof Error ? error.message : String(error)}`, error));
+	}
+};
+
+//#endregion
+//#region packages/builder/src/prebuilt/extractor.ts
+/**
+* Extract field selections from evaluated intermediate elements.
+*
+* For fragments, calls `spread()` with empty/default variables to get field selections.
+* For operations, calls `documentSource()` to get field selections.
+*
+* @param elements - Record of canonical ID to intermediate artifact element
+* @returns Object containing selections map and any warnings encountered
+*/
+const extractFieldSelections = (elements) => {
+	const selections = new Map();
+	const warnings = [];
+	for (const [id, element] of Object.entries(elements)) {
+		const canonicalId = id;
+		try {
+			if (element.type === "fragment") {
+				const variableDefinitions = element.element.variableDefinitions;
+				const varRefs = Object.fromEntries(Object.keys(variableDefinitions).map((k) => [k, (0, __soda_gql_core.createVarRefFromVariable)(k)]));
+				const fields = element.element.spread(varRefs);
+				selections.set(canonicalId, {
+					type: "fragment",
+					schemaLabel: element.element.schemaLabel,
+					key: element.element.key,
+					typename: element.element.typename,
+					fields,
+					variableDefinitions
+				});
+			} else if (element.type === "operation") {
+				const fields = element.element.documentSource();
+				const document = element.element.document;
+				const operationDef = document.definitions.find((def) => def.kind === graphql.Kind.OPERATION_DEFINITION);
+				const variableDefinitions = operationDef?.variableDefinitions ?? [];
+				selections.set(canonicalId, {
+					type: "operation",
+					schemaLabel: element.element.schemaLabel,
+					operationName: element.element.operationName,
+					operationType: element.element.operationType,
+					fields,
+					variableDefinitions
+				});
+			}
+		} catch (error) {
+			warnings.push(`[prebuilt] Failed to extract field selections for ${canonicalId}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return {
+		selections,
+		warnings
+	};
+};
+
 //#endregion
 //#region packages/builder/src/artifact/aggregate.ts
 const canonicalToFilePath$1 = (canonicalId) => canonicalId.split("::")[0] ?? canonicalId;
@@ -1410,7 +1783,11 @@ const aggregate = ({ analyses, elements }) => {
 				contentHash: ""
 			};
 			if (element.type === "fragment") {
-				const prebuild = { typename: element.element.typename };
+				const prebuild = {
+					typename: element.element.typename,
+					key: element.element.key,
+					schemaLabel: element.element.schemaLabel
+				};
 				registry.set(definition.canonicalId, {
 					id: definition.canonicalId,
 					type: "fragment",
@@ -1426,6 +1803,7 @@ const aggregate = ({ analyses, elements }) => {
 				const prebuild = {
 					operationType: element.element.operationType,
 					operationName: element.element.operationName,
+					schemaLabel: element.element.schemaLabel,
 					document: element.element.document,
 					variableNames: element.element.variableNames,
 					metadata: element.element.metadata
@@ -3662,6 +4040,8 @@ exports.collectAffectedFiles = collectAffectedFiles;
 exports.createBuilderService = createBuilderService;
 exports.createBuilderSession = createBuilderSession;
 exports.createGraphqlSystemIdentifyHelper = createGraphqlSystemIdentifyHelper;
+exports.emitPrebuiltTypes = emitPrebuiltTypes;
+exports.extractFieldSelections = extractFieldSelections;
 exports.extractModuleAdjacency = extractModuleAdjacency;
 exports.formatBuilderErrorForCLI = formatBuilderErrorForCLI;
 exports.formatBuilderErrorStructured = formatBuilderErrorStructured;