@soda-gql/builder 0.7.0 → 0.8.0

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);
 		}
 	}
 };
@@ -915,47 +1378,6 @@ const createGraphqlSystemIdentifyHelper = (config) => {
 	};
 };
 
-//#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()
-		})
-	})
-});
-
 //#endregion
 //#region packages/builder/src/artifact/aggregate.ts
 const canonicalToFilePath$1 = (canonicalId) => canonicalId.split("::")[0] ?? canonicalId;
@@ -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
 /**
@@ -3034,7 +3263,7 @@ 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", () => {
@@ -3329,4 +3558,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