@soda-gql/tools 0.13.0

package/dist/typegen.cjs

@@ -0,0 +1,864 @@
+const require_chunk = require('./chunk-BrXtsOCC.cjs');
+let neverthrow = require("neverthrow");
+let __soda_gql_core = require("@soda-gql/core");
+let graphql = require("graphql");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let __soda_gql_common_template_extraction = require("@soda-gql/common/template-extraction");
+let __swc_core = require("@swc/core");
+let node_fs_promises = require("node:fs/promises");
+let __soda_gql_builder = require("@soda-gql/builder");
+let fast_glob = require("fast-glob");
+fast_glob = require_chunk.__toESM(fast_glob);
+
+//#region packages/tools/src/typegen/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.
+*
+* Fragments without a 'key' property are skipped (not included in PrebuiltTypes)
+* and a warning is added. This allows projects to use fragments without keys
+* while still generating prebuilt types for those that have keys.
+*
+* @returns Result containing grouped selections and warnings, or error if schema not found
+*/
+const groupBySchema = (fieldSelections, schemas) => {
+	const grouped = new Map();
+	const warnings = [];
+	let skippedFragmentCount = 0;
+	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)(__soda_gql_builder.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) {
+				skippedFragmentCount++;
+				warnings.push(`[prebuilt] Fragment "${canonicalId}" skipped: missing 'key' property. ` + `Use tagged template syntax fragment("Name", "Type")\`{ ... }\` to auto-assign a key, ` + `or set 'key' explicitly in the callback builder.`);
+				continue;
+			}
+			try {
+				const usedInputObjects = collectUsedInputObjectsFromVarDefs(schema, selection.variableDefinitions);
+				for (const inputName of usedInputObjects) {
+					group.inputObjects.add(inputName);
+				}
+				const outputType = (0, __soda_gql_core.calculateFieldsType)(schema, selection.fields, outputFormatters, selection.typename);
+				const hasVariables = Object.keys(selection.variableDefinitions).length > 0;
+				const inputType = hasVariables ? (0, __soda_gql_core.generateInputTypeFromVarDefs)(schema, selection.variableDefinitions, { formatters: inputFormatters }) : "void";
+				group.fragments.push({
+					key: selection.key,
+					typename: selection.typename,
+					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 rootTypeName = schema.operations[selection.operationType];
+				const outputType = (0, __soda_gql_core.calculateFieldsType)(schema, selection.fields, outputFormatters, rootTypeName ?? undefined);
+				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,
+		skippedFragmentCount
+	});
+};
+/**
+* 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 fieldSpec of Object.values(inputDef.fields)) {
+			const parsed = (0, __soda_gql_core.parseInputSpecifier)(fieldSpec);
+			if (parsed.kind === "input" && !inputObjects.has(parsed.name)) {
+				inputObjects.add(parsed.name);
+				collectNested(parsed.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 specStr of Object.values(specifiers)) {
+		const parsed = (0, __soda_gql_core.parseInputSpecifier)(specStr);
+		if (parsed.kind === "input" && schema.input[parsed.name]) {
+			directInputs.add(parsed.name);
+		}
+	}
+	return collectNestedInputObjects(schema, directInputs);
+};
+/**
+* Collect all input object types used in VariableDefinitions (VarSpecifier objects).
+* Used for fragment variable definitions.
+*/
+const collectUsedInputObjectsFromVarDefs = (schema, varDefs) => {
+	const directInputs = new Set();
+	for (const varSpec of Object.values(varDefs)) {
+		if (varSpec.kind === "input" && schema.input[varSpec.name]) {
+			directInputs.add(varSpec.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(`export type Input_${schemaName}_${inputName} = ${typeString};`);
+	}
+	return lines;
+};
+/**
+* Generate the TypeScript code for prebuilt types.
+*/
+const generateTypesCode = (grouped, schemas, injectsModulePath) => {
+	const schemaNames = Object.keys(schemas);
+	const lines = [
+		"/**",
+		" * Prebuilt type registry.",
+		" *",
+		" * This file is auto-generated by @soda-gql/tools/typegen.",
+		" * Do not edit manually.",
+		" *",
+		" * @module",
+		" * @generated",
+		" */",
+		"",
+		"import type { AssertExtends, PrebuiltTypeRegistry } from \"@soda-gql/core\";"
+	];
+	const scalarImports = schemaNames.map((name) => `scalar_${name}`).join(", ");
+	lines.push(`import type { ${scalarImports} } from "${injectsModulePath}";`);
+	lines.push("");
+	for (const schemaName of schemaNames) {
+		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 deduplicatedFragments = new Map();
+		for (const f of fragments) {
+			deduplicatedFragments.set(f.key, f);
+		}
+		const fragmentEntries = Array.from(deduplicatedFragments.values()).sort((a, b) => a.key.localeCompare(b.key)).map((f) => `    readonly "${f.key}": { readonly typename: "${f.typename}"; readonly input: ${f.inputType}; readonly output: ${f.outputType} };`);
+		const deduplicatedOperations = new Map();
+		for (const o of operations) {
+			deduplicatedOperations.set(o.key, o);
+		}
+		const operationEntries = Array.from(deduplicatedOperations.values()).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("};");
+		lines.push(`type _AssertPrebuiltTypes_${schemaName} = AssertExtends<PrebuiltTypes_${schemaName}, PrebuiltTypeRegistry>;`);
+		lines.push("");
+	}
+	return lines.join("\n");
+};
+/**
+* Emit prebuilt types to the types.prebuilt.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, injectsModulePath } = options;
+	const groupResult = groupBySchema(fieldSelections, schemas);
+	if (groupResult.isErr()) {
+		return (0, neverthrow.err)(groupResult.error);
+	}
+	const { grouped, warnings, skippedFragmentCount } = groupResult.value;
+	const code = generateTypesCode(grouped, schemas, injectsModulePath);
+	const typesPath = (0, node_path.join)(outdir, "types.prebuilt.ts");
+	try {
+		await (0, node_fs_promises.writeFile)(typesPath, code, "utf-8");
+		return (0, neverthrow.ok)({
+			path: typesPath,
+			warnings,
+			skippedFragmentCount
+		});
+	} catch (error) {
+		return (0, neverthrow.err)(__soda_gql_builder.builderErrors.writeFailed(typesPath, `Failed to write prebuilt types: ${error instanceof Error ? error.message : String(error)}`, error));
+	}
+};
+
+//#endregion
+//#region packages/tools/src/typegen/errors.ts
+/**
+* Error constructor helpers for concise error creation.
+*/
+const typegenErrors = {
+	codegenRequired: (outdir) => ({
+		code: "TYPEGEN_CODEGEN_REQUIRED",
+		message: `Generated graphql-system module not found at '${outdir}'. Run 'soda-gql codegen' first.`,
+		outdir
+	}),
+	schemaLoadFailed: (schemaNames, cause) => ({
+		code: "TYPEGEN_SCHEMA_LOAD_FAILED",
+		message: `Failed to load schemas: ${schemaNames.join(", ")}`,
+		schemaNames,
+		cause
+	}),
+	buildFailed: (message, cause) => ({
+		code: "TYPEGEN_BUILD_FAILED",
+		message,
+		cause
+	})
+};
+/**
+* Format TypegenError for console output (human-readable).
+*/
+const formatTypegenError = (error) => {
+	const lines = [];
+	lines.push(`Error [${error.code}]: ${error.message}`);
+	switch (error.code) {
+		case "TYPEGEN_CODEGEN_REQUIRED":
+			lines.push(`  Output directory: ${error.outdir}`);
+			lines.push("  Hint: Run 'soda-gql codegen' to generate the graphql-system module first.");
+			break;
+		case "TYPEGEN_SCHEMA_LOAD_FAILED":
+			lines.push(`  Schemas: ${error.schemaNames.join(", ")}`);
+			break;
+	}
+	if ("cause" in error && error.cause) {
+		lines.push(`  Caused by: ${error.cause}`);
+	}
+	return lines.join("\n");
+};
+
+//#endregion
+//#region packages/tools/src/typegen/template-extractor.ts
+/**
+* Parse TypeScript source with SWC, returning null on failure.
+*/
+const safeParseSync = (source, tsx) => {
+	try {
+		return (0, __swc_core.parseSync)(source, {
+			syntax: "typescript",
+			tsx,
+			decorators: false,
+			dynamicImport: true
+		});
+	} catch {
+		return null;
+	}
+};
+/**
+* Collect gql identifiers from import declarations.
+* Finds imports like `import { gql } from "./graphql-system"`.
+*/
+const collectGqlIdentifiers = (module$1, filePath, helper) => {
+	const identifiers = new Set();
+	for (const item of module$1.body) {
+		let declaration = null;
+		if (item.type === "ImportDeclaration") {
+			declaration = item;
+		} else if ("declaration" in item && item.declaration && item.declaration.type === "ImportDeclaration") {
+			declaration = item.declaration;
+		}
+		if (!declaration) {
+			continue;
+		}
+		if (!helper.isGraphqlSystemImportSpecifier({
+			filePath,
+			specifier: declaration.source.value
+		})) {
+			continue;
+		}
+		for (const specifier of declaration.specifiers ?? []) {
+			if (specifier.type === "ImportSpecifier") {
+				const imported = specifier.imported ? specifier.imported.value : specifier.local.value;
+				if (imported === "gql" && !specifier.imported) {
+					identifiers.add(specifier.local.value);
+				}
+			}
+		}
+	}
+	return identifiers;
+};
+/**
+* Extract all tagged templates from a TypeScript source file.
+*
+* @param filePath - Absolute path to the source file (used for import resolution)
+* @param source - TypeScript source code
+* @param helper - GraphQL system identifier for resolving gql imports
+* @returns Extracted templates and any warnings
+*/
+const extractTemplatesFromSource = (filePath, source, helper) => {
+	const warnings = [];
+	const isTsx = filePath.endsWith(".tsx");
+	const program = safeParseSync(source, isTsx);
+	if (!program || program.type !== "Module") {
+		if (source.includes("gql")) {
+			warnings.push(`[typegen-extract] Failed to parse ${filePath}`);
+		}
+		return {
+			templates: [],
+			warnings
+		};
+	}
+	const gqlIdentifiers = collectGqlIdentifiers(program, filePath, helper);
+	if (gqlIdentifiers.size === 0) {
+		return {
+			templates: [],
+			warnings
+		};
+	}
+	return {
+		templates: (0, __soda_gql_common_template_extraction.walkAndExtract)(program, gqlIdentifiers),
+		warnings
+	};
+};
+
+//#endregion
+//#region packages/tools/src/typegen/template-scanner.ts
+/**
+* Source file scanner for tagged template extraction.
+*
+* Discovers source files from config include/exclude patterns,
+* reads them, and extracts tagged templates using the template extractor.
+*
+* @module
+*/
+/**
+* Scan source files for tagged templates.
+*
+* Uses fast-glob to discover files matching include/exclude patterns,
+* then extracts tagged templates from each file.
+*/
+const scanSourceFiles = (options) => {
+	const { include, exclude, baseDir, helper } = options;
+	const warnings = [];
+	const ignorePatterns = exclude.map((pattern) => pattern.startsWith("!") ? pattern.slice(1) : pattern);
+	const matchedFiles = fast_glob.default.sync(include, {
+		cwd: baseDir,
+		ignore: ignorePatterns,
+		onlyFiles: true,
+		absolute: true
+	});
+	const templates = new Map();
+	for (const filePath of matchedFiles) {
+		const normalizedPath = (0, node_path.normalize)((0, node_path.resolve)(filePath)).replace(/\\/g, "/");
+		try {
+			const source = (0, node_fs.readFileSync)(normalizedPath, "utf-8");
+			const { templates: extracted, warnings: extractionWarnings } = extractTemplatesFromSource(normalizedPath, source, helper);
+			warnings.push(...extractionWarnings);
+			if (extracted.length > 0) {
+				templates.set(normalizedPath, extracted);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			warnings.push(`[typegen-scan] Failed to read ${normalizedPath}: ${message}`);
+		}
+	}
+	return {
+		templates,
+		warnings
+	};
+};
+
+//#endregion
+//#region packages/tools/src/typegen/template-to-selections.ts
+/**
+* Convert extracted templates into field selections for the emitter.
+*
+* @param templates - Templates extracted from source files, keyed by file path
+* @param schemas - Loaded schema objects keyed by schema name
+* @returns Map of canonical IDs to field selection data, plus any warnings
+*/
+const convertTemplatesToSelections = (templates, schemas) => {
+	const selections = new Map();
+	const warnings = [];
+	const schemaIndexes = new Map(Object.entries(schemas).map(([name, schema]) => [name, (0, __soda_gql_core.createSchemaIndexFromSchema)(schema)]));
+	for (const [filePath, fileTemplates] of templates) {
+		for (const template of fileTemplates) {
+			const schema = schemas[template.schemaName];
+			if (!schema) {
+				warnings.push(`[typegen-template] Unknown schema "${template.schemaName}" in ${filePath}`);
+				continue;
+			}
+			const schemaIndex = schemaIndexes.get(template.schemaName);
+			if (!schemaIndex) {
+				continue;
+			}
+			try {
+				if (template.kind === "fragment") {
+					const selection = convertFragmentTemplate(template, schema, filePath);
+					if (selection) {
+						selections.set(selection.id, selection.data);
+					}
+				} else {
+					const selection = convertOperationTemplate(template, schema, filePath);
+					if (selection) {
+						selections.set(selection.id, selection.data);
+					}
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				warnings.push(`[typegen-template] Failed to process ${template.kind} in ${filePath}: ${message}`);
+			}
+		}
+	}
+	return {
+		selections,
+		warnings
+	};
+};
+/**
+* Recursively filter out __FRAG_SPREAD_ placeholder nodes from a selection set.
+* These placeholders are created by template-extractor for interpolated fragment references.
+* buildFieldsFromSelectionSet would throw on them since no interpolationMap is available.
+*/
+const filterPlaceholderSpreads = (selectionSet) => ({
+	...selectionSet,
+	selections: selectionSet.selections.filter((sel) => !(sel.kind === graphql.Kind.FRAGMENT_SPREAD && sel.name.value.startsWith("__FRAG_SPREAD_"))).map((sel) => {
+		if (sel.kind === graphql.Kind.FIELD && sel.selectionSet) {
+			return {
+				...sel,
+				selectionSet: filterPlaceholderSpreads(sel.selectionSet)
+			};
+		}
+		if (sel.kind === graphql.Kind.INLINE_FRAGMENT && sel.selectionSet) {
+			return {
+				...sel,
+				selectionSet: filterPlaceholderSpreads(sel.selectionSet)
+			};
+		}
+		return sel;
+	})
+});
+/** Simple matching-paren finder for template content (no comments/strings to handle). */
+const findClosingParen = (source, openIndex) => {
+	let depth = 0;
+	for (let i = openIndex; i < source.length; i++) {
+		if (source[i] === "(") depth++;
+		else if (source[i] === ")") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+};
+/**
+* Reconstruct full GraphQL source from an extracted template.
+* For curried syntax (new), prepends the definition header from tag call arguments.
+* For curried fragments with Fragment Arguments, repositions variable declarations
+* before the on-clause to produce RFC-compliant syntax.
+* For old syntax, returns content as-is.
+*/
+const reconstructGraphql = (template) => {
+	if (template.elementName) {
+		if (template.kind === "fragment" && template.typeName) {
+			const trimmed = template.content.trim();
+			if (trimmed.startsWith("(")) {
+				const closeIdx = findClosingParen(trimmed, 0);
+				if (closeIdx !== -1) {
+					const varDecls = trimmed.slice(0, closeIdx + 1);
+					const selectionSet = trimmed.slice(closeIdx + 1).trim();
+					return `fragment ${template.elementName}${varDecls} on ${template.typeName} ${selectionSet}`;
+				}
+			}
+			return `fragment ${template.elementName} on ${template.typeName} ${trimmed}`;
+		}
+		return `${template.kind} ${template.elementName} ${template.content}`;
+	}
+	return template.content;
+};
+/**
+* Convert a fragment template into FieldSelectionData.
+*/
+const convertFragmentTemplate = (template, schema, filePath) => {
+	const schemaIndex = (0, __soda_gql_core.createSchemaIndexFromSchema)(schema);
+	const graphqlSource = reconstructGraphql(template);
+	const variableDefinitions = (0, __soda_gql_core.extractFragmentVariables)(graphqlSource, schemaIndex);
+	const { preprocessed } = (0, __soda_gql_core.preprocessFragmentArgs)(graphqlSource);
+	const document = (0, graphql.parse)(preprocessed);
+	const fragDef = document.definitions.find((d) => d.kind === graphql.Kind.FRAGMENT_DEFINITION);
+	if (!fragDef || fragDef.kind !== graphql.Kind.FRAGMENT_DEFINITION) {
+		return null;
+	}
+	const fragmentName = fragDef.name.value;
+	const onType = fragDef.typeCondition.name.value;
+	const fields = (0, __soda_gql_core.buildFieldsFromSelectionSet)(filterPlaceholderSpreads(fragDef.selectionSet), schema, onType);
+	const id = `${filePath}::${fragmentName}`;
+	return {
+		id,
+		data: {
+			type: "fragment",
+			schemaLabel: schema.label,
+			key: fragmentName,
+			typename: onType,
+			fields,
+			variableDefinitions
+		}
+	};
+};
+/**
+* Convert an operation template into FieldSelectionData.
+*/
+const convertOperationTemplate = (template, schema, filePath) => {
+	const graphqlSource = reconstructGraphql(template);
+	const document = (0, graphql.parse)(graphqlSource);
+	const opDef = document.definitions.find((d) => d.kind === graphql.Kind.OPERATION_DEFINITION);
+	if (!opDef || opDef.kind !== graphql.Kind.OPERATION_DEFINITION) {
+		return null;
+	}
+	const operationName = opDef.name?.value ?? "Anonymous";
+	const operationType = opDef.operation;
+	const rootTypeName = getRootTypeName(schema, operationType);
+	const fields = (0, __soda_gql_core.buildFieldsFromSelectionSet)(filterPlaceholderSpreads(opDef.selectionSet), schema, rootTypeName);
+	const variableDefinitions = opDef.variableDefinitions ?? [];
+	const id = `${filePath}::${operationName}`;
+	return {
+		id,
+		data: {
+			type: "operation",
+			schemaLabel: schema.label,
+			operationName,
+			operationType,
+			fields,
+			variableDefinitions: [...variableDefinitions]
+		}
+	};
+};
+/**
+* Get the root type name for an operation type from the schema.
+*/
+const getRootTypeName = (schema, operationType) => {
+	switch (operationType) {
+		case "query": return schema.operations.query ?? "Query";
+		case "mutation": return schema.operations.mutation ?? "Mutation";
+		case "subscription": return schema.operations.subscription ?? "Subscription";
+		default: return "Query";
+	}
+};
+
+//#endregion
+//#region packages/tools/src/typegen/runner.ts
+/**
+* Main typegen runner.
+*
+* Orchestrates the prebuilt type generation process:
+* 1. Load schemas from generated CJS bundle
+* 2. Build artifact to evaluate elements
+* 3. Extract field selections from builder
+* 4. Scan source files for tagged templates and merge selections
+* 5. Emit types.prebuilt.ts
+*
+* @module
+*/
+const extensionMap = {
+	".ts": ".js",
+	".tsx": ".js",
+	".mts": ".mjs",
+	".cts": ".cjs",
+	".js": ".js",
+	".mjs": ".mjs",
+	".cjs": ".cjs"
+};
+const toImportSpecifier = (fromPath, targetPath, options) => {
+	const fromDir = (0, node_path.dirname)(fromPath);
+	const normalized = (0, node_path.relative)(fromDir, targetPath).replace(/\\/g, "/");
+	const sourceExt = (0, node_path.extname)(targetPath);
+	if (!options?.includeExtension) {
+		if (normalized.length === 0) {
+			return `./${targetPath.slice(0, -sourceExt.length).split("/").pop()}`;
+		}
+		const withPrefix$1 = normalized.startsWith(".") ? normalized : `./${normalized}`;
+		const currentExt$1 = (0, node_path.extname)(withPrefix$1);
+		return currentExt$1 ? withPrefix$1.slice(0, -currentExt$1.length) : withPrefix$1;
+	}
+	const runtimeExt = extensionMap[sourceExt] ?? sourceExt;
+	if (normalized.length === 0) {
+		const base = runtimeExt !== sourceExt ? targetPath.slice(0, -sourceExt.length).split("/").pop() : targetPath.split("/").pop();
+		return `./${base}${runtimeExt}`;
+	}
+	const withPrefix = normalized.startsWith(".") ? normalized : `./${normalized}`;
+	if (!runtimeExt) {
+		return withPrefix;
+	}
+	if (withPrefix.endsWith(runtimeExt)) {
+		return withPrefix;
+	}
+	const currentExt = (0, node_path.extname)(withPrefix);
+	const withoutExt = currentExt ? withPrefix.slice(0, -currentExt.length) : withPrefix;
+	return `${withoutExt}${runtimeExt}`;
+};
+/**
+* Run the typegen process.
+*
+* This function:
+* 1. Loads schemas from the generated CJS bundle
+* 2. Creates a BuilderService and builds the artifact
+* 3. Extracts field selections from the artifact
+* 4. Scans source files for tagged templates and merges selections
+* 5. Emits types.prebuilt.ts using emitPrebuiltTypes
+*
+* @param options - Typegen options including config
+* @returns Result containing success data or error
+*/
+const runTypegen = async (options) => {
+	const { config } = options;
+	const outdir = (0, node_path.resolve)(config.outdir);
+	const cjsPath = (0, node_path.join)(outdir, "index.cjs");
+	const importSpecifierOptions = { includeExtension: config.styles.importExtension };
+	if (!(0, node_fs.existsSync)(cjsPath)) {
+		return (0, neverthrow.err)(typegenErrors.codegenRequired(outdir));
+	}
+	const schemaNames = Object.keys(config.schemas);
+	const schemasResult = (0, __soda_gql_builder.loadSchemasFromBundle)(cjsPath, schemaNames);
+	if (schemasResult.isErr()) {
+		return (0, neverthrow.err)(typegenErrors.schemaLoadFailed(schemaNames, schemasResult.error));
+	}
+	const schemas = schemasResult.value;
+	const prebuiltTypesPath = (0, node_path.join)(outdir, "types.prebuilt.ts");
+	const injectsModulePath = toImportSpecifier(prebuiltTypesPath, (0, node_path.join)(outdir, "_internal-injects.ts"), importSpecifierOptions);
+	const builderService = (0, __soda_gql_builder.createBuilderService)({ config });
+	const artifactResult = await builderService.buildAsync();
+	if (artifactResult.isErr()) {
+		return (0, neverthrow.err)(typegenErrors.buildFailed(`Builder failed: ${artifactResult.error.message}`, artifactResult.error));
+	}
+	const intermediateElements = builderService.getIntermediateElements();
+	if (!intermediateElements) {
+		return (0, neverthrow.err)(typegenErrors.buildFailed("No intermediate elements available after build", undefined));
+	}
+	const fieldSelectionsResult = (0, __soda_gql_builder.extractFieldSelections)(intermediateElements);
+	const { selections: builderSelections, warnings: extractWarnings } = fieldSelectionsResult;
+	const graphqlHelper = (0, __soda_gql_builder.createGraphqlSystemIdentifyHelper)(config);
+	const scanResult = scanSourceFiles({
+		include: [...config.include],
+		exclude: [...config.exclude],
+		baseDir: config.baseDir,
+		helper: graphqlHelper
+	});
+	const templateSelections = convertTemplatesToSelections(scanResult.templates, schemas);
+	const fieldSelections = mergeSelections(builderSelections, templateSelections.selections, config.baseDir);
+	const scanWarnings = [...scanResult.warnings, ...templateSelections.warnings];
+	const emitResult = await emitPrebuiltTypes({
+		schemas,
+		fieldSelections,
+		outdir,
+		injectsModulePath
+	});
+	if (emitResult.isErr()) {
+		return (0, neverthrow.err)(emitResult.error);
+	}
+	const { warnings: emitWarnings, skippedFragmentCount } = emitResult.value;
+	let fragmentCount = 0;
+	let operationCount = 0;
+	for (const selection of fieldSelections.values()) {
+		if (selection.type === "fragment" && selection.key) {
+			fragmentCount++;
+		} else if (selection.type === "operation") {
+			operationCount++;
+		}
+	}
+	const allWarnings = [
+		...extractWarnings,
+		...scanWarnings,
+		...emitWarnings
+	];
+	return (0, neverthrow.ok)({
+		prebuiltTypesPath,
+		fragmentCount,
+		operationCount,
+		skippedFragmentCount,
+		warnings: allWarnings
+	});
+};
+const extractElementName = (data) => data.type === "fragment" ? data.key : data.operationName;
+/**
+* Merge builder and template selections into a combined map.
+*
+* Builder selections are authoritative — VM evaluation correctly resolves
+* fragment spreads that static template analysis cannot handle.
+* Template selections serve as fallback for elements only found by the scanner.
+*
+* Deduplication is per-element (file + GraphQL name), not per-file, so that
+* callback-builder operations in files that also contain tagged templates are preserved.
+*/
+const mergeSelections = (builderSelections, templateSelections, baseDir) => {
+	const extractFilePart = (id) => {
+		const filePart = id.split("::")[0] ?? "";
+		if (filePart.startsWith("/")) {
+			return (0, node_path.relative)(baseDir, filePart);
+		}
+		return filePart;
+	};
+	const builderElements = new Set();
+	for (const [id, data] of builderSelections) {
+		const name = extractElementName(data);
+		if (name) builderElements.add(`${extractFilePart(id)}::${name}`);
+	}
+	const fieldSelections = new Map();
+	for (const [id, data] of builderSelections) {
+		fieldSelections.set(id, data);
+	}
+	for (const [id, data] of templateSelections) {
+		const name = extractElementName(data);
+		if (name && builderElements.has(`${extractFilePart(id)}::${name}`)) continue;
+		fieldSelections.set(id, data);
+	}
+	return fieldSelections;
+};
+
+//#endregion
+exports.emitPrebuiltTypes = emitPrebuiltTypes;
+exports.formatTypegenError = formatTypegenError;
+exports.runTypegen = runTypegen;
+exports.typegenErrors = typegenErrors;
+//# sourceMappingURL=typegen.cjs.map