@demokit-ai/core 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -263,6 +263,134 @@ interface ParsedPattern {
      */
     paramNames: string[];
 }
+/**
+ * Configuration for fetching fixtures from DemoKit Cloud
+ */
+interface RemoteConfig {
+    /**
+     * DemoKit Cloud API key
+     * Format: dk_live_xxxx
+     */
+    apiKey: string;
+    /**
+     * DemoKit Cloud API URL
+     * @default 'https://api.demokit.cloud'
+     */
+    cloudUrl?: string;
+    /**
+     * Error callback for remote fetch failures
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when fixtures are successfully loaded
+     */
+    onLoad?: (response: CloudFixtureResponse) => void;
+    /**
+     * Timeout for API requests in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * Whether to retry on failure
+     * @default true
+     */
+    retry?: boolean;
+    /**
+     * Maximum number of retries
+     * @default 3
+     */
+    maxRetries?: number;
+}
+/**
+ * Response from DemoKit Cloud /api/v1/fixtures endpoint
+ */
+interface CloudFixtureResponse {
+    /**
+     * The generated fixture data (keyed by model name)
+     * @example { users: [{ id: '1', name: 'Alice' }], products: [...] }
+     */
+    data: Record<string, unknown[]>;
+    /**
+     * Endpoint-to-data mappings for SDK auto-configuration
+     */
+    mappings: EndpointMapping[];
+    /**
+     * Version identifier (generation ID) for cache invalidation
+     */
+    version: string;
+}
+/**
+ * An endpoint mapping that describes how to route API calls to fixture data
+ */
+interface EndpointMapping {
+    /**
+     * HTTP method (GET, POST, PUT, PATCH, DELETE)
+     */
+    method: string;
+    /**
+     * URL pattern with :param placeholders
+     * @example '/api/users/:id'
+     */
+    pattern: string;
+    /**
+     * Key in fixture data to use as source
+     * @example 'users'
+     */
+    sourceModel: string;
+    /**
+     * Response type:
+     * - 'collection': Returns all records (array)
+     * - 'single': Returns one record by lookup
+     * - 'custom': Uses custom transform (not yet supported in SDK)
+     */
+    responseType: 'collection' | 'single' | 'custom';
+    /**
+     * For 'single' type: field in data to match against
+     * @example 'id'
+     */
+    lookupField?: string | null;
+    /**
+     * For 'single' type: URL param name to use for lookup
+     * @example 'id' (from :id in pattern)
+     */
+    lookupParam?: string | null;
+}
+/**
+ * Combined configuration for DemoKit with optional remote support
+ */
+interface DemoKitRemoteConfig extends Omit<DemoKitConfig, 'fixtures'> {
+    /**
+     * Remote configuration for fetching from DemoKit Cloud
+     * When provided, fixtures are fetched from the cloud
+     */
+    remote: RemoteConfig;
+    /**
+     * Local fixture overrides that take precedence over remote fixtures
+     * Useful for customizing specific endpoints while using cloud data for the rest
+     */
+    fixtures?: FixtureMap;
+}
+/**
+ * State of remote fixture loading
+ */
+interface RemoteLoadingState {
+    /**
+     * Whether fixtures are currently being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Error if loading failed
+     */
+    error: Error | null;
+    /**
+     * The loaded response (if successful)
+     */
+    response: CloudFixtureResponse | null;
+    /**
+     * Timestamp of last successful load
+     */
+    loadedAt: Date | null;
+}
 
 /**
  * Create a demo interceptor that patches fetch to return mock data
@@ -562,4 +690,2189 @@ declare function saveDemoState(key: string | undefined, enabled: boolean): void;
  */
 declare function clearDemoState(key?: string): void;
 
-export { DEFAULT_STORAGE_KEY, type DemoInterceptor, type DemoKitConfig, type DemoState, type DemoStateStore, type DemoStateStoreOptions, type FixtureHandler, type FixtureMap, type MatchResult, type ParsedPattern, type QueryKey, type QueryKeyElement, type QueryKeyMatchResult, type RequestContext, type SessionState, clearDemoState, clearPatternCache, createDemoInterceptor, createDemoState, createDemoStateStore, createSessionState, findMatchingPattern, findMatchingQueryKeyPattern, loadDemoState, matchQueryKey, matchUrl, parseUrlPattern, saveDemoState };
+/**
+ * Remote Configuration Support for DemoKit Cloud
+ *
+ * Provides functions to fetch fixture data and endpoint mappings from DemoKit Cloud
+ * and transform them into FixtureMap handlers that can be used with the demo interceptor.
+ *
+ * @example
+ * ```typescript
+ * import { fetchCloudFixtures, buildFixtureMap } from '@demokit-ai/core'
+ *
+ * const response = await fetchCloudFixtures({
+ *   apiKey: 'dk_live_xxx',
+ * })
+ *
+ * const fixtureMap = buildFixtureMap(response.data, response.mappings)
+ * ```
+ */
+
+/**
+ * Default DemoKit Cloud API URL
+ */
+declare const DEFAULT_CLOUD_URL = "https://api.demokit.cloud";
+/**
+ * Default request timeout in milliseconds
+ */
+declare const DEFAULT_TIMEOUT = 10000;
+/**
+ * Default maximum retries
+ */
+declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Validate API key format
+ */
+declare function isValidApiKey(apiKey: string): boolean;
+/**
+ * Error thrown when remote fetch fails
+ */
+declare class RemoteFetchError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly retryable: boolean;
+    constructor(message: string, statusCode?: number | undefined, retryable?: boolean);
+}
+/**
+ * Fetch fixtures and mappings from DemoKit Cloud
+ *
+ * @param config - Remote configuration with API key and options
+ * @returns Promise resolving to cloud fixture response with data, mappings, and version
+ * @throws RemoteFetchError if the request fails
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchCloudFixtures({
+ *   apiKey: 'dk_live_xxx',
+ *   onLoad: (data) => console.log('Loaded version:', data.version),
+ *   onError: (error) => console.error('Failed to load:', error),
+ * })
+ * ```
+ */
+declare function fetchCloudFixtures(config: RemoteConfig): Promise<CloudFixtureResponse>;
+/**
+ * Build a FixtureMap from cloud data and endpoint mappings
+ *
+ * Transforms endpoint mappings into fixture handlers that can be used
+ * with the demo interceptor. Each mapping becomes a pattern-matched
+ * handler that returns the appropriate data.
+ *
+ * @param data - Fixture data keyed by model name (e.g., { users: [...], products: [...] })
+ * @param mappings - Endpoint mappings from DemoKit Cloud
+ * @returns FixtureMap that can be passed to createDemoInterceptor
+ *
+ * @example
+ * ```typescript
+ * const fixtureMap = buildFixtureMap(
+ *   { users: [{ id: '1', name: 'Alice' }] },
+ *   [
+ *     { method: 'GET', pattern: '/api/users', sourceModel: 'users', responseType: 'collection' },
+ *     { method: 'GET', pattern: '/api/users/:id', sourceModel: 'users', responseType: 'single', lookupField: 'id', lookupParam: 'id' },
+ *   ]
+ * )
+ *
+ * // Result:
+ * // {
+ * //   'GET /api/users': () => [{ id: '1', name: 'Alice' }],
+ * //   'GET /api/users/:id': ({ params }) => users.find(u => u.id === params.id),
+ * // }
+ * ```
+ */
+declare function buildFixtureMap(data: Record<string, unknown[]>, mappings: EndpointMapping[]): FixtureMap;
+/**
+ * Create a fixture handler for a single endpoint mapping
+ *
+ * @param mapping - The endpoint mapping configuration
+ * @param sourceData - The source data array for this mapping
+ * @returns A fixture handler function or undefined if mapping is invalid
+ */
+declare function createHandlerForMapping(mapping: EndpointMapping, sourceData: unknown[]): FixtureHandler | undefined;
+/**
+ * Merge remote fixtures with local overrides
+ *
+ * Creates a combined FixtureMap where local fixtures take precedence
+ * over remote fixtures for the same patterns.
+ *
+ * @param remoteFixtures - Fixtures built from cloud mappings
+ * @param localOverrides - Local fixtures that override remote ones
+ * @returns Merged FixtureMap
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeFixtures(remoteFixtures, {
+ *   // Override specific endpoint with custom logic
+ *   'POST /api/users': ({ body }) => ({ id: 'custom', ...body }),
+ * })
+ * ```
+ */
+declare function mergeFixtures(remoteFixtures: FixtureMap, localOverrides?: FixtureMap): FixtureMap;
+/**
+ * Create a complete fixture setup from cloud response and optional overrides
+ *
+ * Convenience function that combines buildFixtureMap and mergeFixtures.
+ *
+ * @param response - Cloud fixture response
+ * @param localOverrides - Optional local fixtures to merge
+ * @returns Complete FixtureMap ready for use with createDemoInterceptor
+ */
+declare function createRemoteFixtures(response: CloudFixtureResponse, localOverrides?: FixtureMap): FixtureMap;
+
+/**
+ * Core types for DemoKit schema representation
+ *
+ * These types represent a parsed API schema with relationship detection,
+ * independent of the source format (OpenAPI, GraphQL, etc.)
+ */
+/**
+ * The main schema representation for DemoKit
+ * Contains all information needed for fixture generation
+ */
+interface DemokitSchema {
+    /**
+     * Metadata about the API
+     */
+    info: SchemaInfo;
+    /**
+     * All API endpoints discovered from the spec
+     */
+    endpoints: Endpoint[];
+    /**
+     * All data models (schemas) from the spec
+     */
+    models: Record<string, DataModel>;
+    /**
+     * Detected relationships between models
+     */
+    relationships: Relationship[];
+}
+/**
+ * API metadata
+ */
+interface SchemaInfo {
+    /**
+     * API title from the spec
+     */
+    title: string;
+    /**
+     * API version
+     */
+    version: string;
+    /**
+     * Optional description
+     */
+    description?: string;
+    /**
+     * Base URL for the API (if specified)
+     */
+    baseUrl?: string;
+}
+/**
+ * An API endpoint
+ */
+interface Endpoint {
+    /**
+     * HTTP method (GET, POST, PUT, PATCH, DELETE)
+     */
+    method: HttpMethod;
+    /**
+     * URL path with parameter placeholders
+     * @example "/users/{id}" or "/orders/{orderId}/items"
+     */
+    path: string;
+    /**
+     * Operation ID from OpenAPI (if available)
+     */
+    operationId?: string;
+    /**
+     * Human-readable summary
+     */
+    summary?: string;
+    /**
+     * Detailed description
+     */
+    description?: string;
+    /**
+     * Path parameters
+     */
+    pathParams: ParameterDef[];
+    /**
+     * Query parameters
+     */
+    queryParams: ParameterDef[];
+    /**
+     * Request body schema (for POST/PUT/PATCH)
+     */
+    requestBody?: RequestBody;
+    /**
+     * Response schemas by status code
+     */
+    responses: Record<string, ResponseDef>;
+    /**
+     * Tags for grouping endpoints
+     */
+    tags: string[];
+}
+/**
+ * HTTP methods supported
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * A request or response body definition
+ */
+interface RequestBody {
+    /**
+     * Content type (usually application/json)
+     */
+    contentType: string;
+    /**
+     * Reference to the model name, or inline schema
+     */
+    schema: SchemaRef | DataModel;
+    /**
+     * Whether the body is required
+     */
+    required: boolean;
+    /**
+     * Description of the body
+     */
+    description?: string;
+}
+/**
+ * A response definition
+ */
+interface ResponseDef {
+    /**
+     * HTTP status code
+     */
+    statusCode: string;
+    /**
+     * Description of the response
+     */
+    description?: string;
+    /**
+     * Content type to schema mapping
+     */
+    content?: Record<string, SchemaRef | DataModel>;
+}
+/**
+ * A parameter definition (path or query)
+ */
+interface ParameterDef {
+    /**
+     * Parameter name
+     */
+    name: string;
+    /**
+     * Where the parameter is located
+     */
+    in: 'path' | 'query' | 'header' | 'cookie';
+    /**
+     * Whether the parameter is required
+     */
+    required: boolean;
+    /**
+     * Parameter type
+     */
+    type: PropertyType;
+    /**
+     * Optional format hint
+     */
+    format?: string;
+    /**
+     * Description
+     */
+    description?: string;
+    /**
+     * Example value
+     */
+    example?: unknown;
+}
+/**
+ * Reference to another schema/model
+ */
+interface SchemaRef {
+    /**
+     * The referenced model name
+     */
+    $ref: string;
+}
+/**
+ * A data model representing an object schema
+ */
+interface DataModel {
+    /**
+     * Model name (from the schema component name)
+     */
+    name: string;
+    /**
+     * The type of this model
+     */
+    type: ModelType;
+    /**
+     * Description from the spec
+     */
+    description?: string;
+    /**
+     * Properties for object types
+     */
+    properties?: Record<string, PropertyDef>;
+    /**
+     * Required property names
+     */
+    required?: string[];
+    /**
+     * For array types, the item schema
+     */
+    items?: SchemaRef | DataModel;
+    /**
+     * Enum values for enum types
+     */
+    enum?: unknown[];
+    /**
+     * Example value from the spec
+     */
+    example?: unknown;
+    /**
+     * Additional properties schema (for dictionaries)
+     */
+    additionalProperties?: boolean | SchemaRef | DataModel;
+}
+/**
+ * Model types
+ */
+type ModelType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+/**
+ * A property definition within a model
+ */
+interface PropertyDef {
+    /**
+     * Property name
+     */
+    name: string;
+    /**
+     * Property type
+     */
+    type: PropertyType;
+    /**
+     * Format hint (uuid, email, date-time, etc.)
+     */
+    format?: string;
+    /**
+     * Description
+     */
+    description?: string;
+    /**
+     * Whether this property is required
+     */
+    required?: boolean;
+    /**
+     * Whether this property is nullable
+     */
+    nullable?: boolean;
+    /**
+     * Enum values for string enums
+     */
+    enum?: unknown[];
+    /**
+     * For array types, the item schema
+     */
+    items?: SchemaRef | DataModel;
+    /**
+     * Reference to another model (for $ref properties)
+     */
+    $ref?: string;
+    /**
+     * Example value
+     */
+    example?: unknown;
+    /**
+     * Default value
+     */
+    default?: unknown;
+    /**
+     * Minimum value (for numbers)
+     */
+    minimum?: number;
+    /**
+     * Maximum value (for numbers)
+     */
+    maximum?: number;
+    /**
+     * Min length (for strings)
+     */
+    minLength?: number;
+    /**
+     * Max length (for strings)
+     */
+    maxLength?: number;
+    /**
+     * Pattern (regex for strings)
+     */
+    pattern?: string;
+    /**
+     * Detected relationship to another model
+     * Set by relationship detection, not directly from spec
+     */
+    relationshipTo?: RelationshipTarget;
+    /**
+     * Custom extension for explicit relationship hints
+     * @example "x-demokit-relationship": { "model": "User", "field": "id" }
+     */
+    'x-demokit-relationship'?: RelationshipTarget;
+}
+/**
+ * Property types
+ */
+type PropertyType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+/**
+ * A detected relationship between two models
+ */
+interface Relationship {
+    /**
+     * The source side of the relationship
+     */
+    from: RelationshipSide;
+    /**
+     * The target side of the relationship
+     */
+    to: RelationshipSide;
+    /**
+     * Type of relationship
+     */
+    type: RelationshipType;
+    /**
+     * Whether the relationship is required (not nullable)
+     */
+    required: boolean;
+    /**
+     * How this relationship was detected
+     */
+    detectedBy: RelationshipDetectionMethod;
+}
+/**
+ * One side of a relationship
+ */
+interface RelationshipSide {
+    /**
+     * Model name
+     */
+    model: string;
+    /**
+     * Field name
+     */
+    field: string;
+}
+/**
+ * Target for a relationship from a property
+ */
+interface RelationshipTarget {
+    /**
+     * Target model name
+     */
+    model: string;
+    /**
+     * Target field (usually "id")
+     */
+    field: string;
+}
+/**
+ * Types of relationships between models
+ */
+type RelationshipType = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/**
+ * How a relationship was detected
+ */
+type RelationshipDetectionMethod = 'explicit-ref' | 'naming-convention' | 'x-demokit-extension' | 'inferred';
+/**
+ * Helper type to check if something is a schema reference
+ */
+declare function isSchemaRef(value: unknown): value is SchemaRef;
+/**
+ * Extract the model name from a $ref string
+ * @example "#/components/schemas/User" -> "User"
+ */
+declare function extractRefName(ref: string): string;
+
+/**
+ * OpenAPI 3.x parser for DemoKit
+ *
+ * Parses OpenAPI specs into DemoKit's internal schema representation
+ * with automatic relationship detection.
+ *
+ * Uses @scalar/openapi-parser - a modern, webpack-compatible parser.
+ */
+
+/**
+ * Options for parsing OpenAPI specs
+ */
+interface ParseOptions {
+    /**
+     * Whether to dereference all $ref pointers
+     * @default true
+     */
+    dereference?: boolean;
+    /**
+     * Whether to detect relationships automatically
+     * @default true
+     */
+    detectRelationships?: boolean;
+    /**
+     * Whether to include response schemas in models
+     * @default true
+     */
+    includeResponses?: boolean;
+}
+/**
+ * Parse an OpenAPI spec from a file path or URL
+ */
+declare function parseOpenAPIFromPath(pathOrUrl: string, options?: ParseOptions): Promise<DemokitSchema>;
+/**
+ * Parse an OpenAPI spec from a string (JSON or YAML)
+ */
+declare function parseOpenAPIFromString(spec: string, options?: ParseOptions): Promise<DemokitSchema>;
+/**
+ * Parse an OpenAPI spec from an already-parsed object
+ */
+declare function parseOpenAPIFromObject(spec: Record<string, unknown>, options?: ParseOptions): Promise<DemokitSchema>;
+
+/**
+ * Types for codebase schema parsers.
+ * These types define the interface for parsing various schema formats
+ * (TypeScript, Zod, Drizzle, Prisma, etc.) into DemokitSchema.
+ */
+
+/**
+ * Supported schema formats that can be parsed from codebases.
+ */
+type SchemaFormat = 'typescript' | 'zod' | 'drizzle' | 'prisma' | 'graphql' | 'supabase' | 'trpc' | 'nextjs' | 'openapi' | 'auto';
+/**
+ * A file to be parsed, with path and content.
+ */
+interface CodebaseFile {
+    /**
+     * Relative or absolute file path.
+     */
+    path: string;
+    /**
+     * File content as a string.
+     */
+    content: string;
+}
+/**
+ * Options for parsing codebase schemas.
+ */
+interface ParseSchemaOptions {
+    /**
+     * The format to parse as. Use 'auto' to detect.
+     * @default 'auto'
+     */
+    format?: SchemaFormat;
+    /**
+     * Schema/API name for the output.
+     * @default 'Codebase Schema'
+     */
+    name?: string;
+    /**
+     * Schema version.
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * Whether to detect relationships between models.
+     * @default true
+     */
+    detectRelationships?: boolean;
+    /**
+     * Whether to include inferred relationships from naming conventions.
+     * @default true
+     */
+    inferRelationships?: boolean;
+}
+/**
+ * Result of parsing with additional metadata.
+ */
+interface ParseResult {
+    /**
+     * The parsed schema.
+     */
+    schema: DemokitSchema;
+    /**
+     * The format that was detected/used.
+     */
+    format: SchemaFormat;
+    /**
+     * Any warnings encountered during parsing.
+     */
+    warnings: ParseWarning[];
+    /**
+     * Files that were parsed.
+     */
+    parsedFiles: string[];
+}
+/**
+ * A warning encountered during parsing.
+ */
+interface ParseWarning {
+    /**
+     * Warning code for programmatic handling.
+     */
+    code: string;
+    /**
+     * Human-readable message.
+     */
+    message: string;
+    /**
+     * File where the warning occurred.
+     */
+    file?: string;
+    /**
+     * Line number where the warning occurred.
+     */
+    line?: number;
+}
+/**
+ * Detection result for schema format.
+ */
+interface FormatDetectionResult {
+    /**
+     * The detected format, or null if unknown.
+     */
+    format: SchemaFormat | null;
+    /**
+     * Confidence score from 0-1.
+     */
+    confidence: number;
+    /**
+     * Evidence that led to this detection.
+     */
+    evidence: string[];
+}
+/**
+ * Patterns for detecting schema formats from file content.
+ */
+interface FormatDetectionPatterns {
+    /**
+     * File path patterns (globs).
+     */
+    pathPatterns: string[];
+    /**
+     * Keywords/patterns to search for in content.
+     */
+    contentPatterns: string[];
+    /**
+     * File extensions to match.
+     */
+    extensions: string[];
+}
+
+/**
+ * Format detection utilities for codebase schema files.
+ * Detects which schema format (TypeScript, Zod, Drizzle, Prisma, etc.)
+ * a given file or content is written in.
+ */
+
+/**
+ * Detection patterns for each schema format.
+ */
+declare const FORMAT_PATTERNS: Record<Exclude<SchemaFormat, 'auto'>, FormatDetectionPatterns>;
+/**
+ * Priority order when multiple formats are detected.
+ * Formats earlier in the list take precedence.
+ */
+declare const FORMAT_PRIORITY: SchemaFormat[];
+/**
+ * Detect the schema format of a single file.
+ */
+declare function detectFormat(file: CodebaseFile): FormatDetectionResult;
+/**
+ * Detect the primary schema format from multiple files.
+ * Returns the format with highest total confidence.
+ */
+declare function detectFormatFromFiles(files: CodebaseFile[]): FormatDetectionResult;
+/**
+ * Group files by their detected format.
+ */
+declare function groupFilesByFormat(files: CodebaseFile[]): Map<SchemaFormat, CodebaseFile[]>;
+
+/**
+ * TypeScript interface/type parser.
+ * Parses TypeScript interface and type declarations into DemokitSchema.
+ *
+ * Supports:
+ * - interface declarations
+ * - type aliases (object types)
+ * - enum declarations
+ * - Generic types (partial support)
+ * - Union/intersection types (partial support)
+ * - Array types
+ * - Optional properties
+ * - JSDoc comments for descriptions
+ */
+
+/**
+ * Parse TypeScript files containing interface/type definitions.
+ */
+declare function parseTypeScript(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Zod schema parser.
+ * Parses Zod validation schemas into DemokitSchema.
+ *
+ * Supports:
+ * - z.object() schemas
+ * - z.string(), z.number(), z.boolean() primitives
+ * - z.array() and z.tuple()
+ * - z.enum() and z.nativeEnum()
+ * - z.optional(), z.nullable()
+ * - z.union(), z.intersection()
+ * - z.lazy() for recursive types
+ * - .describe() for descriptions
+ * - .default() values
+ * - String validations (.email(), .uuid(), .url(), etc.)
+ * - Number validations (.min(), .max(), .int())
+ */
+
+/**
+ * Parse Zod schema files into DemokitSchema.
+ */
+declare function parseZod(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Drizzle ORM schema parser.
+ * Parses Drizzle table definitions and relations into DemokitSchema.
+ *
+ * Supports:
+ * - pgTable(), mysqlTable(), sqliteTable() definitions
+ * - Column types (text, integer, boolean, uuid, timestamp, etc.)
+ * - Primary keys, foreign keys, unique constraints
+ * - relations() function for explicit relationships
+ * - Default values
+ * - Nullable columns
+ *
+ * This parser extracts high-fidelity relationship information
+ * since Drizzle uses explicit relations() declarations.
+ */
+
+/**
+ * Parse Drizzle schema files into DemokitSchema.
+ */
+declare function parseDrizzle(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Prisma schema parser.
+ * Parses Prisma schema files (.prisma) into DemokitSchema.
+ *
+ * Supports:
+ * - model definitions with fields
+ * - Field types (String, Int, Float, Boolean, DateTime, etc.)
+ * - @id, @unique, @default attributes
+ * - @relation for relationships
+ * - Optional fields (?)
+ * - Array fields ([])
+ * - Enums
+ * - @map and @@map for custom names
+ *
+ * Prisma schemas have explicit relationship definitions,
+ * providing high-fidelity relationship detection.
+ */
+
+/**
+ * Parse Prisma schema files into DemokitSchema.
+ */
+declare function parsePrisma(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * GraphQL SDL parser.
+ * Parses GraphQL schema files (.graphql, .gql) into DemokitSchema.
+ *
+ * Supports:
+ * - type definitions (type, interface, input, enum)
+ * - Field types (String, Int, Float, Boolean, ID, custom types)
+ * - Non-null (!) and list ([]) modifiers
+ * - Field relationships based on type references
+ * - Query, Mutation, and Subscription types
+ *
+ * GraphQL schemas have explicit type references,
+ * providing high-fidelity relationship detection.
+ */
+
+/**
+ * Parse GraphQL schema files into DemokitSchema.
+ */
+declare function parseGraphQL(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Supabase generated types parser.
+ * Parses Supabase database.types.ts files into DemokitSchema.
+ *
+ * Supports:
+ * - Database interface with Tables property
+ * - Tables.*.Row type for each table
+ * - Column types mapped from PostgreSQL types
+ * - Foreign key relationships from Insert/Update types
+ * - Views and Enums
+ *
+ * Supabase generates types from the database schema,
+ * providing accurate type information and relationships.
+ */
+
+/**
+ * Parse Supabase types files into DemokitSchema.
+ */
+declare function parseSupabase(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * tRPC router parser.
+ * Parses tRPC router definitions into DemokitSchema.
+ *
+ * Supports:
+ * - router() definitions with procedure chains
+ * - .input() and .output() Zod schemas
+ * - publicProcedure and protectedProcedure
+ * - Nested routers (appRouter structure)
+ *
+ * tRPC uses Zod for validation, so this parser extracts
+ * Zod schemas and delegates to the Zod parser for details.
+ */
+
+/**
+ * Parse tRPC router files into DemokitSchema.
+ */
+declare function parseTRPC(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Next.js parser.
+ * Parses Next.js API routes and Server Actions into DemokitSchema.
+ *
+ * Supports:
+ * - App Router: app/api/[...]/route.ts (GET, POST, PUT, PATCH, DELETE)
+ * - Pages Router: pages/api/[...].ts (handler function)
+ * - Server Actions: 'use server' directive
+ * - TypeScript types for request/response bodies
+ * - Zod validation schemas in API routes
+ *
+ * Extracts endpoint and schema information from Next.js conventions.
+ */
+
+/**
+ * Parse Next.js files into DemokitSchema.
+ */
+declare function parseNextJS(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Unified schema parser entry point.
+ *
+ * Provides a single `parseSchema()` function that can parse
+ * multiple schema formats and automatically detect the format.
+ *
+ * @example
+ * // Parse with auto-detection
+ * const result = await parseSchema(files)
+ *
+ * // Parse specific format
+ * const result = await parseSchema(files, { format: 'drizzle' })
+ *
+ * // Parse from strings
+ * const result = await parseSchemaFromStrings([
+ *   { path: 'schema.ts', content: 'export const users = pgTable(...)' }
+ * ])
+ */
+
+/**
+ * Parse schema files from a codebase.
+ *
+ * Supports TypeScript, Zod, Drizzle, and Prisma formats.
+ * Can auto-detect the format or use a specified format.
+ *
+ * @param files - Array of files with path and content
+ * @param options - Parsing options
+ * @returns Parsed schema with metadata
+ */
+declare function parseSchema(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+/**
+ * Parse multiple formats from a codebase and merge the results.
+ *
+ * This is useful when a codebase uses multiple schema sources
+ * (e.g., Drizzle for database + Zod for validation).
+ *
+ * @param files - Array of files with path and content
+ * @param options - Parsing options
+ * @returns Merged schema from all detected formats
+ */
+declare function parseSchemaMultiFormat(files: CodebaseFile[], options?: ParseSchemaOptions): ParseResult;
+
+/**
+ * Relationship detection for DemoKit schemas
+ *
+ * Detects relationships between models using:
+ * 1. Explicit $ref references in OpenAPI
+ * 2. Naming conventions (userId -> User.id)
+ * 3. x-demokit-relationship extension
+ */
+
+/**
+ * Check if a property looks like a foreign key based on naming conventions
+ */
+declare function detectRelationshipFromNaming(property: PropertyDef, availableModels: Set<string>): RelationshipTarget | null;
+/**
+ * Check if a property has an explicit x-demokit-relationship extension
+ */
+declare function detectRelationshipFromExtension(property: PropertyDef): RelationshipTarget | null;
+/**
+ * Check if a property is a $ref to another model
+ */
+declare function detectRelationshipFromRef(property: PropertyDef, availableModels: Set<string>): RelationshipTarget | null;
+/**
+ * Detect all relationships in a set of models
+ */
+declare function detectRelationships(models: Record<string, DataModel>): Relationship[];
+/**
+ * Find all relationships for a specific model
+ */
+declare function getRelationshipsForModel(modelName: string, relationships: Relationship[]): {
+    outgoing: Relationship[];
+    incoming: Relationship[];
+};
+/**
+ * Check if a model is referenced by other models
+ */
+declare function isModelReferenced(modelName: string, relationships: Relationship[]): boolean;
+/**
+ * Get the dependency order for models based on relationships
+ * Returns models in order such that dependencies come before dependents
+ */
+declare function getModelDependencyOrder(models: Record<string, DataModel>, relationships: Relationship[]): string[];
+
+/**
+ * Schema Merger.
+ * Merges multiple DemokitSchemas from different sources into a unified schema.
+ *
+ * Features:
+ * - Case-insensitive model name matching
+ * - Property merge with source tracking
+ * - Relationship priority (explicit > inferred)
+ * - Conflict detection and resolution
+ * - Endpoint merging from multiple sources
+ */
+
+/**
+ * Options for schema merging.
+ */
+interface MergeOptions {
+    /**
+     * How to resolve property conflicts when the same model appears in multiple sources.
+     * - 'prefer-explicit': Prefer properties from more explicit sources (e.g., Drizzle over TypeScript)
+     * - 'prefer-first': Keep the first value encountered
+     * - 'union': Combine all properties, with first taking precedence for conflicts
+     */
+    conflictResolution?: 'prefer-explicit' | 'prefer-first' | 'union';
+    /**
+     * Order of precedence for relationships.
+     * Earlier formats have higher priority.
+     * Default: ['drizzle', 'prisma', 'graphql', 'supabase', 'zod', 'trpc', 'typescript', 'nextjs']
+     */
+    relationshipPriority?: SchemaFormat[];
+    /**
+     * Whether to track the source of each field for debugging.
+     */
+    trackSources?: boolean;
+    /**
+     * Name for the merged schema.
+     */
+    name?: string;
+    /**
+     * Version for the merged schema.
+     */
+    version?: string;
+}
+/**
+ * A source schema with its format identifier.
+ */
+interface SchemaSource {
+    format: SchemaFormat;
+    schema: DemokitSchema;
+}
+/**
+ * Result of a merge operation.
+ */
+interface MergeResult {
+    /**
+     * The merged schema.
+     */
+    schema: DemokitSchema;
+    /**
+     * Conflicts detected during merge.
+     */
+    conflicts: MergeConflict[];
+    /**
+     * Source tracking for each model (if enabled).
+     */
+    sources?: ModelSourceMap;
+    /**
+     * Formats that were merged.
+     */
+    mergedFormats: SchemaFormat[];
+}
+/**
+ * Describes a merge conflict.
+ */
+interface MergeConflict {
+    type: 'model' | 'property' | 'relationship';
+    modelName: string;
+    propertyName?: string;
+    sources: SchemaFormat[];
+    resolution: 'kept-first' | 'merged' | 'overwritten';
+    details?: string;
+}
+/**
+ * Tracks which source provided each model/property.
+ */
+interface ModelSourceMap {
+    [modelName: string]: {
+        primarySource: SchemaFormat;
+        properties: {
+            [propertyName: string]: SchemaFormat;
+        };
+    };
+}
+/**
+ * Merge multiple schemas into a unified schema.
+ *
+ * @param sources - Array of schemas with their format identifiers
+ * @param options - Merge options
+ * @returns Merged schema with conflict information
+ */
+declare function mergeSchemas(sources: SchemaSource[], options?: MergeOptions): MergeResult;
+/**
+ * Compare two schemas and return the differences.
+ */
+declare function diffSchemas(base: DemokitSchema, updated: DemokitSchema): SchemaDiff;
+/**
+ * Schema diff result.
+ */
+interface SchemaDiff {
+    added: SchemaDiffItem[];
+    removed: SchemaDiffItem[];
+    modified: SchemaDiffItem[];
+}
+/**
+ * A single diff item.
+ */
+interface SchemaDiffItem {
+    type: 'model' | 'relationship' | 'endpoint';
+    name: string;
+    details: unknown;
+}
+/**
+ * Property diff.
+ */
+interface PropertyDiff {
+    name: string;
+    change: 'added' | 'removed' | 'modified';
+    oldValue?: PropertyDef;
+    newValue?: PropertyDef;
+}
+
+/**
+ * Error handling utilities for schema parsing.
+ *
+ * Provides custom error types and safe parsing utilities
+ * for graceful error recovery during schema parsing.
+ */
+
+/**
+ * Base error class for schema parsing errors.
+ */
+declare class SchemaParseError extends Error {
+    readonly code: string;
+    readonly filePath?: string | undefined;
+    readonly line?: number | undefined;
+    constructor(message: string, code: string, filePath?: string | undefined, line?: number | undefined);
+}
+/**
+ * Error thrown when a format cannot be detected.
+ */
+declare class FormatDetectionError extends SchemaParseError {
+    constructor(message: string, filePath?: string);
+}
+/**
+ * Error thrown when a file cannot be parsed.
+ */
+declare class FileParseError extends SchemaParseError {
+    constructor(message: string, filePath: string, line?: number);
+}
+/**
+ * Error thrown when schema validation fails.
+ */
+declare class SchemaValidationError extends SchemaParseError {
+    readonly validationErrors: string[];
+    constructor(message: string, validationErrors: string[]);
+}
+/**
+ * Error thrown when merging schemas fails.
+ */
+declare class SchemaMergeError extends SchemaParseError {
+    readonly modelName?: string | undefined;
+    constructor(message: string, modelName?: string | undefined);
+}
+/**
+ * Result of a safe operation that may fail.
+ */
+type SafeResult<T> = {
+    success: true;
+    value: T;
+    warnings: ParseWarning[];
+} | {
+    success: false;
+    error: Error;
+    warnings: ParseWarning[];
+};
+/**
+ * Safely execute a parsing function and capture errors as warnings.
+ *
+ * @param fn - The function to execute
+ * @param fallback - Fallback value if the function fails
+ * @param errorCode - Warning code to use if the function fails
+ * @returns Result with value or error
+ */
+declare function safeExecute<T>(fn: () => T, fallback: T, errorCode: string): {
+    value: T;
+    warning?: ParseWarning;
+};
+/**
+ * Safely parse content with error recovery.
+ * Returns partial results with warnings instead of failing completely.
+ *
+ * @param items - Array of items to process
+ * @param processor - Function to process each item
+ * @param errorCode - Warning code prefix for errors
+ * @returns Processed results and accumulated warnings
+ */
+declare function safeProcessMany<T, R>(items: T[], processor: (item: T) => R, errorCode: string): {
+    results: R[];
+    warnings: ParseWarning[];
+};
+/**
+ * Create a warning from an error.
+ */
+declare function errorToWarning(error: unknown, code: string, file?: string): ParseWarning;
+/**
+ * Aggregate multiple warnings into a summary warning.
+ */
+declare function aggregateWarnings(warnings: ParseWarning[], summaryCode: string, summaryPrefix: string): ParseWarning[];
+/**
+ * Check if an error is recoverable (should result in warning, not failure).
+ */
+declare function isRecoverableError(error: unknown): boolean;
+
+/**
+ * Types for @demokit-ai/codegen
+ *
+ * Includes validation types, generation options, and output formats.
+ */
+
+/**
+ * Result of validating demo data against a schema
+ */
+interface ValidationResult {
+    /** Whether all validations passed */
+    valid: boolean;
+    /** Critical errors that must be fixed */
+    errors: ValidationError[];
+    /** Non-critical issues that should be reviewed */
+    warnings: ValidationWarning[];
+    /** Summary statistics */
+    stats: ValidationStats;
+}
+/**
+ * A validation error - data that violates schema constraints
+ */
+interface ValidationError {
+    /** Type of validation failure */
+    type: ValidationErrorType;
+    /** Model where the error occurred */
+    model: string;
+    /** Field where the error occurred */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+    /** The invalid value (for debugging) */
+    value?: unknown;
+    /** Expected value or constraint */
+    expected?: string;
+    /** Record ID if applicable */
+    recordId?: string;
+}
+/**
+ * Types of validation errors
+ */
+type ValidationErrorType = 'missing_reference' | 'type_mismatch' | 'format_invalid' | 'constraint_violation' | 'required_missing' | 'enum_invalid' | 'timestamp_order' | 'array_empty' | 'duplicate_id';
+/**
+ * A validation warning - issues that may be intentional
+ */
+interface ValidationWarning {
+    /** Type of warning */
+    type: ValidationWarningType;
+    /** Model where the warning occurred */
+    model: string;
+    /** Field where the warning occurred */
+    field: string;
+    /** Human-readable warning message */
+    message: string;
+    /** The suspicious value */
+    value?: unknown;
+}
+/**
+ * Types of validation warnings
+ */
+type ValidationWarningType = 'orphaned_record' | 'suspicious_value' | 'missing_optional' | 'empty_string';
+/**
+ * Statistics about the validation run
+ */
+interface ValidationStats {
+    /** Total number of records validated */
+    totalRecords: number;
+    /** Records per model */
+    recordsByModel: Record<string, number>;
+    /** Number of relationships validated */
+    relationshipsChecked: number;
+    /** Number of type checks performed */
+    typeChecks: number;
+    /** Duration of validation in ms */
+    durationMs: number;
+}
+/**
+ * A validation rule that can be applied to data
+ */
+interface ValidationRule {
+    /** Unique identifier for this rule */
+    id: string;
+    /** Model this rule applies to */
+    model: string;
+    /** Field this rule applies to */
+    field: string;
+    /** Type of check to perform */
+    check: ValidationCheck;
+    /** Target field or value for comparison checks */
+    target?: string;
+    /** Whether this is a required field */
+    required?: boolean;
+    /** Custom error message */
+    message?: string;
+}
+/**
+ * Types of validation checks
+ */
+type ValidationCheck = 'isString' | 'isNumber' | 'isInteger' | 'isBoolean' | 'isArray' | 'isObject' | 'isNull' | 'isUUID' | 'isEmail' | 'isURL' | 'isISO8601' | 'isDate' | 'isDateTime' | 'minLength' | 'maxLength' | 'minimum' | 'maximum' | 'pattern' | 'existsIn' | 'isUnique' | 'equals' | 'beforeOrEqual' | 'afterOrEqual' | 'arrayNotEmpty' | 'arrayMinLength' | 'arrayMaxLength' | 'inEnum';
+/**
+ * Configuration for the rule generator
+ */
+interface RuleGeneratorConfig {
+    /** Whether to generate rules for optional fields */
+    includeOptional?: boolean;
+    /** Whether to generate relationship rules */
+    includeRelationships?: boolean;
+    /** Whether to generate format validation rules */
+    includeFormats?: boolean;
+    /** Custom rules to add */
+    customRules?: ValidationRule[];
+}
+/**
+ * Demo data for a single model
+ */
+type ModelData = Record<string, unknown>[];
+/**
+ * Complete demo data set
+ */
+type DemoData = Record<string, ModelData>;
+/**
+ * Options for the validator
+ */
+interface ValidatorOptions {
+    /** Schema to validate against */
+    schema: DemokitSchema;
+    /** Whether to collect warnings (slower) */
+    collectWarnings?: boolean;
+    /** Whether to stop on first error */
+    failFast?: boolean;
+    /** Maximum errors to collect before stopping */
+    maxErrors?: number;
+    /** Custom validation rules to add */
+    customRules?: ValidationRule[];
+}
+/**
+ * Level of data generation
+ */
+type GenerationLevel = 'schema-valid' | 'relationship-valid' | 'narrative-driven';
+/**
+ * Options for data generation
+ */
+interface GenerationOptions {
+    /** Level of generation */
+    level: GenerationLevel;
+    /** Number of records per model */
+    counts?: Record<string, number>;
+    /** Base timestamp for reproducible data */
+    baseTimestamp?: number;
+    /** Seed for random generation - different seed produces different data */
+    seed?: number;
+    /** Output format */
+    format?: 'typescript' | 'json';
+    /** Whether to include validation */
+    validate?: boolean;
+    /** Custom generation rules from project settings */
+    customRules?: GenerationRulesConfig;
+}
+/**
+ * Configuration for custom field generation rules
+ * Stored in projects.settings.generationRules
+ */
+interface GenerationRulesConfig {
+    /** Schema version for migration support */
+    version: 1;
+    /** Per-field rules, keyed by "ModelName.fieldName" */
+    fieldRules: Record<string, FieldRule>;
+    /** Uploaded datasets for correlated value generation, keyed by dataset ID */
+    datasets?: Record<string, Dataset>;
+}
+/**
+ * A rule for generating values for a specific field
+ */
+type FieldRule = StringFieldRule | NumberFieldRule | IntegerFieldRule | BooleanFieldRule | EnumFieldRule | DatasetFieldRule;
+/**
+ * Rule for generating string field values
+ */
+interface StringFieldRule {
+    type: 'string';
+    strategy: 'oneOf' | 'pattern';
+    /** For 'oneOf' strategy - pick randomly from this list */
+    values?: string[];
+    /** For 'pattern' strategy - template like "SKU-{0000}" where {0000} is replaced with zero-padded number */
+    pattern?: string;
+}
+/**
+ * Rule for generating number field values
+ */
+interface NumberFieldRule {
+    type: 'number';
+    strategy: 'range' | 'fixed';
+    /** For 'range' strategy */
+    min?: number;
+    max?: number;
+    /** Number of decimal places (default: 2) */
+    precision?: number;
+    /** For 'fixed' strategy - always use this value */
+    value?: number;
+}
+/**
+ * Rule for generating integer field values
+ */
+interface IntegerFieldRule {
+    type: 'integer';
+    strategy: 'range' | 'fixed';
+    min?: number;
+    max?: number;
+    value?: number;
+}
+/**
+ * Rule for generating boolean field values
+ */
+interface BooleanFieldRule {
+    type: 'boolean';
+    strategy: 'fixed' | 'weighted';
+    /** For 'fixed' strategy - always this value */
+    value?: boolean;
+    /** For 'weighted' strategy - probability of true (0-1) */
+    trueProbability?: number;
+}
+/**
+ * Rule for generating enum field values
+ */
+interface EnumFieldRule {
+    type: 'enum';
+    strategy: 'subset' | 'weighted';
+    /** For 'subset' strategy - only use these values */
+    allowedValues?: string[];
+    /** For 'weighted' strategy - value -> weight mapping */
+    weights?: Record<string, number>;
+}
+/**
+ * Rule for generating values from a linked dataset column
+ * Enables row-based correlation - multiple fields linked to the same dataset
+ * will use values from the same row within a record
+ */
+interface DatasetFieldRule {
+    type: 'fromDataset';
+    /** ID of the dataset to pull values from */
+    datasetId: string;
+    /** Column name to use for this field's values */
+    column: string;
+}
+/**
+ * A dataset containing rows of correlated values
+ * Limited to ~1000 rows for in-memory storage in project settings
+ */
+interface Dataset {
+    /** Unique identifier for the dataset */
+    id: string;
+    /** Human-readable name for display */
+    name: string;
+    /** Column headers from CSV */
+    columns: string[];
+    /** Row data - array of arrays matching column order */
+    rows: string[][];
+    /** When the dataset was created/uploaded */
+    createdAt: string;
+    /** Optional description of the dataset contents */
+    description?: string;
+}
+/**
+ * Result of parsing CSV content
+ */
+interface ParseCSVResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Column headers (if successful) */
+    columns?: string[];
+    /** Row data (if successful) */
+    rows?: string[][];
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether rows were truncated to meet limit */
+    truncated?: boolean;
+    /** Original row count before truncation */
+    originalRowCount?: number;
+}
+/**
+ * Result of data generation
+ */
+interface GenerationResult {
+    /** The generated data */
+    data: DemoData;
+    /** Generated fixture code (if format is typescript) */
+    fixtures?: string;
+    /** Validation results */
+    validation: ValidationResult;
+    /** Generation metadata */
+    metadata: GenerationMetadata;
+}
+/**
+ * Metadata about the generation process
+ */
+interface GenerationMetadata {
+    /** Generation level used */
+    level: GenerationLevel;
+    /** Timestamp when generated */
+    generatedAt: string;
+    /** Total records generated */
+    totalRecords: number;
+    /** Records per model */
+    recordsByModel: Record<string, number>;
+    /** IDs used in generation */
+    usedIds: Record<string, string[]>;
+    /** Duration of generation in ms */
+    durationMs: number;
+}
+/**
+ * Context about the application being demoed
+ */
+interface AppContext {
+    /** Application name */
+    name: string;
+    /** What the app does */
+    description: string;
+    /** Domain (e-commerce, b2b-saas, etc.) */
+    domain: string;
+    /** Key entities and their purposes */
+    keyEntities: EntityContext[];
+    /** Main features/capabilities */
+    features: string[];
+}
+/**
+ * Context about a specific entity
+ */
+interface EntityContext {
+    /** Entity/model name */
+    name: string;
+    /** What this entity represents */
+    purpose: string;
+    /** Key fields to focus on */
+    keyFields: string[];
+    /** Business rules that apply */
+    businessRules?: string[];
+}
+/**
+ * Narrative for generating story-driven data
+ */
+interface DemoNarrative {
+    /** Overall scenario */
+    scenario: string;
+    /** Key story points to hit */
+    keyPoints: string[];
+    /** Named characters/personas */
+    characters?: Character[];
+    /** Timeline of events */
+    timeline?: TimelineEvent[];
+    /** Metric targets */
+    metrics?: MetricTarget[];
+}
+/**
+ * A character/persona in the demo
+ */
+interface Character {
+    /** Character name */
+    name: string;
+    /** Role (customer, admin, etc.) */
+    role: string;
+    /** Character description */
+    description?: string;
+}
+/**
+ * A timeline event in the narrative
+ */
+interface TimelineEvent {
+    /** When this happens (relative or absolute) */
+    when: string;
+    /** What happens */
+    event: string;
+    /** Which characters are involved */
+    characters?: string[];
+}
+/**
+ * A metric target for the narrative
+ */
+interface MetricTarget {
+    /** Metric name */
+    name: string;
+    /** Target value or description */
+    value?: string;
+    /** Trend (increasing, declining, stable) */
+    trend?: 'increasing' | 'declining' | 'stable';
+    /** Percentage change */
+    amount?: string;
+}
+
+/**
+ * Main generator orchestrator for demo data generation
+ *
+ * Supports two levels:
+ * - Level 1 (schema-valid): Generate data that matches types
+ * - Level 2 (relationship-valid): Generate data with valid references
+ */
+
+/**
+ * Generate demo data from a schema
+ */
+declare function generateDemoData(schema: DemokitSchema, options?: GenerationOptions): GenerationResult;
+
+/**
+ * ID generation utilities for demo data
+ *
+ * Generates consistent, deterministic IDs for reproducible fixtures.
+ */
+/**
+ * Generate a UUID v4 (random)
+ * Uses a simple implementation for portability
+ */
+declare function generateUUID(): string;
+/**
+ * Generate a deterministic UUID from a seed
+ * Useful for reproducible fixtures
+ */
+declare function generateSeededUUID(seed: number): string;
+/**
+ * Generate a model-specific ID
+ * Format: {prefix}_{index} or UUID based on format hint
+ */
+declare function generateIdForModel(modelName: string, index: number, format?: string): string;
+/**
+ * Generate an ID based on a property definition
+ */
+declare function generateId(format?: string, index?: number): string;
+/**
+ * Generate a prefixed ID
+ * @example generatePrefixedId('user', 1) => 'user_001'
+ */
+declare function generatePrefixedId(prefix: string, index: number): string;
+/**
+ * Generate a CUID-like ID
+ * Format: c + timestamp + random
+ */
+declare function generateCuid(): string;
+/**
+ * Generate a ULID-like ID
+ * Format: timestamp (10 chars) + random (16 chars)
+ */
+declare function generateUlid(): string;
+
+interface GeneratedAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    stateFull: string;
+    country: string;
+    countryCode: string;
+    postalCode: string;
+    formatted: string;
+}
+
+/**
+ * Value generators for different property types
+ *
+ * Generates realistic demo data based on property type, format, and constraints.
+ */
+
+/**
+ * Context for generating correlated values within a single record.
+ * This allows related fields (like city, state, zip) to be consistent,
+ * and ensures fields linked to the same dataset use the same row.
+ */
+interface RecordContext {
+    /** Pre-generated correlated address for this record */
+    address?: GeneratedAddress;
+    /** Country code preference (US, CA, GB, AU, DE) */
+    countryCode?: string;
+    /**
+     * Pre-selected row indices for each dataset (Phase 2).
+     * Key is dataset ID, value is the row index to use.
+     * This ensures multiple fields linked to the same dataset use the same row.
+     */
+    datasetRowIndices?: Map<string, number>;
+}
+/**
+ * Generate a value for a property definition
+ *
+ * @param propDef - The property definition from the schema
+ * @param index - The record index (0-based)
+ * @param baseTimestamp - Optional base timestamp for date generation
+ * @param seed - Random seed for deterministic generation
+ * @param recordContext - Optional context for correlated field generation
+ * @param customRule - Optional custom generation rule for this field
+ * @param datasets - Optional datasets for fromDataset rules (Phase 2)
+ */
+declare function generateValue(propDef: PropertyDef, index: number, baseTimestamp?: number, seed?: number, recordContext?: RecordContext, customRule?: FieldRule, datasets?: Record<string, Dataset>): unknown;
+
+/**
+ * CSV Parser for Linked Datasets
+ *
+ * Parses CSV content into structured data for use in generation rules.
+ * Supports:
+ * - Quoted fields with commas and newlines
+ * - Header row detection
+ * - Row limit enforcement (1000 rows max)
+ * - Validation of consistent column counts
+ */
+
+/**
+ * Parse CSV content into columns and rows
+ *
+ * @param content - Raw CSV content as a string
+ * @returns ParseCSVResult with columns, rows, or error
+ */
+declare function parseCSV(content: string): ParseCSVResult;
+/**
+ * Generate a unique dataset ID
+ */
+declare function generateDatasetId(): string;
+/**
+ * Validate that a dataset name is valid
+ */
+declare function validateDatasetName(name: string): string | null;
+
+/**
+ * App Context Inference
+ *
+ * Analyzes a DemokitSchema to infer what the application does,
+ * its domain, key entities, and features. This provides context
+ * for narrative-driven data generation.
+ *
+ * The inference process works in several stages:
+ * 1. Domain detection - What type of application is this?
+ * 2. Entity analysis - What are the key data objects?
+ * 3. Feature inference - What can users do with the app?
+ * 4. Business rule extraction - What constraints apply?
+ *
+ * @example
+ * ```typescript
+ * const schema = await importFromOpenAPI('api.yaml')
+ * const context = inferAppContext(schema)
+ * // context.domain === 'e-commerce'
+ * // context.keyEntities includes Product, Order, Customer
+ * ```
+ */
+
+/**
+ * Infer application context from a schema.
+ *
+ * This is the main entry point for context inference. It analyzes the schema
+ * structure to understand what the application does and how its data relates.
+ *
+ * @param schema - The parsed DemokitSchema from an OpenAPI spec
+ * @returns AppContext with inferred domain, entities, and features
+ *
+ * @example
+ * ```typescript
+ * const context = inferAppContext(schema)
+ * console.log(context.domain) // 'e-commerce'
+ * console.log(context.keyEntities.length) // 5
+ * ```
+ */
+declare function inferAppContext(schema: DemokitSchema): AppContext;
+/**
+ * Create a custom app context with explicit values.
+ *
+ * Use this when the user wants to provide their own context rather than
+ * relying on inference. Useful for demos where the inferred context
+ * doesn't match the intended story.
+ *
+ * @param name - Application name
+ * @param description - What the app does
+ * @param domain - Application domain
+ * @param entities - Key entities with their purposes
+ * @param features - Main features/capabilities
+ * @returns Complete AppContext object
+ *
+ * @example
+ * ```typescript
+ * const context = createAppContext(
+ *   'ShopFlow',
+ *   'Enterprise e-commerce platform',
+ *   'e-commerce',
+ *   [{ name: 'Product', purpose: 'Items for sale', keyFields: ['id', 'price'] }],
+ *   ['Checkout', 'Inventory Management']
+ * )
+ * ```
+ */
+declare function createAppContext(name: string, description: string, domain: string, entities: EntityContext[], features: string[]): AppContext;
+/**
+ * Merge inferred context with user-provided overrides.
+ *
+ * Allows users to customize specific parts of the inferred context
+ * while keeping the rest. Useful for fine-tuning without starting
+ * from scratch.
+ *
+ * @param inferred - The automatically inferred context
+ * @param overrides - User-provided values to override
+ * @returns Merged context with overrides taking precedence
+ *
+ * @example
+ * ```typescript
+ * const inferred = inferAppContext(schema)
+ * const custom = mergeAppContext(inferred, {
+ *   name: 'My Custom App Name',
+ *   domain: 'b2b-saas', // Override the detected domain
+ * })
+ * ```
+ */
+declare function mergeAppContext(inferred: AppContext, overrides: Partial<AppContext>): AppContext;
+
+/**
+ * Output Formatters
+ *
+ * Convert generated demo data into various output formats for different use cases:
+ *
+ * - **TypeScript**: Type-safe fixture files with const assertions
+ * - **JSON**: Standard data interchange format with optional metadata
+ * - **SQL**: INSERT statements for database seeding
+ * - **CSV**: Spreadsheet-compatible format for individual models
+ *
+ * Each formatter handles:
+ * - Proper escaping for the target format
+ * - Optional headers/metadata
+ * - Null and special value handling
+ * - Nested objects and arrays
+ *
+ * @example
+ * ```typescript
+ * // Generate TypeScript fixtures
+ * const tsCode = formatAsTypeScript(data, { asConst: true })
+ *
+ * // Generate JSON with metadata
+ * const json = formatAsJSON(data, { includeMetadata: true })
+ *
+ * // Generate SQL INSERT statements
+ * const sql = formatAsSQL(data, { tableName: name => `tbl_${name}` })
+ *
+ * // Generate CSV for a specific model
+ * const csv = formatAsCSV(data, 'Customer')
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Output format options for TypeScript generation
+ *
+ * Controls the generated TypeScript code structure and styling.
+ *
+ * @example
+ * ```typescript
+ * const options: OutputOptions = {
+ *   asConst: true,           // Add 'as const' for type safety
+ *   indent: 2,               // 2-space indentation
+ *   includeHeader: true,     // Add generation comment
+ *   narrative: myNarrative,  // Include narrative in header
+ * }
+ * ```
+ */
+interface OutputOptions {
+    /** Whether to include TypeScript 'as const' assertions. Defaults to true. */
+    asConst?: boolean;
+    /** Whether to include type annotations (future use). */
+    includeTypes?: boolean;
+    /** Indentation in spaces. Defaults to 2. */
+    indent?: number;
+    /** Whether to add a comment header with generation info. Defaults to true. */
+    includeHeader?: boolean;
+    /** Narrative for header comments (scenario, key points). */
+    narrative?: DemoNarrative;
+}
+/**
+ * Format demo data as TypeScript code
+ *
+ * Generates a TypeScript module with:
+ * - Header comment with generation timestamp
+ * - Optional narrative info (scenario, key points)
+ * - Individual exports per model (DEMO_USER, DEMO_ORDER, etc.)
+ * - Combined DEMO_DATA export with all models
+ * - 'as const' assertions for full type inference
+ *
+ * Model names are converted to CONSTANT_CASE for variable names.
+ *
+ * @param data - Demo data object (model names → record arrays)
+ * @param options - Formatting options (asConst, indent, header, narrative)
+ * @returns TypeScript source code as string
+ *
+ * @example
+ * ```typescript
+ * const data = {
+ *   User: [{ id: '1', name: 'Alice' }],
+ *   Order: [{ id: '1', userId: '1', total: 100 }],
+ * }
+ *
+ * const code = formatAsTypeScript(data, {
+ *   asConst: true,
+ *   narrative: { scenario: 'Demo', keyPoints: ['Show users'] },
+ * })
+ *
+ * // Output:
+ * // /**
+ * //  * Auto-generated demo fixtures
+ * //  * Scenario: Demo
+ * //  * Key points:
+ * //  * - Show users
+ * //  *‍/
+ * // export const DEMO_USER = [...] as const
+ * // export const DEMO_ORDER = [...] as const
+ * // export const DEMO_DATA = { User: DEMO_USER, Order: DEMO_ORDER } as const
+ * ```
+ */
+declare function formatAsTypeScript(data: DemoData, options?: OutputOptions): string;
+/**
+ * Format demo data as JSON
+ *
+ * Generates standard JSON output with optional metadata wrapper.
+ *
+ * Without metadata:
+ * ```json
+ * { "User": [...], "Order": [...] }
+ * ```
+ *
+ * With metadata:
+ * ```json
+ * {
+ *   "_metadata": { "generatedAt": "...", "modelCount": 2, "recordCount": 10 },
+ *   "data": { "User": [...], "Order": [...] }
+ * }
+ * ```
+ *
+ * @param data - Demo data object (model names → record arrays)
+ * @param options - Formatting options (indent, includeMetadata)
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * // Simple JSON output
+ * const json = formatAsJSON(data)
+ *
+ * // JSON with metadata
+ * const jsonWithMeta = formatAsJSON(data, { includeMetadata: true })
+ * ```
+ */
+declare function formatAsJSON(data: DemoData, options?: {
+    indent?: number;
+    includeMetadata?: boolean;
+}): string;
+/**
+ * Format demo data as SQL INSERT statements
+ *
+ * Generates INSERT statements for database seeding. Handles:
+ * - Automatic table name conversion (snake_case by default)
+ * - Proper value escaping (strings, nulls, numbers, booleans)
+ * - JSON serialization for arrays and objects
+ * - Comment headers with record counts
+ *
+ * @param data - Demo data object (model names → record arrays)
+ * @param options - Formatting options (tableName function)
+ * @returns SQL INSERT statements as string
+ *
+ * @example
+ * ```typescript
+ * const sql = formatAsSQL(data)
+ * // Output:
+ * // -- Auto-generated demo data
+ * // -- User (5 records)
+ * // INSERT INTO user (id, name, email) VALUES ('1', 'Alice', 'alice@example.com');
+ *
+ * // Custom table names
+ * const sql = formatAsSQL(data, {
+ *   tableName: name => `demo_${name.toLowerCase()}`
+ * })
+ * ```
+ */
+declare function formatAsSQL(data: DemoData, options?: {
+    tableName?: (modelName: string) => string;
+}): string;
+/**
+ * Format demo data as CSV (one model at a time)
+ *
+ * Generates RFC 4180-compliant CSV with:
+ * - Header row with all column names
+ * - Proper escaping (commas, quotes, newlines)
+ * - Unified columns from all records (handles sparse data)
+ * - JSON serialization for complex values
+ *
+ * Note: CSV format only supports a single model at a time.
+ * For multiple models, call this function once per model.
+ *
+ * @param data - Demo data object (model names → record arrays)
+ * @param modelName - Name of the model to export
+ * @returns CSV string (empty string if model not found or empty)
+ *
+ * @example
+ * ```typescript
+ * const userCsv = formatAsCSV(data, 'User')
+ * // Output:
+ * // id,name,email
+ * // 1,Alice,alice@example.com
+ * // 2,Bob,bob@example.com
+ *
+ * // Export each model to separate files
+ * for (const model of Object.keys(data)) {
+ *   const csv = formatAsCSV(data, model)
+ *   writeFileSync(`${model}.csv`, csv)
+ * }
+ * ```
+ */
+declare function formatAsCSV(data: DemoData, modelName: string): string;
+
+/**
+ * Main validator for demo data
+ *
+ * Validates data against a DemokitSchema, checking:
+ * - Type correctness
+ * - Format validity
+ * - Referential integrity
+ * - Custom constraints
+ */
+
+/**
+ * Validate demo data against a schema
+ */
+declare function validateData(data: DemoData, options: ValidatorOptions): ValidationResult;
+/**
+ * Validate timestamp ordering (e.g., createdAt <= updatedAt)
+ */
+declare function validateTimestampOrder(data: DemoData, rules: Array<{
+    model: string;
+    before: string;
+    after: string;
+}>): ValidationError[];
+
+/**
+ * Validation rule generation from DemokitSchema
+ *
+ * Automatically generates validation rules based on:
+ * - Property types and formats
+ * - Required fields
+ * - Constraints (min/max, patterns)
+ * - Relationships
+ */
+
+/**
+ * Generate all validation rules from a schema
+ */
+declare function generateRulesFromSchema(schema: DemokitSchema, config?: RuleGeneratorConfig): ValidationRule[];
+/**
+ * Get a human-readable description of a rule
+ */
+declare function describeRule(rule: ValidationRule): string;
+/**
+ * Group rules by model for easier inspection
+ */
+declare function groupRulesByModel(rules: ValidationRule[]): Record<string, ValidationRule[]>;
+/**
+ * Filter rules to get only relationship rules
+ */
+declare function getRelationshipRules(rules: ValidationRule[]): ValidationRule[];
+/**
+ * Filter rules to get only required field rules
+ */
+declare function getRequiredFieldRules(rules: ValidationRule[]): ValidationRule[];
+
+/**
+ * Individual validation check functions
+ *
+ * Each function returns true if the value passes the check.
+ */
+/**
+ * Check if value is a string
+ */
+declare function isString(value: unknown): boolean;
+/**
+ * Check if value is a number (not NaN)
+ */
+declare function isNumber(value: unknown): boolean;
+/**
+ * Check if value is an integer
+ */
+declare function isInteger(value: unknown): boolean;
+/**
+ * Check if value is a boolean
+ */
+declare function isBoolean(value: unknown): boolean;
+/**
+ * Check if value is an array
+ */
+declare function isArray(value: unknown): boolean;
+/**
+ * Check if value is a plain object
+ */
+declare function isObject(value: unknown): boolean;
+/**
+ * Check if value is null
+ */
+declare function isNull(value: unknown): boolean;
+/**
+ * Check if value is undefined
+ */
+declare function isUndefined(value: unknown): boolean;
+/**
+ * Check if value is null or undefined
+ */
+declare function isNullish(value: unknown): boolean;
+/**
+ * Check if value is a valid UUID
+ */
+declare function isUUID(value: unknown, strict?: boolean): boolean;
+/**
+ * Check if value is a valid email format
+ */
+declare function isEmail(value: unknown): boolean;
+/**
+ * Check if value is a valid URL
+ */
+declare function isURL(value: unknown): boolean;
+/**
+ * Check if value is a valid ISO 8601 date (YYYY-MM-DD)
+ */
+declare function isDate(value: unknown): boolean;
+/**
+ * Check if value is a valid ISO 8601 datetime
+ */
+declare function isDateTime(value: unknown): boolean;
+/**
+ * Alias for isDateTime - checks ISO 8601 format
+ */
+declare function isISO8601(value: unknown): boolean;
+/**
+ * Check if string length is at least minLength
+ */
+declare function hasMinLength(value: unknown, minLength: number): boolean;
+/**
+ * Check if string length is at most maxLength
+ */
+declare function hasMaxLength(value: unknown, maxLength: number): boolean;
+/**
+ * Check if number is at least minimum
+ */
+declare function hasMinimum(value: unknown, minimum: number): boolean;
+/**
+ * Check if number is at most maximum
+ */
+declare function hasMaximum(value: unknown, maximum: number): boolean;
+/**
+ * Check if string matches a regex pattern
+ */
+declare function matchesPattern(value: unknown, pattern: string | RegExp): boolean;
+/**
+ * Check if value is in an enum array
+ */
+declare function isInEnum(value: unknown, enumValues: unknown[]): boolean;
+/**
+ * Check if two values are equal
+ */
+declare function equals(value: unknown, expected: unknown): boolean;
+/**
+ * Check if a date/datetime is before or equal to another
+ */
+declare function isBeforeOrEqual(value: unknown, other: unknown): boolean;
+/**
+ * Check if a date/datetime is after or equal to another
+ */
+declare function isAfterOrEqual(value: unknown, other: unknown): boolean;
+/**
+ * Check if array is not empty
+ */
+declare function isArrayNotEmpty(value: unknown): boolean;
+/**
+ * Check if array has at least minLength items
+ */
+declare function hasArrayMinLength(value: unknown, minLength: number): boolean;
+/**
+ * Check if array has at most maxLength items
+ */
+declare function hasArrayMaxLength(value: unknown, maxLength: number): boolean;
+/**
+ * Check if a string is empty or only whitespace
+ */
+declare function isEmptyString(value: unknown): boolean;
+/**
+ * Get the type name of a value (for error messages)
+ */
+declare function getTypeName(value: unknown): string;
+
+declare const checks_equals: typeof equals;
+declare const checks_getTypeName: typeof getTypeName;
+declare const checks_hasArrayMaxLength: typeof hasArrayMaxLength;
+declare const checks_hasArrayMinLength: typeof hasArrayMinLength;
+declare const checks_hasMaxLength: typeof hasMaxLength;
+declare const checks_hasMaximum: typeof hasMaximum;
+declare const checks_hasMinLength: typeof hasMinLength;
+declare const checks_hasMinimum: typeof hasMinimum;
+declare const checks_isAfterOrEqual: typeof isAfterOrEqual;
+declare const checks_isArray: typeof isArray;
+declare const checks_isArrayNotEmpty: typeof isArrayNotEmpty;
+declare const checks_isBeforeOrEqual: typeof isBeforeOrEqual;
+declare const checks_isBoolean: typeof isBoolean;
+declare const checks_isDate: typeof isDate;
+declare const checks_isDateTime: typeof isDateTime;
+declare const checks_isEmail: typeof isEmail;
+declare const checks_isEmptyString: typeof isEmptyString;
+declare const checks_isISO8601: typeof isISO8601;
+declare const checks_isInEnum: typeof isInEnum;
+declare const checks_isInteger: typeof isInteger;
+declare const checks_isNull: typeof isNull;
+declare const checks_isNullish: typeof isNullish;
+declare const checks_isNumber: typeof isNumber;
+declare const checks_isObject: typeof isObject;
+declare const checks_isString: typeof isString;
+declare const checks_isURL: typeof isURL;
+declare const checks_isUUID: typeof isUUID;
+declare const checks_isUndefined: typeof isUndefined;
+declare const checks_matchesPattern: typeof matchesPattern;
+declare namespace checks {
+  export { checks_equals as equals, checks_getTypeName as getTypeName, checks_hasArrayMaxLength as hasArrayMaxLength, checks_hasArrayMinLength as hasArrayMinLength, checks_hasMaxLength as hasMaxLength, checks_hasMaximum as hasMaximum, checks_hasMinLength as hasMinLength, checks_hasMinimum as hasMinimum, checks_isAfterOrEqual as isAfterOrEqual, checks_isArray as isArray, checks_isArrayNotEmpty as isArrayNotEmpty, checks_isBeforeOrEqual as isBeforeOrEqual, checks_isBoolean as isBoolean, checks_isDate as isDate, checks_isDateTime as isDateTime, checks_isEmail as isEmail, checks_isEmptyString as isEmptyString, checks_isISO8601 as isISO8601, checks_isInEnum as isInEnum, checks_isInteger as isInteger, checks_isNull as isNull, checks_isNullish as isNullish, checks_isNumber as isNumber, checks_isObject as isObject, checks_isString as isString, checks_isURL as isURL, checks_isUUID as isUUID, checks_isUndefined as isUndefined, checks_matchesPattern as matchesPattern };
+}
+
+export { type AppContext, type BooleanFieldRule, type Character, type CloudFixtureResponse, type CodebaseFile, DEFAULT_CLOUD_URL, DEFAULT_MAX_RETRIES, DEFAULT_STORAGE_KEY, DEFAULT_TIMEOUT, type DataModel, type Dataset, type DatasetFieldRule, type DemoData, type DemoInterceptor, type DemoKitConfig, type DemoKitRemoteConfig, type DemoNarrative, type DemoState, type DemoStateStore, type DemoStateStoreOptions, type DemokitSchema, type Endpoint, type EndpointMapping, type EntityContext, type EnumFieldRule, FORMAT_PATTERNS, FORMAT_PRIORITY, type FieldRule, FileParseError, type FixtureHandler, type FixtureMap, FormatDetectionError, type FormatDetectionPatterns, type FormatDetectionResult, type GenerationLevel, type GenerationMetadata, type GenerationOptions, type GenerationResult, type GenerationRulesConfig, type HttpMethod, type IntegerFieldRule, type MatchResult, type MergeConflict, type MergeOptions, type MergeResult, type MetricTarget, type ModelData, type ModelSourceMap, type ModelType, type NumberFieldRule, type OutputOptions, type ParameterDef, type ParseCSVResult, type ParseOptions, type ParseResult, type ParseSchemaOptions, type ParseWarning, type ParsedPattern, type PropertyDef, type PropertyDiff, type PropertyType, type QueryKey, type QueryKeyElement, type QueryKeyMatchResult, type Relationship, type RelationshipDetectionMethod, type RelationshipSide, type RelationshipTarget, type RelationshipType, type RemoteConfig, RemoteFetchError, type RemoteLoadingState, type RequestBody, type RequestContext, type ResponseDef, type RuleGeneratorConfig, type SafeResult, type SchemaDiff, type SchemaDiffItem, type SchemaFormat, type SchemaInfo, SchemaMergeError, SchemaParseError, type SchemaRef, type SchemaSource, SchemaValidationError, type SessionState, type StringFieldRule, type TimelineEvent, type ValidationCheck, type ValidationError, type ValidationErrorType, type ValidationResult, type ValidationRule, type ValidationStats, type ValidationWarning, type ValidationWarningType, type ValidatorOptions, aggregateWarnings, buildFixtureMap, checks, clearDemoState, clearPatternCache, createAppContext, createDemoInterceptor, createDemoState, createDemoStateStore, createHandlerForMapping, createRemoteFixtures, createSessionState, describeRule, detectFormat, detectFormatFromFiles, detectRelationshipFromExtension, detectRelationshipFromNaming, detectRelationshipFromRef, detectRelationships, diffSchemas, errorToWarning, extractRefName, fetchCloudFixtures, findMatchingPattern, findMatchingQueryKeyPattern, formatAsCSV, formatAsJSON, formatAsSQL, formatAsTypeScript, generateCuid, generateDatasetId, generateDemoData, generateId, generateIdForModel, generatePrefixedId, generateRulesFromSchema, generateSeededUUID, generateUUID, generateUlid, generateValue, getModelDependencyOrder, getRelationshipRules, getRelationshipsForModel, getRequiredFieldRules, groupFilesByFormat, groupRulesByModel, inferAppContext, isModelReferenced, isRecoverableError, isSchemaRef, isValidApiKey, loadDemoState, matchQueryKey, matchUrl, mergeAppContext, mergeFixtures, mergeSchemas, parseCSV, parseDrizzle, parseGraphQL, parseNextJS, parseOpenAPIFromObject, parseOpenAPIFromPath, parseOpenAPIFromString, parsePrisma, parseSchema, parseSchemaMultiFormat, parseSupabase, parseTRPC, parseTypeScript, parseUrlPattern, parseZod, safeExecute, safeProcessMany, saveDemoState, validateData, validateDatasetName, validateTimestampOrder };