@famgia/omnify-atlas 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,585 @@
+import { SchemaCollection, DatabaseDriver, PropertyDefinition, LoadedSchema } from '@famgia/omnify-types';
+
+/**
+ * @famgia/omnify-atlas - Lock File Types
+ *
+ * Types for the .omnify.lock file that tracks schema state.
+ */
+/**
+ * Hash of a schema for change detection.
+ */
+interface SchemaHash {
+    /** Schema name */
+    readonly name: string;
+    /** Content hash (SHA-256) */
+    readonly hash: string;
+    /** File path relative to schemas directory */
+    readonly relativePath: string;
+    /** Last modified timestamp (ISO 8601) */
+    readonly modifiedAt: string;
+}
+/**
+ * Generated migration record.
+ */
+interface GeneratedMigration {
+    /** Migration file name */
+    readonly fileName: string;
+    /** Timestamp when generated */
+    readonly generatedAt: string;
+    /** Schemas involved in this migration */
+    readonly schemas: readonly string[];
+    /** Migration checksum for integrity */
+    readonly checksum: string;
+}
+/**
+ * Lock file structure for tracking schema state.
+ */
+interface LockFile {
+    /** Lock file format version */
+    readonly version: 1;
+    /** When the lock file was last updated */
+    readonly updatedAt: string;
+    /** Database driver used */
+    readonly driver: string;
+    /** Hash of each schema */
+    readonly schemas: Record<string, SchemaHash>;
+    /** Record of generated migrations */
+    readonly migrations: readonly GeneratedMigration[];
+    /** HCL checksum for Atlas comparison */
+    readonly hclChecksum?: string | undefined;
+}
+/**
+ * Schema change type.
+ */
+type ChangeType = 'added' | 'modified' | 'removed';
+/**
+ * Detected schema change.
+ */
+interface SchemaChange {
+    /** Schema name */
+    readonly schemaName: string;
+    /** Type of change */
+    readonly changeType: ChangeType;
+    /** Previous hash (for modified/removed) */
+    readonly previousHash?: string;
+    /** Current hash (for added/modified) */
+    readonly currentHash?: string;
+}
+/**
+ * Result of comparing current schemas to lock file.
+ */
+interface LockFileComparison {
+    /** Whether any changes were detected */
+    readonly hasChanges: boolean;
+    /** List of detected changes */
+    readonly changes: readonly SchemaChange[];
+    /** Schemas that are unchanged */
+    readonly unchanged: readonly string[];
+}
+
+/**
+ * @famgia/omnify-atlas - Lock File Management
+ *
+ * Manages the .omnify.lock file for tracking schema state.
+ */
+
+/**
+ * Default lock file name.
+ */
+declare const LOCK_FILE_NAME = ".omnify.lock";
+/**
+ * Current lock file format version.
+ */
+declare const LOCK_FILE_VERSION: 1;
+/**
+ * Computes SHA-256 hash of content.
+ */
+declare function computeHash(content: string): string;
+/**
+ * Computes hash for a schema.
+ */
+declare function computeSchemaHash(schema: {
+    name: string;
+    relativePath: string;
+    properties?: unknown;
+    options?: unknown;
+    values?: readonly string[];
+    kind?: string;
+}): string;
+/**
+ * Creates a new empty lock file.
+ */
+declare function createEmptyLockFile(driver: string): LockFile;
+/**
+ * Reads lock file from disk.
+ * Returns null if file doesn't exist.
+ */
+declare function readLockFile(lockFilePath: string): Promise<LockFile | null>;
+/**
+ * Writes lock file to disk.
+ */
+declare function writeLockFile(lockFilePath: string, lockFile: LockFile): Promise<void>;
+/**
+ * Builds schema hashes from a schema collection.
+ */
+declare function buildSchemaHashes(schemas: SchemaCollection): Promise<Record<string, SchemaHash>>;
+/**
+ * Compares current schemas to lock file and detects changes.
+ */
+declare function compareSchemas(currentHashes: Record<string, SchemaHash>, lockFile: LockFile | null): LockFileComparison;
+/**
+ * Updates lock file with current schema state.
+ */
+declare function updateLockFile(existingLockFile: LockFile | null, currentHashes: Record<string, SchemaHash>, driver: string): LockFile;
+/**
+ * Adds a migration record to the lock file.
+ */
+declare function addMigrationRecord(lockFile: LockFile, fileName: string, schemas: readonly string[], migrationContent: string): LockFile;
+
+/**
+ * @famgia/omnify-atlas - HCL Types
+ *
+ * Types for Atlas HCL schema generation.
+ */
+
+/**
+ * SQL column type for a specific database driver.
+ */
+interface SqlColumnType {
+    /** The SQL type (e.g., 'varchar(255)', 'int', 'text') */
+    readonly type: string;
+    /** Whether the column is nullable */
+    readonly nullable: boolean;
+    /** Default value (if any) */
+    readonly default?: string | undefined;
+    /** Whether this is an auto-increment column */
+    readonly autoIncrement?: boolean | undefined;
+    /** Whether this column is unsigned (for numeric types) */
+    readonly unsigned?: boolean | undefined;
+}
+/**
+ * HCL column definition.
+ */
+interface HclColumn {
+    /** Column name */
+    readonly name: string;
+    /** SQL type info */
+    readonly type: SqlColumnType;
+    /** Whether this is a primary key */
+    readonly primaryKey?: boolean;
+    /** Whether this column has a unique constraint */
+    readonly unique?: boolean;
+}
+/**
+ * HCL index definition.
+ */
+interface HclIndex {
+    /** Index name */
+    readonly name: string;
+    /** Columns in the index */
+    readonly columns: readonly string[];
+    /** Whether this is a unique index */
+    readonly unique?: boolean;
+}
+/**
+ * HCL foreign key definition.
+ */
+interface HclForeignKey {
+    /** Foreign key constraint name */
+    readonly name: string;
+    /** Local column(s) */
+    readonly columns: readonly string[];
+    /** Referenced table */
+    readonly refTable: string;
+    /** Referenced column(s) */
+    readonly refColumns: readonly string[];
+    /** ON DELETE action */
+    readonly onDelete?: string;
+    /** ON UPDATE action */
+    readonly onUpdate?: string;
+}
+/**
+ * HCL table definition.
+ */
+interface HclTable {
+    /** Table name */
+    readonly name: string;
+    /** Table columns */
+    readonly columns: readonly HclColumn[];
+    /** Table indexes */
+    readonly indexes: readonly HclIndex[];
+    /** Foreign key constraints */
+    readonly foreignKeys: readonly HclForeignKey[];
+    /** Primary key columns (if composite) */
+    readonly primaryKey?: readonly string[];
+}
+/**
+ * HCL enum definition.
+ */
+interface HclEnum {
+    /** Enum name */
+    readonly name: string;
+    /** Enum values */
+    readonly values: readonly string[];
+}
+/**
+ * Complete HCL schema.
+ */
+interface HclSchema {
+    /** Database driver */
+    readonly driver: DatabaseDriver;
+    /** Schema/database name */
+    readonly schemaName?: string | undefined;
+    /** Tables in the schema */
+    readonly tables: readonly HclTable[];
+    /** Enums in the schema (PostgreSQL) */
+    readonly enums: readonly HclEnum[];
+}
+/**
+ * Options for HCL generation.
+ */
+interface HclGenerationOptions {
+    /** Database driver */
+    readonly driver: DatabaseDriver;
+    /** Schema/database name */
+    readonly schemaName?: string;
+    /** Whether to include soft delete column */
+    readonly includeSoftDelete?: boolean;
+    /** Whether to include timestamps */
+    readonly includeTimestamps?: boolean;
+}
+
+/**
+ * @famgia/omnify-atlas - Type Mapper
+ *
+ * Maps Omnify property types to SQL types for different database drivers.
+ */
+
+/**
+ * Maps a property type to SQL column type.
+ */
+declare function mapPropertyToSql(property: PropertyDefinition, driver: DatabaseDriver): SqlColumnType;
+/**
+ * Gets the SQL type for a primary key.
+ */
+declare function getPrimaryKeyType(pkType: 'Int' | 'BigInt' | 'Uuid' | 'String', driver: DatabaseDriver): SqlColumnType;
+/**
+ * Gets the SQL type for timestamp columns.
+ */
+declare function getTimestampType(driver: DatabaseDriver): SqlColumnType;
+/**
+ * Converts table name from PascalCase schema name.
+ */
+declare function schemaNameToTableName(schemaName: string): string;
+/**
+ * Converts property name to column name.
+ */
+declare function propertyNameToColumnName(propertyName: string): string;
+
+/**
+ * @famgia/omnify-atlas - HCL Generator
+ *
+ * Generates Atlas HCL schema from Omnify schemas.
+ */
+
+/**
+ * Generates HCL table from a schema.
+ */
+declare function generateHclTable(schema: LoadedSchema, allSchemas: SchemaCollection, driver: DatabaseDriver): HclTable;
+/**
+ * Generates complete HCL schema from schema collection.
+ */
+declare function generateHclSchema(schemas: SchemaCollection, options: HclGenerationOptions): HclSchema;
+/**
+ * Renders HCL schema to string.
+ */
+declare function renderHcl(schema: HclSchema): string;
+
+/**
+ * @famgia/omnify-atlas - Atlas Types
+ *
+ * Types for Atlas CLI integration.
+ */
+
+/**
+ * Atlas CLI configuration.
+ */
+interface AtlasConfig {
+    /** Path to Atlas CLI binary (default: 'atlas') */
+    readonly binaryPath?: string;
+    /** Database driver */
+    readonly driver: DatabaseDriver;
+    /** Development database URL for diff operations */
+    readonly devUrl: string;
+    /** Working directory for Atlas operations */
+    readonly workDir?: string;
+    /** Timeout for Atlas commands in milliseconds */
+    readonly timeout?: number;
+}
+/**
+ * Atlas diff operation options.
+ */
+interface AtlasDiffOptions {
+    /** Path to the "from" schema (previous state) */
+    readonly fromPath?: string | undefined;
+    /** Path to the "to" schema (current state) */
+    readonly toPath: string;
+    /** Output format */
+    readonly format?: 'sql' | 'hcl' | undefined;
+    /** Whether to include drop statements */
+    readonly allowDestructive?: boolean | undefined;
+}
+/**
+ * Atlas command result.
+ */
+interface AtlasResult {
+    /** Whether the command succeeded */
+    readonly success: boolean;
+    /** Standard output */
+    readonly stdout: string;
+    /** Standard error */
+    readonly stderr: string;
+    /** Exit code */
+    readonly exitCode: number;
+    /** Execution time in milliseconds */
+    readonly duration: number;
+}
+/**
+ * Atlas diff result.
+ */
+interface AtlasDiffResult extends AtlasResult {
+    /** Whether there are schema changes */
+    readonly hasChanges: boolean;
+    /** SQL statements for changes */
+    readonly sql: string;
+}
+/**
+ * Atlas schema inspect result.
+ */
+interface AtlasInspectResult extends AtlasResult {
+    /** HCL schema content */
+    readonly hcl: string;
+}
+/**
+ * Atlas version info.
+ */
+interface AtlasVersion {
+    /** Atlas version string */
+    readonly version: string;
+    /** Whether Atlas is available */
+    readonly available: boolean;
+}
+
+/**
+ * @famgia/omnify-atlas - Atlas Runner
+ *
+ * Executes Atlas CLI commands via subprocess.
+ */
+
+/**
+ * Checks Atlas version and availability.
+ */
+declare function checkAtlasVersion(config?: Partial<AtlasConfig>): Promise<AtlasVersion>;
+/**
+ * Runs Atlas schema diff.
+ */
+declare function runAtlasDiff(config: AtlasConfig, options: AtlasDiffOptions): Promise<AtlasDiffResult>;
+/**
+ * Runs Atlas schema diff comparing two HCL strings.
+ */
+declare function diffHclSchemas(config: AtlasConfig, fromHcl: string | null, toHcl: string): Promise<AtlasDiffResult>;
+/**
+ * Validates Atlas HCL schema.
+ */
+declare function validateHcl(config: AtlasConfig, hclPath: string): Promise<AtlasResult>;
+/**
+ * Applies schema changes to the dev database (for testing).
+ */
+declare function applySchema(config: AtlasConfig, hclPath: string): Promise<AtlasResult>;
+
+/**
+ * @famgia/omnify-atlas - Diff Types
+ *
+ * Types for parsed schema diff results.
+ */
+/**
+ * Type of SQL operation.
+ */
+type SqlOperationType = 'CREATE_TABLE' | 'DROP_TABLE' | 'ALTER_TABLE' | 'CREATE_INDEX' | 'DROP_INDEX' | 'ADD_COLUMN' | 'DROP_COLUMN' | 'MODIFY_COLUMN' | 'ADD_FOREIGN_KEY' | 'DROP_FOREIGN_KEY' | 'ADD_CONSTRAINT' | 'DROP_CONSTRAINT' | 'UNKNOWN';
+/**
+ * Severity of a change.
+ */
+type ChangeSeverity = 'safe' | 'warning' | 'destructive';
+/**
+ * A single parsed SQL statement.
+ */
+interface ParsedStatement {
+    /** Original SQL statement */
+    readonly sql: string;
+    /** Type of operation */
+    readonly type: SqlOperationType;
+    /** Table name affected */
+    readonly tableName: string;
+    /** Column name (if applicable) */
+    readonly columnName?: string;
+    /** Index name (if applicable) */
+    readonly indexName?: string;
+    /** Constraint name (if applicable) */
+    readonly constraintName?: string;
+    /** Severity of the change */
+    readonly severity: ChangeSeverity;
+}
+/**
+ * Table change summary.
+ */
+interface TableChange {
+    /** Table name */
+    readonly tableName: string;
+    /** Whether the table is new */
+    readonly isNew: boolean;
+    /** Whether the table is being dropped */
+    readonly isDropped: boolean;
+    /** Columns being added */
+    readonly addedColumns: readonly string[];
+    /** Columns being dropped */
+    readonly droppedColumns: readonly string[];
+    /** Columns being modified */
+    readonly modifiedColumns: readonly string[];
+    /** Indexes being added */
+    readonly addedIndexes: readonly string[];
+    /** Indexes being dropped */
+    readonly droppedIndexes: readonly string[];
+    /** Foreign keys being added */
+    readonly addedForeignKeys: readonly string[];
+    /** Foreign keys being dropped */
+    readonly droppedForeignKeys: readonly string[];
+}
+/**
+ * Complete diff result.
+ */
+interface DiffResult {
+    /** Whether there are any changes */
+    readonly hasChanges: boolean;
+    /** Whether there are destructive changes */
+    readonly hasDestructiveChanges: boolean;
+    /** All parsed statements */
+    readonly statements: readonly ParsedStatement[];
+    /** Changes grouped by table */
+    readonly tableChanges: Record<string, TableChange>;
+    /** Summary counts */
+    readonly summary: DiffSummary;
+    /** Raw SQL output */
+    readonly rawSql: string;
+}
+/**
+ * Summary of changes.
+ */
+interface DiffSummary {
+    /** Total statement count */
+    readonly totalStatements: number;
+    /** Tables created */
+    readonly tablesCreated: number;
+    /** Tables dropped */
+    readonly tablesDropped: number;
+    /** Tables altered */
+    readonly tablesAltered: number;
+    /** Columns added */
+    readonly columnsAdded: number;
+    /** Columns dropped */
+    readonly columnsDropped: number;
+    /** Columns modified */
+    readonly columnsModified: number;
+    /** Indexes added */
+    readonly indexesAdded: number;
+    /** Indexes dropped */
+    readonly indexesDropped: number;
+    /** Foreign keys added */
+    readonly foreignKeysAdded: number;
+    /** Foreign keys dropped */
+    readonly foreignKeysDropped: number;
+}
+
+/**
+ * @famgia/omnify-atlas - Diff Parser
+ *
+ * Parses Atlas SQL diff output into structured format.
+ */
+
+/**
+ * Parses Atlas SQL diff output.
+ */
+declare function parseDiffOutput(sql: string): DiffResult;
+/**
+ * Formats diff result for display.
+ */
+declare function formatDiffSummary(result: DiffResult): string;
+
+/**
+ * @famgia/omnify-atlas - Preview Types
+ *
+ * Types for schema change preview.
+ */
+
+/**
+ * Options for change preview.
+ */
+interface PreviewOptions {
+    /** Whether to show raw SQL output */
+    readonly showSql?: boolean;
+    /** Whether to show detailed table changes */
+    readonly showDetails?: boolean;
+    /** Whether to include warnings for destructive changes */
+    readonly warnDestructive?: boolean;
+}
+/**
+ * Complete change preview result.
+ */
+interface ChangePreview {
+    /** Whether any changes were detected */
+    readonly hasChanges: boolean;
+    /** Whether there are destructive changes */
+    readonly hasDestructiveChanges: boolean;
+    /** Schema file changes (from lock file comparison) */
+    readonly schemaChanges: LockFileComparison;
+    /** Database schema changes (from Atlas diff) */
+    readonly databaseChanges: DiffResult;
+    /** Human-readable summary */
+    readonly summary: string;
+    /** Raw SQL for changes */
+    readonly sql: string;
+}
+/**
+ * Preview display format.
+ */
+type PreviewFormat = 'text' | 'json' | 'minimal';
+
+/**
+ * @famgia/omnify-atlas - Change Preview
+ *
+ * Generates human-readable change previews.
+ */
+
+/**
+ * Generates a change preview for schemas.
+ */
+declare function generatePreview(schemas: SchemaCollection, atlasConfig: AtlasConfig, options?: PreviewOptions): Promise<ChangePreview>;
+/**
+ * Previews changes without running Atlas (schema files only).
+ */
+declare function previewSchemaChanges(schemas: SchemaCollection, lockFilePath: string): Promise<{
+    hasChanges: boolean;
+    changes: readonly {
+        schemaName: string;
+        changeType: string;
+    }[];
+}>;
+/**
+ * Formats preview for display.
+ */
+declare function formatPreview(preview: ChangePreview, format?: PreviewFormat): string;
+/**
+ * Checks if preview has blocking issues.
+ */
+declare function hasBlockingIssues(_preview: ChangePreview): boolean;
+
+export { type AtlasConfig, type AtlasDiffOptions, type AtlasDiffResult, type AtlasInspectResult, type AtlasResult, type AtlasVersion, type ChangePreview, type ChangeSeverity, type ChangeType, type DiffResult, type DiffSummary, type GeneratedMigration, type HclColumn, type HclEnum, type HclForeignKey, type HclGenerationOptions, type HclIndex, type HclSchema, type HclTable, LOCK_FILE_NAME, LOCK_FILE_VERSION, type LockFile, type LockFileComparison, type ParsedStatement, type PreviewFormat, type PreviewOptions, type SchemaChange, type SchemaHash, type SqlColumnType, type SqlOperationType, type TableChange, addMigrationRecord, applySchema, buildSchemaHashes, checkAtlasVersion, compareSchemas, computeHash, computeSchemaHash, createEmptyLockFile, diffHclSchemas, formatDiffSummary, formatPreview, generateHclSchema, generateHclTable, generatePreview, getPrimaryKeyType, getTimestampType, hasBlockingIssues, mapPropertyToSql, parseDiffOutput, previewSchemaChanges, propertyNameToColumnName, readLockFile, renderHcl, runAtlasDiff, schemaNameToTableName, updateLockFile, validateHcl, writeLockFile };