@soda-gql/builder 0.7.0 → 0.8.2

package/dist/index.cjs

@@ -25,8 +25,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let neverthrow = require("neverthrow");
+let zod = require("zod");
+let node_crypto = require("node:crypto");
 let node_path = require("node:path");
 let node_vm = require("node:vm");
 let __soda_gql_common = require("@soda-gql/common");
@@ -39,14 +42,452 @@ __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 neverthrow = require("neverthrow");
-let node_fs_promises = require("node:fs/promises");
-let zod = require("zod");
 let typescript = require("typescript");
 typescript = __toESM(typescript);
 let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
 
+//#region packages/builder/src/schemas/artifact.ts
+const BuilderArtifactElementMetadataSchema = zod.z.object({
+	sourcePath: zod.z.string(),
+	contentHash: zod.z.string()
+});
+const BuilderArtifactOperationSchema = zod.z.object({
+	id: zod.z.string(),
+	type: zod.z.literal("operation"),
+	metadata: BuilderArtifactElementMetadataSchema,
+	prebuild: zod.z.object({
+		operationType: zod.z.enum([
+			"query",
+			"mutation",
+			"subscription"
+		]),
+		operationName: zod.z.string(),
+		document: zod.z.unknown(),
+		variableNames: zod.z.array(zod.z.string())
+	})
+});
+const BuilderArtifactFragmentSchema = zod.z.object({
+	id: zod.z.string(),
+	type: zod.z.literal("fragment"),
+	metadata: BuilderArtifactElementMetadataSchema,
+	prebuild: zod.z.object({ typename: zod.z.string() })
+});
+const BuilderArtifactElementSchema = zod.z.discriminatedUnion("type", [BuilderArtifactOperationSchema, BuilderArtifactFragmentSchema]);
+const BuilderArtifactMetaSchema = zod.z.object({
+	version: zod.z.string(),
+	createdAt: zod.z.string()
+});
+const BuilderArtifactSchema = zod.z.object({
+	meta: BuilderArtifactMetaSchema.optional(),
+	elements: zod.z.record(zod.z.string(), BuilderArtifactElementSchema),
+	report: zod.z.object({
+		durationMs: zod.z.number(),
+		warnings: zod.z.array(zod.z.string()),
+		stats: zod.z.object({
+			hits: zod.z.number(),
+			misses: zod.z.number(),
+			skips: zod.z.number()
+		})
+	})
+});
+
+//#endregion
+//#region packages/builder/src/artifact/loader.ts
+/**
+* Load a pre-built artifact from a JSON file asynchronously.
+*
+* @param path - Absolute path to the artifact JSON file
+* @returns Result with the parsed artifact or an error
+*
+* @example
+* ```ts
+* const result = await loadArtifact("/path/to/artifact.json");
+* if (result.isOk()) {
+*   const artifact = result.value;
+*   // Use artifact...
+* }
+* ```
+*/
+const loadArtifact = async (path) => {
+	if (!(0, node_fs.existsSync)(path)) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_NOT_FOUND",
+			message: `Artifact file not found: ${path}`,
+			filePath: path
+		});
+	}
+	let content;
+	try {
+		content = await (0, node_fs_promises.readFile)(path, "utf-8");
+	} catch (error) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_NOT_FOUND",
+			message: `Failed to read artifact file: ${error instanceof Error ? error.message : String(error)}`,
+			filePath: path
+		});
+	}
+	return parseAndValidateArtifact(content, path);
+};
+/**
+* Load a pre-built artifact from a JSON file synchronously.
+*
+* @param path - Absolute path to the artifact JSON file
+* @returns Result with the parsed artifact or an error
+*
+* @example
+* ```ts
+* const result = loadArtifactSync("/path/to/artifact.json");
+* if (result.isOk()) {
+*   const artifact = result.value;
+*   // Use artifact...
+* }
+* ```
+*/
+const loadArtifactSync = (path) => {
+	if (!(0, node_fs.existsSync)(path)) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_NOT_FOUND",
+			message: `Artifact file not found: ${path}`,
+			filePath: path
+		});
+	}
+	let content;
+	try {
+		content = (0, node_fs.readFileSync)(path, "utf-8");
+	} catch (error) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_NOT_FOUND",
+			message: `Failed to read artifact file: ${error instanceof Error ? error.message : String(error)}`,
+			filePath: path
+		});
+	}
+	return parseAndValidateArtifact(content, path);
+};
+/**
+* Parse JSON content and validate against BuilderArtifactSchema.
+*/
+function parseAndValidateArtifact(content, filePath) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch (error) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_PARSE_ERROR",
+			message: `Invalid JSON in artifact file: ${error instanceof Error ? error.message : String(error)}`,
+			filePath
+		});
+	}
+	const validated = BuilderArtifactSchema.safeParse(parsed);
+	if (!validated.success) {
+		return (0, neverthrow.err)({
+			code: "ARTIFACT_VALIDATION_ERROR",
+			message: `Invalid artifact structure: ${validated.error.message}`,
+			filePath
+		});
+	}
+	return (0, neverthrow.ok)(validated.data);
+}
+
+//#endregion
+//#region packages/builder/src/errors/formatter.ts
+/**
+* Hints for each error code to help users understand and fix issues.
+*/
+const errorHints = {
+	ELEMENT_EVALUATION_FAILED: "Check if all imported fragments are properly exported and included in entry patterns.",
+	GRAPH_CIRCULAR_DEPENDENCY: "Break the circular import by extracting shared types to a common module.",
+	GRAPH_MISSING_IMPORT: "Verify the import path exists and the module is included in entry patterns.",
+	RUNTIME_MODULE_LOAD_FAILED: "Ensure the module can be imported and all dependencies are installed.",
+	CONFIG_NOT_FOUND: "Create a soda-gql.config.ts file in your project root.",
+	CONFIG_INVALID: "Check your configuration file for syntax errors or invalid options.",
+	ENTRY_NOT_FOUND: "Verify the entry pattern matches your file structure.",
+	INTERNAL_INVARIANT: "This is an internal error. Please report it at https://github.com/soda-gql/soda-gql/issues"
+};
+/**
+* Format a BuilderError into a structured FormattedError object.
+*/
+const formatBuilderErrorStructured = (error) => {
+	const base = {
+		code: error.code,
+		message: error.message,
+		hint: errorHints[error.code],
+		cause: "cause" in error ? error.cause : undefined
+	};
+	switch (error.code) {
+		case "ELEMENT_EVALUATION_FAILED": return {
+			...base,
+			location: {
+				modulePath: error.modulePath,
+				astPath: error.astPath || undefined
+			}
+		};
+		case "RUNTIME_MODULE_LOAD_FAILED": return {
+			...base,
+			location: {
+				modulePath: error.filePath,
+				astPath: error.astPath
+			}
+		};
+		case "GRAPH_MISSING_IMPORT": return {
+			...base,
+			relatedFiles: [error.importer, error.importee]
+		};
+		case "GRAPH_CIRCULAR_DEPENDENCY": return {
+			...base,
+			relatedFiles: error.chain
+		};
+		case "CONFIG_NOT_FOUND":
+		case "CONFIG_INVALID": return {
+			...base,
+			location: { modulePath: error.path }
+		};
+		case "FINGERPRINT_FAILED": return {
+			...base,
+			location: { modulePath: error.filePath }
+		};
+		case "DISCOVERY_IO_ERROR": return {
+			...base,
+			location: { modulePath: error.path }
+		};
+		default: return base;
+	}
+};
+/**
+* Format a BuilderError for CLI/stderr output with human-readable formatting.
+* Includes location, hint, and related files when available.
+*/
+const formatBuilderErrorForCLI = (error) => {
+	const formatted = formatBuilderErrorStructured(error);
+	const lines = [];
+	lines.push(`Error [${formatted.code}]: ${formatted.message}`);
+	if (formatted.location) {
+		lines.push(`  at ${formatted.location.modulePath}`);
+		if (formatted.location.astPath) {
+			lines.push(`  in ${formatted.location.astPath}`);
+		}
+	}
+	if (formatted.hint) {
+		lines.push("");
+		lines.push(`  Hint: ${formatted.hint}`);
+	}
+	if (formatted.relatedFiles && formatted.relatedFiles.length > 0) {
+		lines.push("");
+		lines.push("  Related files:");
+		for (const file of formatted.relatedFiles) {
+			lines.push(`    - ${file}`);
+		}
+	}
+	return lines.join("\n");
+};
+
+//#endregion
+//#region packages/builder/src/errors.ts
+/**
+* Error constructor helpers for concise error creation.
+*/
+const builderErrors = {
+	entryNotFound: (entry, message) => ({
+		code: "ENTRY_NOT_FOUND",
+		message: message ?? `Entry not found: ${entry}`,
+		entry
+	}),
+	configNotFound: (path, message) => ({
+		code: "CONFIG_NOT_FOUND",
+		message: message ?? `Config file not found: ${path}`,
+		path
+	}),
+	configInvalid: (path, message, cause) => ({
+		code: "CONFIG_INVALID",
+		message,
+		path,
+		cause
+	}),
+	discoveryIOError: (path, message, errno, cause) => ({
+		code: "DISCOVERY_IO_ERROR",
+		message,
+		path,
+		errno,
+		cause
+	}),
+	fingerprintFailed: (filePath, message, cause) => ({
+		code: "FINGERPRINT_FAILED",
+		message,
+		filePath,
+		cause
+	}),
+	unsupportedAnalyzer: (analyzer, message) => ({
+		code: "UNSUPPORTED_ANALYZER",
+		message: message ?? `Unsupported analyzer: ${analyzer}`,
+		analyzer
+	}),
+	canonicalPathInvalid: (path, reason) => ({
+		code: "CANONICAL_PATH_INVALID",
+		message: `Invalid canonical path: ${path}${reason ? ` (${reason})` : ""}`,
+		path,
+		reason
+	}),
+	canonicalScopeMismatch: (expected, actual) => ({
+		code: "CANONICAL_SCOPE_MISMATCH",
+		message: `Scope mismatch: expected ${expected}, got ${actual}`,
+		expected,
+		actual
+	}),
+	graphCircularDependency: (chain) => ({
+		code: "GRAPH_CIRCULAR_DEPENDENCY",
+		message: `Circular dependency detected: ${chain.join(" → ")}`,
+		chain
+	}),
+	graphMissingImport: (importer, importee) => ({
+		code: "GRAPH_MISSING_IMPORT",
+		message: `Missing import: "${importer}" imports "${importee}" but it's not in the graph`,
+		importer,
+		importee
+	}),
+	docDuplicate: (name, sources) => ({
+		code: "DOC_DUPLICATE",
+		message: `Duplicate document name: ${name} found in ${sources.length} files`,
+		name,
+		sources
+	}),
+	writeFailed: (outPath, message, cause) => ({
+		code: "WRITE_FAILED",
+		message,
+		outPath,
+		cause
+	}),
+	cacheCorrupted: (message, cachePath, cause) => ({
+		code: "CACHE_CORRUPTED",
+		message,
+		cachePath,
+		cause
+	}),
+	runtimeModuleLoadFailed: (filePath, astPath, message, cause) => ({
+		code: "RUNTIME_MODULE_LOAD_FAILED",
+		message,
+		filePath,
+		astPath,
+		cause
+	}),
+	artifactRegistrationFailed: (elementId, reason) => ({
+		code: "ARTIFACT_REGISTRATION_FAILED",
+		message: `Failed to register artifact element ${elementId}: ${reason}`,
+		elementId,
+		reason
+	}),
+	elementEvaluationFailed: (modulePath, astPath, message, cause) => ({
+		code: "ELEMENT_EVALUATION_FAILED",
+		message,
+		modulePath,
+		astPath,
+		cause
+	}),
+	internalInvariant: (message, context, cause) => ({
+		code: "INTERNAL_INVARIANT",
+		message: `Internal invariant violated: ${message}`,
+		context,
+		cause
+	})
+};
+/**
+* Convenience helper to create an err Result from BuilderError.
+*/
+const builderErr = (error) => (0, neverthrow.err)(error);
+/**
+* Type guard for BuilderError.
+*/
+const isBuilderError = (error) => {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+};
+/**
+* Format BuilderError for console output (human-readable).
+*/
+const formatBuilderError = (error) => {
+	const lines = [];
+	lines.push(`Error [${error.code}]: ${error.message}`);
+	switch (error.code) {
+		case "ENTRY_NOT_FOUND":
+			lines.push(`  Entry: ${error.entry}`);
+			break;
+		case "CONFIG_NOT_FOUND":
+		case "CONFIG_INVALID":
+			lines.push(`  Path: ${error.path}`);
+			if (error.code === "CONFIG_INVALID" && error.cause) {
+				lines.push(`  Cause: ${error.cause}`);
+			}
+			break;
+		case "DISCOVERY_IO_ERROR":
+			lines.push(`  Path: ${error.path}`);
+			if (error.errno !== undefined) {
+				lines.push(`  Errno: ${error.errno}`);
+			}
+			break;
+		case "FINGERPRINT_FAILED":
+			lines.push(`  File: ${error.filePath}`);
+			break;
+		case "CANONICAL_PATH_INVALID":
+			lines.push(`  Path: ${error.path}`);
+			if (error.reason) {
+				lines.push(`  Reason: ${error.reason}`);
+			}
+			break;
+		case "CANONICAL_SCOPE_MISMATCH":
+			lines.push(`  Expected: ${error.expected}`);
+			lines.push(`  Actual: ${error.actual}`);
+			break;
+		case "GRAPH_CIRCULAR_DEPENDENCY":
+			lines.push(`  Chain: ${error.chain.join(" → ")}`);
+			break;
+		case "GRAPH_MISSING_IMPORT":
+			lines.push(`  Importer: ${error.importer}`);
+			lines.push(`  Importee: ${error.importee}`);
+			break;
+		case "DOC_DUPLICATE":
+			lines.push(`  Name: ${error.name}`);
+			lines.push(`  Sources:\n    ${error.sources.join("\n    ")}`);
+			break;
+		case "WRITE_FAILED":
+			lines.push(`  Output path: ${error.outPath}`);
+			break;
+		case "CACHE_CORRUPTED":
+			if (error.cachePath) {
+				lines.push(`  Cache path: ${error.cachePath}`);
+			}
+			break;
+		case "RUNTIME_MODULE_LOAD_FAILED":
+			lines.push(`  File: ${error.filePath}`);
+			lines.push(`  AST path: ${error.astPath}`);
+			break;
+		case "ARTIFACT_REGISTRATION_FAILED":
+			lines.push(`  Element ID: ${error.elementId}`);
+			lines.push(`  Reason: ${error.reason}`);
+			break;
+		case "ELEMENT_EVALUATION_FAILED":
+			lines.push(`  at ${error.modulePath}`);
+			if (error.astPath) {
+				lines.push(`  in ${error.astPath}`);
+			}
+			break;
+		case "INTERNAL_INVARIANT":
+			if (error.context) {
+				lines.push(`  Context: ${error.context}`);
+			}
+			break;
+	}
+	if ("cause" in error && error.cause && !["CONFIG_INVALID"].includes(error.code)) {
+		lines.push(`  Caused by: ${error.cause}`);
+	}
+	return lines.join("\n");
+};
+/**
+* Assert unreachable code path (for exhaustiveness checks).
+* This is the ONLY acceptable throw in builder code.
+*/
+const assertUnreachable = (value, context) => {
+	throw new Error(`Unreachable code path${context ? ` in ${context}` : ""}: received ${JSON.stringify(value)}`);
+};
+
+//#endregion
 //#region packages/builder/src/scheduler/effects.ts
 /**
 * File read effect - reads a file from the filesystem.
@@ -171,6 +612,8 @@ var OptionalFileStatEffect = class extends __soda_gql_common.Effect {
 * Supports both sync and async schedulers, enabling parallel element evaluation
 * when using async scheduler.
 *
+* Wraps errors with module context for better debugging.
+*
 * @example
 * yield* new ElementEvaluationEffect(element).run();
 */
@@ -179,19 +622,39 @@ var ElementEvaluationEffect = class extends __soda_gql_common.Effect {
 		super();
 		this.element = element;
 	}
+	/**
+	* Wrap an error with element context for better debugging.
+	*/
+	wrapError(error) {
+		const context = __soda_gql_core.GqlElement.getContext(this.element);
+		if (context) {
+			const { filePath, astPath } = (0, __soda_gql_common.parseCanonicalId)(context.canonicalId);
+			const message = error instanceof Error ? error.message : String(error);
+			throw builderErrors.elementEvaluationFailed(filePath, astPath, message, error);
+		}
+		throw error;
+	}
 	_executeSync() {
-		const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
-		const result = generator.next();
-		while (!result.done) {
-			throw new Error("Async operation required during sync element evaluation");
+		try {
+			const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
+			const result = generator.next();
+			while (!result.done) {
+				throw new Error("Async operation required during sync element evaluation");
+			}
+		} catch (error) {
+			this.wrapError(error);
 		}
 	}
 	async _executeAsync() {
-		const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
-		let result = generator.next();
-		while (!result.done) {
-			await result.value;
-			result = generator.next();
+		try {
+			const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
+			let result = generator.next();
+			while (!result.done) {
+				await result.value;
+				result = generator.next();
+			}
+		} catch (error) {
+			this.wrapError(error);
 		}
 	}
 };
@@ -887,74 +1350,33 @@ const createGraphqlSystemIdentifyHelper = (config) => {
 			return getCanonicalFileName((0, node_fs.realpathSync)(resolved));
 		} catch {
 			return getCanonicalFileName(resolved);
-		}
-	};
-	const graphqlSystemPath = (0, node_path.resolve)(config.outdir, "index.ts");
-	const canonicalGraphqlSystemPath = toCanonical(graphqlSystemPath);
-	const canonicalAliases = new Set(config.graphqlSystemAliases.map((alias) => alias));
-	return {
-		isGraphqlSystemFile: ({ filePath }) => {
-			return toCanonical(filePath) === canonicalGraphqlSystemPath;
-		},
-		isGraphqlSystemImportSpecifier: ({ filePath, specifier }) => {
-			if (canonicalAliases.has(specifier)) {
-				return true;
-			}
-			if (!specifier.startsWith(".")) {
-				return false;
-			}
-			const resolved = (0, __soda_gql_common.resolveRelativeImportWithExistenceCheck)({
-				filePath,
-				specifier
-			});
-			if (!resolved) {
-				return false;
-			}
-			return toCanonical(resolved) === canonicalGraphqlSystemPath;
-		}
-	};
-};
-
-//#endregion
-//#region packages/builder/src/schemas/artifact.ts
-const BuilderArtifactElementMetadataSchema = zod.z.object({
-	sourcePath: zod.z.string(),
-	contentHash: zod.z.string()
-});
-const BuilderArtifactOperationSchema = zod.z.object({
-	id: zod.z.string(),
-	type: zod.z.literal("operation"),
-	metadata: BuilderArtifactElementMetadataSchema,
-	prebuild: zod.z.object({
-		operationType: zod.z.enum([
-			"query",
-			"mutation",
-			"subscription"
-		]),
-		operationName: zod.z.string(),
-		document: zod.z.unknown(),
-		variableNames: zod.z.array(zod.z.string())
-	})
-});
-const BuilderArtifactFragmentSchema = zod.z.object({
-	id: zod.z.string(),
-	type: zod.z.literal("fragment"),
-	metadata: BuilderArtifactElementMetadataSchema,
-	prebuild: zod.z.object({ typename: zod.z.string() })
-});
-const BuilderArtifactElementSchema = zod.z.discriminatedUnion("type", [BuilderArtifactOperationSchema, BuilderArtifactFragmentSchema]);
-const BuilderArtifactSchema = zod.z.object({
-	elements: zod.z.record(zod.z.string(), BuilderArtifactElementSchema),
-	report: zod.z.object({
-		durationMs: zod.z.number(),
-		warnings: zod.z.array(zod.z.string()),
-		stats: zod.z.object({
-			hits: zod.z.number(),
-			misses: zod.z.number(),
-			skips: zod.z.number()
-		})
-	})
-});
+		}
+	};
+	const graphqlSystemPath = (0, node_path.resolve)(config.outdir, "index.ts");
+	const canonicalGraphqlSystemPath = toCanonical(graphqlSystemPath);
+	const canonicalAliases = new Set(config.graphqlSystemAliases.map((alias) => alias));
+	return {
+		isGraphqlSystemFile: ({ filePath }) => {
+			return toCanonical(filePath) === canonicalGraphqlSystemPath;
+		},
+		isGraphqlSystemImportSpecifier: ({ filePath, specifier }) => {
+			if (canonicalAliases.has(specifier)) {
+				return true;
+			}
+			if (!specifier.startsWith(".")) {
+				return false;
+			}
+			const resolved = (0, __soda_gql_common.resolveRelativeImportWithExistenceCheck)({
+				filePath,
+				specifier
+			});
+			if (!resolved) {
+				return false;
+			}
+			return toCanonical(resolved) === canonicalGraphqlSystemPath;
+		}
+	};
+};
 
 //#endregion
 //#region packages/builder/src/artifact/aggregate.ts
@@ -1073,199 +1495,6 @@ const buildArtifact = ({ elements, analyses, stats: cache }) => {
 	});
 };
 
-//#endregion
-//#region packages/builder/src/errors.ts
-/**
-* Error constructor helpers for concise error creation.
-*/
-const builderErrors = {
-	entryNotFound: (entry, message) => ({
-		code: "ENTRY_NOT_FOUND",
-		message: message ?? `Entry not found: ${entry}`,
-		entry
-	}),
-	configNotFound: (path, message) => ({
-		code: "CONFIG_NOT_FOUND",
-		message: message ?? `Config file not found: ${path}`,
-		path
-	}),
-	configInvalid: (path, message, cause) => ({
-		code: "CONFIG_INVALID",
-		message,
-		path,
-		cause
-	}),
-	discoveryIOError: (path, message, errno, cause) => ({
-		code: "DISCOVERY_IO_ERROR",
-		message,
-		path,
-		errno,
-		cause
-	}),
-	fingerprintFailed: (filePath, message, cause) => ({
-		code: "FINGERPRINT_FAILED",
-		message,
-		filePath,
-		cause
-	}),
-	unsupportedAnalyzer: (analyzer, message) => ({
-		code: "UNSUPPORTED_ANALYZER",
-		message: message ?? `Unsupported analyzer: ${analyzer}`,
-		analyzer
-	}),
-	canonicalPathInvalid: (path, reason) => ({
-		code: "CANONICAL_PATH_INVALID",
-		message: `Invalid canonical path: ${path}${reason ? ` (${reason})` : ""}`,
-		path,
-		reason
-	}),
-	canonicalScopeMismatch: (expected, actual) => ({
-		code: "CANONICAL_SCOPE_MISMATCH",
-		message: `Scope mismatch: expected ${expected}, got ${actual}`,
-		expected,
-		actual
-	}),
-	graphCircularDependency: (chain) => ({
-		code: "GRAPH_CIRCULAR_DEPENDENCY",
-		message: `Circular dependency detected: ${chain.join(" → ")}`,
-		chain
-	}),
-	graphMissingImport: (importer, importee) => ({
-		code: "GRAPH_MISSING_IMPORT",
-		message: `Missing import: "${importer}" imports "${importee}" but it's not in the graph`,
-		importer,
-		importee
-	}),
-	docDuplicate: (name, sources) => ({
-		code: "DOC_DUPLICATE",
-		message: `Duplicate document name: ${name} found in ${sources.length} files`,
-		name,
-		sources
-	}),
-	writeFailed: (outPath, message, cause) => ({
-		code: "WRITE_FAILED",
-		message,
-		outPath,
-		cause
-	}),
-	cacheCorrupted: (message, cachePath, cause) => ({
-		code: "CACHE_CORRUPTED",
-		message,
-		cachePath,
-		cause
-	}),
-	runtimeModuleLoadFailed: (filePath, astPath, message, cause) => ({
-		code: "RUNTIME_MODULE_LOAD_FAILED",
-		message,
-		filePath,
-		astPath,
-		cause
-	}),
-	artifactRegistrationFailed: (elementId, reason) => ({
-		code: "ARTIFACT_REGISTRATION_FAILED",
-		message: `Failed to register artifact element ${elementId}: ${reason}`,
-		elementId,
-		reason
-	}),
-	internalInvariant: (message, context, cause) => ({
-		code: "INTERNAL_INVARIANT",
-		message: `Internal invariant violated: ${message}`,
-		context,
-		cause
-	})
-};
-/**
-* Convenience helper to create an err Result from BuilderError.
-*/
-const builderErr = (error) => (0, neverthrow.err)(error);
-/**
-* Type guard for BuilderError.
-*/
-const isBuilderError = (error) => {
-	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
-};
-/**
-* Format BuilderError for console output (human-readable).
-*/
-const formatBuilderError = (error) => {
-	const lines = [];
-	lines.push(`Error [${error.code}]: ${error.message}`);
-	switch (error.code) {
-		case "ENTRY_NOT_FOUND":
-			lines.push(`  Entry: ${error.entry}`);
-			break;
-		case "CONFIG_NOT_FOUND":
-		case "CONFIG_INVALID":
-			lines.push(`  Path: ${error.path}`);
-			if (error.code === "CONFIG_INVALID" && error.cause) {
-				lines.push(`  Cause: ${error.cause}`);
-			}
-			break;
-		case "DISCOVERY_IO_ERROR":
-			lines.push(`  Path: ${error.path}`);
-			if (error.errno !== undefined) {
-				lines.push(`  Errno: ${error.errno}`);
-			}
-			break;
-		case "FINGERPRINT_FAILED":
-			lines.push(`  File: ${error.filePath}`);
-			break;
-		case "CANONICAL_PATH_INVALID":
-			lines.push(`  Path: ${error.path}`);
-			if (error.reason) {
-				lines.push(`  Reason: ${error.reason}`);
-			}
-			break;
-		case "CANONICAL_SCOPE_MISMATCH":
-			lines.push(`  Expected: ${error.expected}`);
-			lines.push(`  Actual: ${error.actual}`);
-			break;
-		case "GRAPH_CIRCULAR_DEPENDENCY":
-			lines.push(`  Chain: ${error.chain.join(" → ")}`);
-			break;
-		case "GRAPH_MISSING_IMPORT":
-			lines.push(`  Importer: ${error.importer}`);
-			lines.push(`  Importee: ${error.importee}`);
-			break;
-		case "DOC_DUPLICATE":
-			lines.push(`  Name: ${error.name}`);
-			lines.push(`  Sources:\n    ${error.sources.join("\n    ")}`);
-			break;
-		case "WRITE_FAILED":
-			lines.push(`  Output path: ${error.outPath}`);
-			break;
-		case "CACHE_CORRUPTED":
-			if (error.cachePath) {
-				lines.push(`  Cache path: ${error.cachePath}`);
-			}
-			break;
-		case "RUNTIME_MODULE_LOAD_FAILED":
-			lines.push(`  File: ${error.filePath}`);
-			lines.push(`  AST path: ${error.astPath}`);
-			break;
-		case "ARTIFACT_REGISTRATION_FAILED":
-			lines.push(`  Element ID: ${error.elementId}`);
-			lines.push(`  Reason: ${error.reason}`);
-			break;
-		case "INTERNAL_INVARIANT":
-			if (error.context) {
-				lines.push(`  Context: ${error.context}`);
-			}
-			break;
-	}
-	if ("cause" in error && error.cause && !["CONFIG_INVALID"].includes(error.code)) {
-		lines.push(`  Caused by: ${error.cause}`);
-	}
-	return lines.join("\n");
-};
-/**
-* Assert unreachable code path (for exhaustiveness checks).
-* This is the ONLY acceptable throw in builder code.
-*/
-const assertUnreachable = (value, context) => {
-	throw new Error(`Unreachable code path${context ? ` in ${context}` : ""}: received ${JSON.stringify(value)}`);
-};
-
 //#endregion
 //#region packages/builder/src/ast/common/scope.ts
 /**
@@ -1575,25 +1804,41 @@ const collectAllDefinitions$1 = ({ module: module$1, gqlIdentifiers, imports: _i
 		if (node.type === "CallExpression") {
 			const gqlCall = unwrapMethodChains$1(gqlIdentifiers, node);
 			if (gqlCall) {
-				const { astPath } = tracker.registerDefinition();
-				const isTopLevel = stack.length === 1;
-				let isExported = false;
-				let exportBinding;
-				if (isTopLevel && stack[0]) {
-					const topLevelName = stack[0].nameSegment;
-					if (exportBindings.has(topLevelName)) {
-						isExported = true;
-						exportBinding = exportBindings.get(topLevelName);
+				const needsAnonymousScope = tracker.currentDepth() === 0;
+				let anonymousScopeHandle;
+				if (needsAnonymousScope) {
+					const anonymousName = getAnonymousName("anonymous");
+					anonymousScopeHandle = tracker.enterScope({
+						segment: anonymousName,
+						kind: "expression",
+						stableKey: "anonymous"
+					});
+				}
+				try {
+					const { astPath } = tracker.registerDefinition();
+					const isTopLevel = stack.length === 1;
+					let isExported = false;
+					let exportBinding;
+					if (isTopLevel && stack[0]) {
+						const topLevelName = stack[0].nameSegment;
+						if (exportBindings.has(topLevelName)) {
+							isExported = true;
+							exportBinding = exportBindings.get(topLevelName);
+						}
+					}
+					handledCalls.push(node);
+					pending.push({
+						astPath,
+						isTopLevel,
+						isExported,
+						exportBinding,
+						expression: expressionFromCall(gqlCall)
+					});
+				} finally {
+					if (anonymousScopeHandle) {
+						tracker.exitScope(anonymousScopeHandle);
 					}
 				}
-				handledCalls.push(node);
-				pending.push({
-					astPath,
-					isTopLevel,
-					isExported,
-					exportBinding,
-					expression: expressionFromCall(gqlCall)
-				});
 				return;
 			}
 		}
@@ -1606,6 +1851,8 @@ const collectAllDefinitions$1 = ({ module: module$1, gqlIdentifiers, imports: _i
 							visit(decl.init, newStack);
 						});
 					}
+				} else if (decl.init) {
+					visit(decl.init, stack);
 				}
 			});
 			return;
@@ -1957,25 +2204,41 @@ const collectAllDefinitions = ({ sourceFile, identifiers, exports: exports$1 })
 		if (typescript.default.isCallExpression(node)) {
 			const gqlCall = unwrapMethodChains(identifiers, node);
 			if (gqlCall) {
-				const { astPath } = tracker.registerDefinition();
-				const isTopLevel = stack.length === 1;
-				let isExported = false;
-				let exportBinding;
-				if (isTopLevel && stack[0]) {
-					const topLevelName = stack[0].nameSegment;
-					if (exportBindings.has(topLevelName)) {
-						isExported = true;
-						exportBinding = exportBindings.get(topLevelName);
+				const needsAnonymousScope = tracker.currentDepth() === 0;
+				let anonymousScopeHandle;
+				if (needsAnonymousScope) {
+					const anonymousName = getAnonymousName("anonymous");
+					anonymousScopeHandle = tracker.enterScope({
+						segment: anonymousName,
+						kind: "expression",
+						stableKey: "anonymous"
+					});
+				}
+				try {
+					const { astPath } = tracker.registerDefinition();
+					const isTopLevel = stack.length === 1;
+					let isExported = false;
+					let exportBinding;
+					if (isTopLevel && stack[0]) {
+						const topLevelName = stack[0].nameSegment;
+						if (exportBindings.has(topLevelName)) {
+							isExported = true;
+							exportBinding = exportBindings.get(topLevelName);
+						}
+					}
+					handledCalls.push(node);
+					pending.push({
+						astPath,
+						isTopLevel,
+						isExported,
+						exportBinding,
+						expression: gqlCall.getText(sourceFile)
+					});
+				} finally {
+					if (anonymousScopeHandle) {
+						tracker.exitScope(anonymousScopeHandle);
 					}
 				}
-				handledCalls.push(node);
-				pending.push({
-					astPath,
-					isTopLevel,
-					isExported,
-					exportBinding,
-					expression: gqlCall.getText(sourceFile)
-				});
 				return;
 			}
 		}
@@ -2148,20 +2411,58 @@ const toEntryKey = (key) => {
 	return hasher.hash(key, "xxhash");
 };
 const PERSISTENCE_VERSION = "v1";
+/**
+* Validate persisted data structure.
+* Uses simple validation to detect corruption without strict schema.
+*/
+const isValidPersistedData = (data) => {
+	if (typeof data !== "object" || data === null) return false;
+	const record = data;
+	if (typeof record.version !== "string") return false;
+	if (typeof record.storage !== "object" || record.storage === null) return false;
+	for (const value of Object.values(record.storage)) {
+		if (!Array.isArray(value)) return false;
+		for (const entry of value) {
+			if (!Array.isArray(entry) || entry.length !== 2) return false;
+			if (typeof entry[0] !== "string") return false;
+			const envelope = entry[1];
+			if (typeof envelope !== "object" || envelope === null) return false;
+			const env = envelope;
+			if (typeof env.key !== "string" || typeof env.version !== "string") return false;
+		}
+	}
+	return true;
+};
 const createMemoryCache = ({ prefix = [], persistence } = {}) => {
 	const storage = new Map();
 	if (persistence?.enabled) {
 		try {
 			if ((0, node_fs.existsSync)(persistence.filePath)) {
 				const content = (0, node_fs.readFileSync)(persistence.filePath, "utf-8");
-				const data = JSON.parse(content);
-				if (data.version === PERSISTENCE_VERSION && data.storage) {
-					for (const [namespaceKey, entries] of Object.entries(data.storage)) {
-						const namespaceMap = new Map();
-						for (const [hashedKey, envelope] of entries) {
-							namespaceMap.set(hashedKey, envelope);
+				let parsed;
+				try {
+					parsed = JSON.parse(content);
+				} catch {
+					console.warn(`[cache] Corrupt cache file (invalid JSON), starting fresh: ${persistence.filePath}`);
+					try {
+						(0, node_fs.unlinkSync)(persistence.filePath);
+					} catch {}
+					parsed = null;
+				}
+				if (parsed) {
+					if (!isValidPersistedData(parsed)) {
+						console.warn(`[cache] Corrupt cache file (invalid structure), starting fresh: ${persistence.filePath}`);
+						try {
+							(0, node_fs.unlinkSync)(persistence.filePath);
+						} catch {}
+					} else if (parsed.version === PERSISTENCE_VERSION) {
+						for (const [namespaceKey, entries] of Object.entries(parsed.storage)) {
+							const namespaceMap = new Map();
+							for (const [hashedKey, envelope] of entries) {
+								namespaceMap.set(hashedKey, envelope);
+							}
+							storage.set(namespaceKey, namespaceMap);
 						}
-						storage.set(namespaceKey, namespaceMap);
 					}
 				}
 			}
@@ -2282,11 +2583,8 @@ const createMemoryCache = ({ prefix = [], persistence } = {}) => {
 					version: PERSISTENCE_VERSION,
 					storage: serialized
 				};
-				const dir = (0, node_path.dirname)(persistence.filePath);
-				if (!(0, node_fs.existsSync)(dir)) {
-					(0, node_fs.mkdirSync)(dir, { recursive: true });
-				}
-				(0, node_fs.writeFileSync)(persistence.filePath, JSON.stringify(data), "utf-8");
+				const fs = (0, __soda_gql_common.getPortableFS)();
+				fs.writeFileSyncAtomic(persistence.filePath, JSON.stringify(data));
 			} catch (error) {
 				console.warn(`[cache] Failed to save cache to ${persistence.filePath}:`, error);
 			}
@@ -3015,6 +3313,43 @@ const collectAffectedFiles = (input) => {
 //#endregion
 //#region packages/builder/src/session/builder-session.ts
 /**
+* Singleton state for beforeExit handler registration.
+* Ensures only one handler is registered regardless of how many sessions are created.
+*/
+const exitHandlerState = {
+	registered: false,
+	factories: new Set()
+};
+/**
+* Register a cache factory for save on process exit.
+* Uses singleton pattern to prevent multiple handler registrations.
+*/
+const registerExitHandler = (cacheFactory) => {
+	exitHandlerState.factories.add(cacheFactory);
+	if (!exitHandlerState.registered) {
+		exitHandlerState.registered = true;
+		process.on("beforeExit", () => {
+			for (const factory of exitHandlerState.factories) {
+				factory.save();
+			}
+		});
+	}
+};
+/**
+* Unregister a cache factory from the exit handler.
+*/
+const unregisterExitHandler = (cacheFactory) => {
+	exitHandlerState.factories.delete(cacheFactory);
+};
+/**
+* Reset exit handler state for testing.
+* @internal
+*/
+const __resetExitHandlerForTests = () => {
+	exitHandlerState.registered = false;
+	exitHandlerState.factories.clear();
+};
+/**
 * Create a new builder session.
 *
 * The session maintains in-memory state across builds to enable incremental processing.
@@ -3034,12 +3369,10 @@ const createBuilderSession = (options) => {
 		prefix: ["builder"],
 		persistence: {
 			enabled: true,
-			filePath: (0, node_path.join)(process.cwd(), ".cache", "soda-gql", "builder", "cache.json")
+			filePath: (0, node_path.join)(process.cwd(), "node_modules", ".cache", "soda-gql", "builder", "cache.json")
 		}
 	});
-	process.on("beforeExit", () => {
-		cacheFactory.save();
-	});
+	registerExitHandler(cacheFactory);
 	const graphqlHelper = createGraphqlSystemIdentifyHelper(config);
 	const ensureAstAnalyzer = (0, __soda_gql_common.cachedFn)(() => createAstAnalyzer({
 		analyzer: config.analyzer,
@@ -3183,6 +3516,7 @@ const createBuilderSession = (options) => {
 		getCurrentArtifact: () => state.lastArtifact,
 		dispose: () => {
 			cacheFactory.save();
+			unregisterExitHandler(cacheFactory);
 		}
 	};
 };
@@ -3329,4 +3663,8 @@ exports.createBuilderService = createBuilderService;
 exports.createBuilderSession = createBuilderSession;
 exports.createGraphqlSystemIdentifyHelper = createGraphqlSystemIdentifyHelper;
 exports.extractModuleAdjacency = extractModuleAdjacency;
+exports.formatBuilderErrorForCLI = formatBuilderErrorForCLI;
+exports.formatBuilderErrorStructured = formatBuilderErrorStructured;
+exports.loadArtifact = loadArtifact;
+exports.loadArtifactSync = loadArtifactSync;
 //# sourceMappingURL=index.cjs.map