@soda-gql/builder 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,820 @@
+import { CanonicalId, CanonicalId as CanonicalId$1, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker } from "@soda-gql/common";
+import { ZodSchema, z } from "zod";
+import * as neverthrow0 from "neverthrow";
+import { Result } from "neverthrow";
+import { Script } from "node:vm";
+import { AnyComposedOperation, AnyInlineOperation, AnyModel, AnySlice } from "@soda-gql/core";
+import { RuntimeComposedOperationInput, RuntimeInlineOperationInput, RuntimeModelInput, RuntimeSliceInput } from "@soda-gql/core/runtime";
+import { ResolvedSodaGqlConfig } from "@soda-gql/config";
+
+//#region packages/builder/src/intermediate-module/types.d.ts
+type IntermediateModule = {
+  readonly filePath: string;
+  readonly canonicalIds: readonly string[];
+  readonly sourceCode: string;
+  readonly transpiledCode: string;
+  readonly contentHash: string;
+  readonly script: Script;
+};
+type IntermediateArtifactElement = {
+  readonly type: "model";
+  readonly element: AnyModel;
+} | {
+  readonly type: "slice";
+  readonly element: AnySlice;
+} | {
+  readonly type: "operation";
+  readonly element: AnyComposedOperation;
+} | {
+  readonly type: "inlineOperation";
+  readonly element: AnyInlineOperation;
+};
+//#endregion
+//#region packages/builder/src/internal/graphql-system.d.ts
+type GraphqlSystemIdentifyHelper = {
+  readonly isGraphqlSystemFile: (input: {
+    filePath: string;
+  }) => boolean;
+  readonly isGraphqlSystemImportSpecifier: (input: {
+    filePath: string;
+    specifier: string;
+  }) => boolean;
+};
+/**
+ * Create a GraphqlSystemIdentifyHelper from the resolved config.
+ * Uses canonical path comparison to handle casing, symlinks, and aliases.
+ */
+declare const createGraphqlSystemIdentifyHelper: (config: ResolvedSodaGqlConfig) => GraphqlSystemIdentifyHelper;
+//#endregion
+//#region packages/builder/src/errors.d.ts
+/**
+ * Comprehensive error code taxonomy for Builder operations.
+ */
+type BuilderErrorCode = "ENTRY_NOT_FOUND" | "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "DISCOVERY_IO_ERROR" | "FINGERPRINT_FAILED" | "UNSUPPORTED_ANALYZER" | "CANONICAL_PATH_INVALID" | "CANONICAL_SCOPE_MISMATCH" | "GRAPH_CIRCULAR_DEPENDENCY" | "GRAPH_MISSING_IMPORT" | "DOC_DUPLICATE" | "WRITE_FAILED" | "CACHE_CORRUPTED" | "RUNTIME_MODULE_LOAD_FAILED" | "ARTIFACT_REGISTRATION_FAILED" | "INTERNAL_INVARIANT";
+/**
+ * Structured error type for all Builder operations.
+ */
+type BuilderError = {
+  readonly code: "ENTRY_NOT_FOUND";
+  readonly message: string;
+  readonly entry: string;
+} | {
+  readonly code: "CONFIG_NOT_FOUND";
+  readonly message: string;
+  readonly path: string;
+} | {
+  readonly code: "CONFIG_INVALID";
+  readonly message: string;
+  readonly path: string;
+  readonly cause?: unknown;
+} | {
+  readonly code: "DISCOVERY_IO_ERROR";
+  readonly message: string;
+  readonly path: string;
+  readonly errno?: string | number;
+  readonly cause?: unknown;
+} | {
+  readonly code: "FINGERPRINT_FAILED";
+  readonly message: string;
+  readonly filePath: string;
+  readonly cause?: unknown;
+} | {
+  readonly code: "UNSUPPORTED_ANALYZER";
+  readonly message: string;
+  readonly analyzer: string;
+} | {
+  readonly code: "CANONICAL_PATH_INVALID";
+  readonly message: string;
+  readonly path: string;
+  readonly reason?: string;
+} | {
+  readonly code: "CANONICAL_SCOPE_MISMATCH";
+  readonly message: string;
+  readonly expected: string;
+  readonly actual: string;
+} | {
+  readonly code: "GRAPH_CIRCULAR_DEPENDENCY";
+  readonly message: string;
+  readonly chain: readonly string[];
+} | {
+  readonly code: "GRAPH_MISSING_IMPORT";
+  readonly message: string;
+  readonly importer: string;
+  readonly importee: string;
+} | {
+  readonly code: "DOC_DUPLICATE";
+  readonly message: string;
+  readonly name: string;
+  readonly sources: readonly string[];
+} | {
+  readonly code: "WRITE_FAILED";
+  readonly message: string;
+  readonly outPath: string;
+  readonly cause?: unknown;
+} | {
+  readonly code: "CACHE_CORRUPTED";
+  readonly message: string;
+  readonly cachePath?: string;
+  readonly cause?: unknown;
+} | {
+  readonly code: "RUNTIME_MODULE_LOAD_FAILED";
+  readonly message: string;
+  readonly filePath: string;
+  readonly astPath: string;
+  readonly cause?: unknown;
+} | {
+  readonly code: "ARTIFACT_REGISTRATION_FAILED";
+  readonly message: string;
+  readonly elementId: string;
+  readonly reason: string;
+} | {
+  readonly code: "INTERNAL_INVARIANT";
+  readonly message: string;
+  readonly context?: string;
+  readonly cause?: unknown;
+};
+/**
+ * Helper type for Builder operation results.
+ */
+type BuilderResult<T> = Result<T, BuilderError>;
+/**
+ * Error constructor helpers for concise error creation.
+ */
+declare const builderErrors: {
+  readonly entryNotFound: (entry: string, message?: string) => BuilderError;
+  readonly configNotFound: (path: string, message?: string) => BuilderError;
+  readonly configInvalid: (path: string, message: string, cause?: unknown) => BuilderError;
+  readonly discoveryIOError: (path: string, message: string, errno?: string | number, cause?: unknown) => BuilderError;
+  readonly fingerprintFailed: (filePath: string, message: string, cause?: unknown) => BuilderError;
+  readonly unsupportedAnalyzer: (analyzer: string, message?: string) => BuilderError;
+  readonly canonicalPathInvalid: (path: string, reason?: string) => BuilderError;
+  readonly canonicalScopeMismatch: (expected: string, actual: string) => BuilderError;
+  readonly graphCircularDependency: (chain: readonly string[]) => BuilderError;
+  readonly graphMissingImport: (importer: string, importee: string) => BuilderError;
+  readonly docDuplicate: (name: string, sources: readonly string[]) => BuilderError;
+  readonly writeFailed: (outPath: string, message: string, cause?: unknown) => BuilderError;
+  readonly cacheCorrupted: (message: string, cachePath?: string, cause?: unknown) => BuilderError;
+  readonly runtimeModuleLoadFailed: (filePath: string, astPath: string, message: string, cause?: unknown) => BuilderError;
+  readonly artifactRegistrationFailed: (elementId: string, reason: string) => BuilderError;
+  readonly internalInvariant: (message: string, context?: string, cause?: unknown) => BuilderError;
+};
+/**
+ * Convenience helper to create an err Result from BuilderError.
+ */
+declare const builderErr: <T = never>(error: BuilderError) => BuilderResult<T>;
+/**
+ * Type guard for BuilderError.
+ */
+declare const isBuilderError: (error: unknown) => error is BuilderError;
+/**
+ * Format BuilderError for console output (human-readable).
+ */
+declare const formatBuilderError: (error: BuilderError) => string;
+/**
+ * Assert unreachable code path (for exhaustiveness checks).
+ * This is the ONLY acceptable throw in builder code.
+ */
+declare const assertUnreachable: (value: never, context?: string) => never;
+//#endregion
+//#region packages/builder/src/types.d.ts
+type BuilderMode = "runtime" | "zero-runtime";
+type BuilderFormat = "json" | "human";
+type BuilderAnalyzer = "ts" | "swc";
+type BuilderInput = Record<string, never>;
+type BuilderOptions = BuilderInput & {
+  readonly outPath: string;
+  readonly format: BuilderFormat;
+};
+//#endregion
+//#region packages/builder/src/ast/types.d.ts
+type SourcePosition = {
+  readonly line: number;
+  readonly column: number;
+};
+type SourceLocation = {
+  readonly start: SourcePosition;
+  readonly end: SourcePosition;
+};
+type ModuleDefinition = {
+  readonly canonicalId: CanonicalId$1;
+  /** AST-derived path uniquely identifying this definition's location (e.g., "MyComponent.useQuery.def") */
+  readonly astPath: string;
+  /** Whether this definition is at the top level of the module */
+  readonly isTopLevel: boolean;
+  /** Whether this definition is exported from the module */
+  readonly isExported: boolean;
+  /** The export binding name if this definition is exported */
+  readonly exportBinding?: string;
+  readonly loc: SourceLocation;
+  readonly expression: string;
+};
+type ModuleDiagnostic = {
+  readonly code: "NON_TOP_LEVEL_DEFINITION";
+  readonly message: string;
+  readonly loc: SourceLocation;
+};
+type ModuleImport = {
+  readonly source: string;
+  readonly imported: string;
+  readonly local: string;
+  readonly kind: "named" | "namespace" | "default";
+  readonly isTypeOnly: boolean;
+};
+type ModuleExport = {
+  readonly kind: "named";
+  readonly exported: string;
+  readonly local: string;
+  readonly source?: undefined;
+  readonly isTypeOnly: boolean;
+} | {
+  readonly kind: "reexport";
+  readonly exported: string;
+  readonly source: string;
+  readonly local?: string;
+  readonly isTypeOnly: boolean;
+};
+type ModuleAnalysis = {
+  readonly filePath: string;
+  readonly signature: string;
+  readonly definitions: readonly ModuleDefinition[];
+  readonly diagnostics: readonly ModuleDiagnostic[];
+  readonly imports: readonly ModuleImport[];
+  readonly exports: readonly ModuleExport[];
+};
+type AnalyzeModuleInput = {
+  readonly filePath: string;
+  readonly source: string;
+};
+//#endregion
+//#region packages/builder/src/ast/index.d.ts
+declare const createAstAnalyzer: ({
+  analyzer,
+  graphqlHelper
+}: {
+  readonly analyzer: BuilderAnalyzer;
+  readonly graphqlHelper: GraphqlSystemIdentifyHelper;
+}) => {
+  type: BuilderAnalyzer;
+  analyze: (input: AnalyzeModuleInput) => ModuleAnalysis;
+};
+declare const getAstAnalyzer: (analyzer: BuilderAnalyzer) => never;
+//#endregion
+//#region packages/builder/src/intermediate-module/evaluation.d.ts
+type BuildIntermediateModulesInput = {
+  readonly analyses: Map<string, ModuleAnalysis>;
+  readonly targetFiles: Set<string>;
+};
+/**
+ * Build intermediate modules from dependency graph.
+ * Each intermediate module corresponds to one source file.
+ */
+declare const generateIntermediateModules: ({
+  analyses,
+  targetFiles
+}: BuildIntermediateModulesInput) => Generator<IntermediateModule, void, undefined>;
+declare const evaluateIntermediateModules: ({
+  intermediateModules,
+  graphqlSystemPath
+}: {
+  intermediateModules: Map<string, IntermediateModule>;
+  graphqlSystemPath: string;
+}) => Record<string, IntermediateArtifactElement>;
+//#endregion
+//#region packages/builder/src/artifact/types.d.ts
+type IntermediateElements = Record<CanonicalId$1, IntermediateArtifactElement>;
+type BuilderArtifactElementMetadata = {
+  readonly sourcePath: string;
+  readonly sourceHash: string;
+  readonly contentHash: string;
+};
+type BuilderArtifactElementBase = {
+  readonly id: CanonicalId$1;
+  readonly metadata: BuilderArtifactElementMetadata;
+};
+type BuilderArtifactOperation = BuilderArtifactElementBase & {
+  readonly type: "operation";
+  readonly prebuild: RuntimeComposedOperationInput["prebuild"];
+};
+type BuilderArtifactInlineOperation = BuilderArtifactElementBase & {
+  readonly type: "inlineOperation";
+  readonly prebuild: RuntimeInlineOperationInput["prebuild"];
+};
+type BuilderArtifactSlice = BuilderArtifactElementBase & {
+  readonly type: "slice";
+  readonly prebuild: RuntimeSliceInput["prebuild"];
+};
+type BuilderArtifactModel = BuilderArtifactElementBase & {
+  readonly type: "model";
+  readonly prebuild: RuntimeModelInput["prebuild"];
+};
+type BuilderArtifactElement = BuilderArtifactOperation | BuilderArtifactInlineOperation | BuilderArtifactSlice | BuilderArtifactModel;
+type BuilderArtifact = {
+  readonly elements: Record<CanonicalId$1, BuilderArtifactElement>;
+  readonly report: {
+    readonly durationMs: number;
+    readonly warnings: readonly string[];
+    readonly stats: {
+      readonly hits: number;
+      readonly misses: number;
+      readonly skips: number;
+    };
+  };
+};
+//#endregion
+//#region packages/builder/src/discovery/fingerprint.d.ts
+/**
+ * File fingerprint containing hash, size, and modification time
+ */
+type FileFingerprint = {
+  /** xxHash hash of file contents */
+  hash: string;
+  /** File size in bytes */
+  sizeBytes: number;
+  /** Last modification time in milliseconds since epoch */
+  mtimeMs: number;
+};
+/**
+ * Fingerprint computation error types
+ */
+type FingerprintError = {
+  code: "FILE_NOT_FOUND";
+  path: string;
+  message: string;
+} | {
+  code: "NOT_A_FILE";
+  path: string;
+  message: string;
+} | {
+  code: "READ_ERROR";
+  path: string;
+  message: string;
+};
+/**
+ * Compute file fingerprint with memoization.
+ * Uses mtime to short-circuit re-hashing unchanged files.
+ *
+ * @param path - Absolute path to file
+ * @returns Result containing FileFingerprint or FingerprintError
+ */
+declare function computeFingerprint(path: string): Result<FileFingerprint, FingerprintError>;
+/**
+ * Invalidate cached fingerprint for a specific path
+ *
+ * @param path - Absolute path to invalidate
+ */
+declare function invalidateFingerprint(path: string): void;
+/**
+ * Clear all cached fingerprints
+ */
+declare function clearFingerprintCache(): void;
+//#endregion
+//#region packages/builder/src/discovery/types.d.ts
+/**
+ * Result of resolving a single import specifier encountered during discovery.
+ */
+type DiscoveredDependency = {
+  /** Module specifier exactly as it appeared in source. */
+  readonly specifier: string;
+  /** Absolute, normalized path when the specifier points to a local file; null for bare package imports. */
+  readonly resolvedPath: string | null;
+  /** True when the specifier targets an external package (i.e. no local snapshot will exist). */
+  readonly isExternal: boolean;
+};
+/**
+ * Immutable cacheable record produced by the discovery phase for a single source file.
+ * Captures analyzer output, dependency fan-out, and bookkeeping metadata.
+ */
+type DiscoverySnapshot = {
+  /** Absolute path to the analyzed file (preserves original casing). */
+  readonly filePath: string;
+  /** Normalized path (POSIX separators) used as a stable cache key. */
+  readonly normalizedFilePath: string;
+  /** Signature of the source contents used to validate cache entries. */
+  readonly signature: string;
+  /** File fingerprint for fast cache invalidation. */
+  readonly fingerprint: FileFingerprint;
+  /** Analyzer type identifier for cache versioning. */
+  readonly analyzer: string;
+  /** Milliseconds since epoch when this snapshot was created. */
+  readonly createdAtMs: number;
+  /** Raw analyzer output (imports, exports, definitions, diagnostics). */
+  readonly analysis: ModuleAnalysis;
+  /** Resolved graph edges for relative imports encountered in the file. */
+  readonly dependencies: readonly DiscoveredDependency[];
+};
+/**
+ * Cache abstraction for storing and retrieving discovery snapshots.
+ * Implementations can back onto disk, memory, or remote stores.
+ */
+interface DiscoveryCache {
+  /**
+   * Look up a snapshot by file path and signature.
+   * Returns null when the cache entry is missing or stale.
+   */
+  load(filePath: string, signature: string): DiscoverySnapshot | null;
+  /**
+   * Peek at cached snapshot without signature validation.
+   * Used for fingerprint-based cache invalidation.
+   * Returns null when the cache entry is missing.
+   */
+  peek(filePath: string): DiscoverySnapshot | null;
+  /**
+   * Persist the provided snapshot.
+   */
+  store(snapshot: DiscoverySnapshot): void;
+  /**
+   * Remove a snapshot when a file is deleted or invalidated.
+   */
+  delete(filePath: string): void;
+  /**
+   * Enumerate all cached snapshots (used to seed incremental builds).
+   */
+  entries(): IterableIterator<DiscoverySnapshot>;
+  /**
+   * Drop every cached entry (useful when analyzer versions change).
+   */
+  clear(): void;
+  /**
+   * Total number of entries currently stored.
+   */
+  size(): number;
+}
+type ModuleLoadStats = {
+  readonly hits: number;
+  readonly misses: number;
+  readonly skips: number;
+};
+//#endregion
+//#region packages/builder/src/schemas/artifact.d.ts
+declare const BuilderArtifactElementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+  type: z.ZodLiteral<"operation">;
+  metadata: z.ZodObject<{
+    sourcePath: z.ZodString;
+    sourceHash: z.ZodString;
+    contentHash: z.ZodString;
+  }, z.core.$strip>;
+  prebuild: z.ZodObject<{
+    operationType: z.ZodEnum<{
+      query: "query";
+      mutation: "mutation";
+      subscription: "subscription";
+    }>;
+    operationName: z.ZodString;
+    document: z.ZodUnknown;
+    variableNames: z.ZodArray<z.ZodString>;
+    projectionPathGraph: z.ZodUnknown;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+  id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+  type: z.ZodLiteral<"slice">;
+  metadata: z.ZodObject<{
+    sourcePath: z.ZodString;
+    sourceHash: z.ZodString;
+    contentHash: z.ZodString;
+  }, z.core.$strip>;
+  prebuild: z.ZodObject<{
+    operationType: z.ZodEnum<{
+      query: "query";
+      mutation: "mutation";
+      subscription: "subscription";
+    }>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+  id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+  type: z.ZodLiteral<"model">;
+  metadata: z.ZodObject<{
+    sourcePath: z.ZodString;
+    sourceHash: z.ZodString;
+    contentHash: z.ZodString;
+  }, z.core.$strip>;
+  prebuild: z.ZodObject<{
+    typename: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+declare const BuilderArtifactSchema: z.ZodObject<{
+  elements: z.ZodRecord<z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+    type: z.ZodLiteral<"operation">;
+    metadata: z.ZodObject<{
+      sourcePath: z.ZodString;
+      sourceHash: z.ZodString;
+      contentHash: z.ZodString;
+    }, z.core.$strip>;
+    prebuild: z.ZodObject<{
+      operationType: z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+        subscription: "subscription";
+      }>;
+      operationName: z.ZodString;
+      document: z.ZodUnknown;
+      variableNames: z.ZodArray<z.ZodString>;
+      projectionPathGraph: z.ZodUnknown;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+    type: z.ZodLiteral<"slice">;
+    metadata: z.ZodObject<{
+      sourcePath: z.ZodString;
+      sourceHash: z.ZodString;
+      contentHash: z.ZodString;
+    }, z.core.$strip>;
+    prebuild: z.ZodObject<{
+      operationType: z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+        subscription: "subscription";
+      }>;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    id: z.core.$ZodType<CanonicalId$1, CanonicalId$1, z.core.$ZodTypeInternals<CanonicalId$1, CanonicalId$1>>;
+    type: z.ZodLiteral<"model">;
+    metadata: z.ZodObject<{
+      sourcePath: z.ZodString;
+      sourceHash: z.ZodString;
+      contentHash: z.ZodString;
+    }, z.core.$strip>;
+    prebuild: z.ZodObject<{
+      typename: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>], "type">>;
+  report: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    warnings: z.ZodArray<z.ZodString>;
+    stats: z.ZodObject<{
+      hits: z.ZodNumber;
+      misses: z.ZodNumber;
+      skips: z.ZodNumber;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+type BuilderArtifact$1 = z.infer<typeof BuilderArtifactSchema>;
+type BuilderArtifactElement$1 = z.infer<typeof BuilderArtifactElementSchema>;
+//#endregion
+//#region packages/builder/src/service.d.ts
+/**
+ * Configuration for BuilderService.
+ * Mirrors BuilderInput shape.
+ */
+type BuilderServiceConfig = {
+  readonly config: ResolvedSodaGqlConfig;
+  readonly entrypointsOverride?: readonly string[] | ReadonlySet<string>;
+};
+/**
+ * Builder service interface providing artifact generation.
+ */
+interface BuilderService {
+  /**
+   * Generate artifacts from configured entry points.
+   *
+   * The service automatically detects file changes using an internal file tracker.
+   * On first call, performs full build. Subsequent calls perform incremental builds
+   * based on detected file changes (added/updated/removed).
+   *
+   * @param options - Optional build options
+   * @param options.force - If true, bypass change detection and force full rebuild
+   * @returns Result containing BuilderArtifact on success or BuilderError on failure.
+   */
+  build(options?: {
+    force?: boolean;
+  }): Result<BuilderArtifact, BuilderError>;
+  /**
+   * Get the current generation number of the artifact.
+   * Increments on each successful build.
+   * Returns 0 if no artifact has been built yet.
+   */
+  getGeneration(): number;
+  /**
+   * Get the most recent artifact without triggering a new build.
+   * Returns null if no artifact has been built yet.
+   */
+  getCurrentArtifact(): BuilderArtifact | null;
+}
+/**
+ * Create a builder service instance with session support.
+ *
+ * The service maintains a long-lived session for incremental builds.
+ * File changes are automatically detected using an internal file tracker.
+ * First build() call initializes the session, subsequent calls perform
+ * incremental builds based on detected file changes.
+ *
+ * Note: Empty entry arrays will produce ENTRY_NOT_FOUND errors at build time.
+ *
+ * @param config - Builder configuration including entry patterns, analyzer, mode, and optional debugDir
+ * @returns BuilderService instance
+ */
+declare const createBuilderService: ({
+  config,
+  entrypointsOverride
+}: BuilderServiceConfig) => BuilderService;
+//#endregion
+//#region packages/builder/src/cache/json-cache.d.ts
+type CacheNamespace = readonly string[];
+type JsonCacheFactoryOptions = {
+  readonly rootDir: string;
+  readonly prefix?: CacheNamespace;
+};
+type JsonCacheStoreOptions<_K extends string, V> = {
+  readonly namespace: CacheNamespace;
+  readonly schema: z.ZodType<V>;
+  readonly version?: string;
+};
+type JsonCacheStore<K extends string, V> = {
+  load(key: K): V | null;
+  store(key: K, value: V): void;
+  delete(key: K): void;
+  entries(): IterableIterator<[K, V]>;
+  clear(): void;
+  size(): number;
+};
+type JsonCacheFactory = {
+  createStore<K extends string, V>(options: JsonCacheStoreOptions<K, V>): JsonCacheStore<K, V>;
+  clearAll(): void;
+};
+declare const createJsonCache: ({
+  rootDir,
+  prefix
+}: JsonCacheFactoryOptions) => JsonCacheFactory;
+//#endregion
+//#region packages/builder/src/cache/json-entity-cache.d.ts
+type JsonEntityCacheOptions<V> = {
+  readonly factory: JsonCacheFactory;
+  readonly namespace: readonly string[];
+  readonly schema: ZodSchema<V>;
+  readonly version: string;
+  readonly keyNormalizer?: (key: string) => string;
+};
+/**
+ * Abstract base class for JSON-based entity caches.
+ * Provides common caching functionality with signature-based eviction.
+ */
+declare abstract class JsonEntityCache<K extends string, V> {
+  protected readonly cacheStore: JsonCacheStore<K, V>;
+  private readonly keyNormalizer;
+  constructor(options: JsonEntityCacheOptions<V>);
+  /**
+   * Normalize a key for consistent cache lookups.
+   */
+  protected normalizeKey(key: string): K;
+  /**
+   * Load raw value from cache without signature validation.
+   */
+  protected loadRaw(key: K): V | null;
+  /**
+   * Store raw value to cache.
+   */
+  protected storeRaw(key: K, value: V): void;
+  /**
+   * Delete an entry from the cache.
+   */
+  delete(key: string): void;
+  /**
+   * Get all cached entries.
+   * Subclasses should override this to provide custom iteration.
+   */
+  protected baseEntries(): IterableIterator<V>;
+  /**
+   * Clear all entries from the cache.
+   */
+  clear(): void;
+  /**
+   * Get the number of entries in the cache.
+   */
+  size(): number;
+}
+//#endregion
+//#region packages/builder/src/discovery/cache.d.ts
+type DiscoveryCacheOptions = {
+  readonly factory: JsonCacheFactory;
+  readonly analyzer: string;
+  readonly evaluatorId: string;
+  readonly namespacePrefix?: readonly string[];
+  readonly version?: string;
+};
+declare class JsonDiscoveryCache extends JsonEntityCache<string, DiscoverySnapshot> implements DiscoveryCache {
+  constructor(options: DiscoveryCacheOptions);
+  load(filePath: string, expectedSignature: string): DiscoverySnapshot | null;
+  peek(filePath: string): DiscoverySnapshot | null;
+  store(snapshot: DiscoverySnapshot): void;
+  entries(): IterableIterator<DiscoverySnapshot>;
+}
+declare const createDiscoveryCache: (options: DiscoveryCacheOptions) => DiscoveryCache;
+//#endregion
+//#region packages/builder/src/discovery/discoverer.d.ts
+type DiscoverModulesOptions = {
+  readonly entryPaths: readonly string[];
+  readonly astAnalyzer: ReturnType<typeof createAstAnalyzer>;
+  /** Set of file paths explicitly invalidated (from BuilderChangeSet) */
+  readonly incremental?: {
+    readonly cache: DiscoveryCache;
+    readonly changedFiles: Set<string>;
+    readonly removedFiles: Set<string>;
+    readonly affectedFiles: Set<string>;
+  };
+};
+type DiscoverModulesResult = {
+  readonly snapshots: readonly DiscoverySnapshot[];
+  readonly cacheHits: number;
+  readonly cacheMisses: number;
+  readonly cacheSkips: number;
+};
+/**
+ * Discover and analyze all modules starting from entry points.
+ * Uses AST parsing instead of RegExp for reliable dependency extraction.
+ * Supports caching with fingerprint-based invalidation to skip re-parsing unchanged files.
+ */
+declare const discoverModules: ({
+  entryPaths,
+  astAnalyzer,
+  incremental
+}: DiscoverModulesOptions) => BuilderResult<DiscoverModulesResult>;
+//#endregion
+//#region packages/builder/src/discovery/entry-paths.d.ts
+/**
+ * Resolve entry file paths from glob patterns or direct paths.
+ * Used by the discovery system to find entry points for module traversal.
+ * All paths are normalized to POSIX format for consistent cache key matching.
+ * Uses Node.js normalize() + backslash replacement to match normalizePath from @soda-gql/common.
+ */
+declare const resolveEntryPaths: (entries: readonly string[]) => neverthrow0.Err<readonly string[], BuilderError> | neverthrow0.Ok<readonly string[], BuilderError>;
+//#endregion
+//#region packages/builder/src/artifact/builder.d.ts
+type BuildArtifactInput = {
+  readonly elements: IntermediateElements;
+  readonly analyses: ReadonlyMap<string, ModuleAnalysis>;
+  readonly stats: ModuleLoadStats;
+};
+declare const buildArtifact: ({
+  elements,
+  analyses,
+  stats: cache
+}: BuildArtifactInput) => Result<BuilderArtifact, BuilderError>;
+//#endregion
+//#region packages/builder/src/session/builder-session.d.ts
+/**
+ * Builder session interface for incremental builds.
+ */
+interface BuilderSession {
+  /**
+   * Perform build fully or incrementally.
+   * The session automatically detects file changes using the file tracker.
+   */
+  build(options?: {
+    force?: boolean;
+  }): Result<BuilderArtifact, BuilderError>;
+  /**
+   * Get the current generation number.
+   */
+  getGeneration(): number;
+  /**
+   * Get the current artifact.
+   */
+  getCurrentArtifact(): BuilderArtifact | null;
+}
+/**
+ * Create a new builder session.
+ *
+ * The session maintains in-memory state across builds to enable incremental processing.
+ */
+declare const createBuilderSession: (options: {
+  readonly evaluatorId?: string;
+  readonly entrypointsOverride?: readonly string[] | ReadonlySet<string>;
+  readonly config: ResolvedSodaGqlConfig;
+}) => BuilderSession;
+//#endregion
+//#region packages/builder/src/session/dependency-validation.d.ts
+type DependencyGraphError = {
+  readonly code: "MISSING_IMPORT";
+  readonly chain: readonly [importingFile: string, importSpecifier: string];
+};
+declare const validateModuleDependencies: ({
+  analyses
+}: {
+  analyses: Map<string, ModuleAnalysis>;
+}) => Result<null, DependencyGraphError>;
+//#endregion
+//#region packages/builder/src/session/module-adjacency.d.ts
+/**
+ * Extract module-level adjacency from dependency graph.
+ * Returns Map of file path -> set of files that import it.
+ * All paths are normalized to POSIX format for consistent cache key matching.
+ */
+declare const extractModuleAdjacency: ({
+  snapshots
+}: {
+  snapshots: Map<string, DiscoverySnapshot>;
+}) => Map<string, Set<string>>;
+/**
+ * Collect all modules affected by changes, including transitive dependents.
+ * Uses BFS to traverse module adjacency graph.
+ * All paths are already normalized from extractModuleAdjacency.
+ */
+declare const collectAffectedFiles: (input: {
+  changedFiles: Set<string>;
+  removedFiles: Set<string>;
+  previousModuleAdjacency: Map<string, Set<string>>;
+}) => Set<string>;
+//#endregion
+export { type BuilderAnalyzer, type BuilderArtifact, type BuilderArtifactElement, type BuilderArtifactElementMetadata, type BuilderArtifactInlineOperation, type BuilderArtifactModel, type BuilderArtifactOperation, BuilderArtifactSchema, type BuilderArtifactSlice, type BuilderError, type BuilderFormat, type BuilderInput, type BuilderMode, type BuilderOptions, type BuilderService, type BuilderServiceConfig, type BuilderSession, type CanonicalId, type CanonicalPathTracker, type DiscoveredDependency, type DiscoveryCache, type DiscoverySnapshot, type ScopeFrame, type ScopeHandle, buildAstPath, createBuilderService, createBuilderSession, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+//# sourceMappingURL=index.d.ts.map