@schemashift/core 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Project, CallExpression, Node, SourceFile } from 'ts-morph';
 
-type SchemaLibrary = 'zod' | 'zod-v3' | 'yup' | 'joi' | 'io-ts' | 'valibot' | 'v4' | 'unknown';
+type SchemaLibrary = 'zod' | 'zod-v3' | 'yup' | 'joi' | 'io-ts' | 'valibot' | 'arktype' | 'superstruct' | 'effect' | 'v4' | 'unknown';
 interface SchemaInfo {
     name: string;
     filePath: string;
@@ -46,6 +46,71 @@ declare class SchemaAnalyzer {
     getProject(): Project;
 }
 
+/**
+ * Approval Workflow for SchemaShift
+ *
+ * Provides review gates before executing migrations on shared codebases.
+ * Pending migrations are stored in `.schemashift/pending/`.
+ */
+type ApprovalStatus = 'pending' | 'approved' | 'rejected';
+interface MigrationRequest {
+    id: string;
+    from: string;
+    to: string;
+    files: string[];
+    requestedBy: string;
+    requestedAt: string;
+    status: ApprovalStatus;
+    reviewedBy?: string;
+    reviewedAt?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ApprovalDecision {
+    requestId: string;
+    status: 'approved' | 'rejected';
+    reviewedBy: string;
+    reason?: string;
+}
+interface ApprovalSummary {
+    pending: number;
+    approved: number;
+    rejected: number;
+    total: number;
+}
+/**
+ * Manages migration approval workflows with file-based persistence.
+ */
+declare class ApprovalManager {
+    private pendingDir;
+    constructor(projectPath: string);
+    /**
+     * Create a new migration request for review.
+     */
+    createRequest(from: string, to: string, files: string[], requestedBy: string, metadata?: Record<string, unknown>): MigrationRequest;
+    /**
+     * Review (approve or reject) a pending migration request.
+     */
+    review(decision: ApprovalDecision): MigrationRequest;
+    /**
+     * Get a specific migration request by ID.
+     */
+    getRequest(id: string): MigrationRequest | null;
+    /**
+     * List all migration requests, optionally filtered by status.
+     */
+    listRequests(status?: ApprovalStatus): MigrationRequest[];
+    /**
+     * Get summary counts of all requests.
+     */
+    getSummary(): ApprovalSummary;
+    /**
+     * Check if a migration has been approved.
+     */
+    isApproved(requestId: string): boolean;
+    private ensureDir;
+}
+
 /**
  * Represents a single method call in a chain.
  * e.g., `.email()` or `.min(5, 'Too short')`
@@ -143,6 +208,15 @@ declare function transformMethodChain(chain: CallChainInfo, newBase: string, fac
     args: string[];
 }[] | null | undefined): string;
 
+interface AuditEntryMetadata {
+    gitCommit?: string;
+    gitBranch?: string;
+    ciJobId?: string;
+    ciProvider?: string;
+    hostname?: string;
+    nodeVersion?: string;
+    schemashiftVersion?: string;
+}
 interface AuditEntry {
     timestamp: string;
     migrationId: string;
@@ -158,6 +232,7 @@ interface AuditEntry {
     riskScore?: number;
     user?: string;
     duration?: number;
+    metadata?: AuditEntryMetadata;
 }
 interface AuditLog {
     version: number;
@@ -186,6 +261,7 @@ declare class MigrationAuditLog {
         errorCount: number;
         riskScore?: number;
         duration?: number;
+        metadata?: AuditEntryMetadata;
     }): AuditEntry;
     /**
      * Read the current audit log.
@@ -205,10 +281,23 @@ declare class MigrationAuditLog {
         failureCount: number;
         migrationPaths: string[];
     };
+    /**
+     * Export audit log as JSON string.
+     */
+    exportJson(): string;
+    /**
+     * Export audit log as CSV string.
+     */
+    exportCsv(): string;
+    /**
+     * Get entries filtered by date range.
+     */
+    getByDateRange(start: Date, end: Date): AuditEntry[];
     /**
      * Clear the audit log.
      */
     clear(): void;
+    private collectMetadata;
     private write;
     private hashContent;
     private getCurrentUser;
@@ -430,6 +519,46 @@ declare function validateConfig(config: SchemaShiftConfig): {
 declare function shouldSuppressWarning(warning: string, filePath: string, rules: WarningSuppressionRule[]): boolean;
 declare function loadConfig(configPath?: string): Promise<SchemaShiftConfig>;
 
+/**
+ * Cross-Field Validation Pattern Helpers
+ *
+ * Provides reusable patterns for common cross-field validation scenarios.
+ * Generates `.superRefine()` code snippets for use during migration.
+ */
+interface CrossFieldPattern {
+    name: string;
+    description: string;
+    zodCode: string;
+}
+/**
+ * Generate a `.superRefine()` snippet for conditional required fields.
+ * When `conditionField` has a truthy value, `requiredField` becomes required.
+ */
+declare function requireIf(conditionField: string, requiredField: string): CrossFieldPattern;
+/**
+ * Generate a `.superRefine()` snippet requiring at least one of the given fields.
+ */
+declare function requireOneOf(fields: string[]): CrossFieldPattern;
+/**
+ * Generate a `.superRefine()` snippet for mutually exclusive fields.
+ * Only one of the given fields can have a value at a time.
+ */
+declare function mutuallyExclusive(fields: string[]): CrossFieldPattern;
+/**
+ * Generate a `.superRefine()` snippet for dependent fields.
+ * When `primaryField` is set, all `dependentFields` become required.
+ */
+declare function dependentFields(primaryField: string, dependents: string[]): CrossFieldPattern;
+/**
+ * Generate a `.superRefine()` snippet for conditional validation.
+ * When `conditionField` equals `conditionValue`, apply validation on `targetField`.
+ */
+declare function conditionalValidation(conditionField: string, conditionValue: string, targetField: string, validationMessage: string): CrossFieldPattern;
+/**
+ * Detect common cross-field patterns in Yup `.when()` calls and suggest Zod equivalents.
+ */
+declare function suggestCrossFieldPattern(whenCode: string): CrossFieldPattern | null;
+
 interface DependencyGraphResult {
     /** Files sorted in dependency order (dependencies first) */
     sortedFiles: string[];
@@ -558,6 +687,67 @@ interface FormLibraryDetection {
 }
 declare function detectFormLibraries(sourceFile: SourceFile): FormLibraryDetection[];
 
+interface SchemaSnapshot {
+    version: number;
+    timestamp: string;
+    projectPath: string;
+    schemas: SchemaFileSnapshot[];
+}
+interface SchemaFileSnapshot {
+    filePath: string;
+    library: string;
+    contentHash: string;
+    schemaCount: number;
+    schemaNames: string[];
+}
+interface DriftResult {
+    hasDrift: boolean;
+    added: SchemaFileSnapshot[];
+    removed: SchemaFileSnapshot[];
+    modified: DriftModification[];
+    unchanged: number;
+    totalFiles: number;
+    snapshotTimestamp: string;
+}
+interface DriftModification {
+    filePath: string;
+    library: string;
+    previousHash: string;
+    currentHash: string;
+    previousSchemaCount: number;
+    currentSchemaCount: number;
+    addedSchemas: string[];
+    removedSchemas: string[];
+}
+declare class DriftDetector {
+    private snapshotDir;
+    private snapshotPath;
+    constructor(projectPath: string);
+    /**
+     * Take a snapshot of the current schema state
+     */
+    snapshot(files: string[], projectPath: string): SchemaSnapshot;
+    /**
+     * Save a snapshot to disk
+     */
+    saveSnapshot(snapshot: SchemaSnapshot): void;
+    /**
+     * Load saved snapshot from disk
+     */
+    loadSnapshot(): SchemaSnapshot | null;
+    /**
+     * Compare current state against saved snapshot
+     */
+    detect(currentFiles: string[], projectPath: string): DriftResult;
+    /**
+     * Compare two snapshots and return drift results
+     */
+    compareSnapshots(baseline: SchemaSnapshot, current: SchemaSnapshot): DriftResult;
+    private extractSchemaNames;
+    private detectLibraryFromContent;
+    private hashContent;
+}
+
 interface FormResolverResult {
     success: boolean;
     transformedCode: string;
@@ -606,6 +796,121 @@ declare class GovernanceEngine {
     private isSchemaExpression;
 }
 
+interface FixResult {
+    success: boolean;
+    fixedCode?: string;
+    explanation: string;
+    rule: string;
+    lineNumber: number;
+}
+interface FixSummary {
+    totalViolations: number;
+    fixed: number;
+    skipped: number;
+    results: FixResult[];
+}
+/**
+ * GovernanceFixer applies auto-fixes for governance violations.
+ * Supports fixing: no-any-schemas, require-descriptions, require-max-length, naming-convention.
+ */
+declare class GovernanceFixer {
+    private defaultMaxLength;
+    /**
+     * Set the default max length appended by the require-max-length fix.
+     */
+    setDefaultMaxLength(length: number): void;
+    /**
+     * Check if a violation is auto-fixable.
+     */
+    canFix(violation: GovernanceViolation): boolean;
+    /**
+     * Fix a single violation in a source file.
+     * Returns the fixed code for the entire file.
+     */
+    fix(violation: GovernanceViolation, sourceCode: string): FixResult;
+    /**
+     * Fix all fixable violations in a source file.
+     * Applies fixes from bottom to top to preserve line numbers.
+     */
+    fixAll(violations: GovernanceViolation[], sourceCode: string): FixSummary;
+    private fixNoAny;
+    private fixRequireDescription;
+    private fixRequireMaxLength;
+    private fixNamingConvention;
+    private fixRequireSafeParse;
+}
+
+/**
+ * Governance Rule Templates
+ *
+ * Pre-built governance rules for common enterprise policies.
+ * These can be registered into the GovernanceEngine for quick setup.
+ *
+ * Template categories:
+ * - Security: Prevent unsafe patterns (XSS, injection, DoS)
+ * - Quality: Enforce code quality standards
+ * - Compliance: Support SOX, HIPAA, GDPR requirements
+ * - Performance: Prevent known performance pitfalls
+ */
+interface GovernanceTemplate {
+    name: string;
+    description: string;
+    category: 'security' | 'quality' | 'compliance' | 'performance';
+    rule: GovernanceRuleFunction;
+}
+/**
+ * All available governance rule templates
+ */
+declare const GOVERNANCE_TEMPLATES: GovernanceTemplate[];
+/**
+ * Get a governance template by name
+ */
+declare function getGovernanceTemplate(name: string): GovernanceTemplate | undefined;
+/**
+ * Get all templates for a category
+ */
+declare function getGovernanceTemplatesByCategory(category: GovernanceTemplate['category']): GovernanceTemplate[];
+/**
+ * Get all available template names
+ */
+declare function getGovernanceTemplateNames(): string[];
+
+interface GraphNode {
+    filePath: string;
+    shortPath: string;
+    schemaLibrary?: string;
+    schemaCount: number;
+}
+interface GraphExportOptions {
+    /** Color-code nodes by schema library */
+    colorByLibrary?: boolean;
+    /** Highlight circular dependencies in red */
+    highlightCircular?: boolean;
+    /** Only show files using a specific library */
+    filterLibrary?: string;
+    /** File metadata for enriched graph display */
+    nodeMetadata?: Map<string, {
+        library?: string;
+        schemaCount?: number;
+    }>;
+}
+/**
+ * Exports dependency graphs in DOT (Graphviz) and Mermaid formats.
+ */
+declare class GraphExporter {
+    /**
+     * Export dependency graph as DOT format for Graphviz.
+     */
+    exportDot(graph: DependencyGraphResult, options?: GraphExportOptions): string;
+    /**
+     * Export dependency graph as Mermaid diagram syntax.
+     */
+    exportMermaid(graph: DependencyGraphResult, options?: GraphExportOptions): string;
+    private shortenPath;
+    private toNodeId;
+    private toMermaidId;
+}
+
 interface IncrementalState {
     migrationId: string;
     from: SchemaLibrary;
@@ -636,6 +941,123 @@ declare class IncrementalTracker {
     private saveState;
 }
 
+interface MigrationTemplateStep {
+    from: string;
+    to: string;
+    description: string;
+}
+interface MigrationPreCheck {
+    description: string;
+    command?: string;
+}
+interface MigrationPostStep {
+    description: string;
+    command?: string;
+}
+interface PackageChange {
+    action: 'install' | 'remove' | 'upgrade';
+    package: string;
+    version?: string;
+}
+interface MigrationTemplate {
+    name: string;
+    description: string;
+    category: 'form-migration' | 'framework-upgrade' | 'library-switch' | 'monorepo';
+    migrationSteps: MigrationTemplateStep[];
+    preChecks: MigrationPreCheck[];
+    postSteps: MigrationPostStep[];
+    packageChanges: PackageChange[];
+    recommendedFlags: string[];
+    estimatedEffort: 'trivial' | 'low' | 'moderate' | 'high';
+}
+/**
+ * Get a migration template by name.
+ */
+declare function getMigrationTemplate(name: string): MigrationTemplate | undefined;
+/**
+ * Get all available migration template names.
+ */
+declare function getMigrationTemplateNames(): string[];
+/**
+ * Get all templates for a specific category.
+ */
+declare function getMigrationTemplatesByCategory(category: MigrationTemplate['category']): MigrationTemplate[];
+/**
+ * Get all built-in migration templates.
+ */
+declare function getAllMigrationTemplates(): MigrationTemplate[];
+/**
+ * Validate a custom migration template.
+ */
+declare function validateMigrationTemplate(template: MigrationTemplate): {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * Webhook Notification System for SchemaShift
+ *
+ * Sends migration event notifications to external services
+ * (Slack, Teams, Zapier, custom webhooks, etc.)
+ */
+type MigrationEventType = 'migration_started' | 'migration_completed' | 'migration_failed' | 'governance_violation' | 'drift_detected';
+interface MigrationEvent {
+    type: MigrationEventType;
+    timestamp: string;
+    project?: string;
+    details: Record<string, unknown>;
+}
+interface NotificationResult {
+    success: boolean;
+    statusCode?: number;
+    error?: string;
+}
+interface WebhookConfig {
+    url: string;
+    events?: MigrationEventType[];
+    headers?: Record<string, string>;
+    secret?: string;
+}
+/**
+ * Send migration event notifications via webhooks.
+ */
+declare class WebhookNotifier {
+    private webhooks;
+    constructor(webhooks: WebhookConfig[]);
+    /**
+     * Create a migration event with current timestamp.
+     */
+    createEvent(type: MigrationEventType, details: Record<string, unknown>, project?: string): MigrationEvent;
+    /**
+     * Send an event to all matching webhooks.
+     */
+    send(event: MigrationEvent): Promise<NotificationResult[]>;
+    /**
+     * Send event to a single webhook endpoint.
+     */
+    private sendToWebhook;
+    /**
+     * Convenience: send a migration_started event.
+     */
+    notifyMigrationStarted(from: string, to: string, fileCount: number, project?: string): Promise<NotificationResult[]>;
+    /**
+     * Convenience: send a migration_completed event.
+     */
+    notifyMigrationCompleted(from: string, to: string, fileCount: number, warningCount: number, project?: string): Promise<NotificationResult[]>;
+    /**
+     * Convenience: send a migration_failed event.
+     */
+    notifyMigrationFailed(from: string, to: string, error: string, project?: string): Promise<NotificationResult[]>;
+    /**
+     * Convenience: send a governance_violation event.
+     */
+    notifyGovernanceViolation(violationCount: number, rules: string[], project?: string): Promise<NotificationResult[]>;
+    /**
+     * Convenience: send a drift_detected event.
+     */
+    notifyDriftDetected(modifiedFiles: number, addedFiles: number, removedFiles: number, project?: string): Promise<NotificationResult[]>;
+}
+
 interface PackageUpdatePlan {
     add: Record<string, string>;
     remove: string[];
@@ -714,6 +1136,38 @@ interface StandardSchemaInfo {
 }
 declare function detectStandardSchema(projectPath: string): StandardSchemaInfo;
 
+interface StandardSchemaAdvisory {
+    shouldConsiderAdapter: boolean;
+    reason: string;
+    adapterExample?: string;
+    migrationAdvantages: string[];
+    adapterAdvantages: string[];
+    recommendation: 'migrate' | 'adapter' | 'either';
+}
+/**
+ * Advises whether to do a full migration or use Standard Schema adapters.
+ *
+ * When both source and target libraries support Standard Schema 1.0,
+ * users may not need a full migration — they can use adapters instead.
+ */
+declare class StandardSchemaAdvisor {
+    /**
+     * Check if a schema library supports Standard Schema.
+     */
+    supportsStandardSchema(library: SchemaLibrary | string): boolean;
+    /**
+     * Generate advisory for a given migration path.
+     */
+    advise(from: SchemaLibrary | string, to: SchemaLibrary | string): StandardSchemaAdvisory;
+    /**
+     * Analyze a project and provide advisory based on detected libraries.
+     */
+    adviseFromProject(projectPath: string, from: SchemaLibrary | string, to: SchemaLibrary | string): StandardSchemaAdvisory & {
+        projectInfo: StandardSchemaInfo;
+    };
+    private generateAdapterExample;
+}
+
 interface ScaffoldedTest {
     filePath: string;
     testCode: string;
@@ -774,4 +1228,4 @@ declare class TypeDedupDetector {
     private namesRelated;
 }
 
-export { type AnalysisResult, type AuditEntry, type AuditLog, type BehavioralAnalysisResult, type BehavioralCategory, type BehavioralWarning, BehavioralWarningAnalyzer, BundleEstimator, type BundleSizeEstimate, type CallChainInfo, type ChainResult, type ChainStep, type ChainStepResult, type ChainValidation, CompatibilityAnalyzer, type CompatibilityResult, type ComplexityEstimate, ComplexityEstimator, type ComplexityWarning, type CustomRule, type DependencyGraphResult, type DetailedAnalysisResult, DetailedAnalyzer, type DuplicateTypeCandidate, EcosystemAnalyzer, type EcosystemIssue, type EcosystemReport, type EffortLevel, type FileComplexity, type FormLibraryDetection, FormResolverMigrator, type FormResolverResult, GovernanceEngine, type GovernanceResult, type GovernanceRuleConfig, type GovernanceRuleFunction, type GovernanceViolation, type IncrementalState, IncrementalTracker, type LibraryBundleInfo, type LibraryVersionInfo, type MethodCallInfo, MigrationAuditLog, MigrationChain, type MigrationReadiness, type MonorepoInfo, type MonorepoPackage, MonorepoResolver, type PackageUpdatePlan, PackageUpdater, type ParallelBatch, type PerformanceAnalysisResult, PerformanceAnalyzer, type PerformanceCategory, type PerformanceWarning, type PluginLoadResult, PluginLoader, type ScaffoldedTest, SchemaAnalyzer, type SchemaComplexity, SchemaDependencyResolver, type SchemaInfo, type SchemaLibrary, type SchemaShiftConfig, type SchemaShiftPlugin, type StandardSchemaInfo, type TestScaffoldResult, TestScaffolder, TransformEngine, type TransformError, type TransformHandler, type TransformOptions, type TransformResult, TypeDedupDetector, type TypeDedupResult, type VersionIssue, type WarningSuppressionRule, type WorkspaceManager, buildCallChain, computeParallelBatches, detectFormLibraries, detectSchemaLibrary, detectStandardSchema, isInsideComment, isInsideStringLiteral, loadConfig, parseCallChain, shouldSuppressWarning, startsWithBase, transformMethodChain, validateConfig };
+export { type AnalysisResult, type ApprovalDecision, ApprovalManager, type ApprovalStatus, type ApprovalSummary, type AuditEntry, type AuditEntryMetadata, type AuditLog, type BehavioralAnalysisResult, type BehavioralCategory, type BehavioralWarning, BehavioralWarningAnalyzer, BundleEstimator, type BundleSizeEstimate, type CallChainInfo, type ChainResult, type ChainStep, type ChainStepResult, type ChainValidation, CompatibilityAnalyzer, type CompatibilityResult, type ComplexityEstimate, ComplexityEstimator, type ComplexityWarning, type CrossFieldPattern, type CustomRule, type DependencyGraphResult, type DetailedAnalysisResult, DetailedAnalyzer, DriftDetector, type DriftModification, type DriftResult, type DuplicateTypeCandidate, EcosystemAnalyzer, type EcosystemIssue, type EcosystemReport, type EffortLevel, type FileComplexity, type FixResult, type FixSummary, type FormLibraryDetection, FormResolverMigrator, type FormResolverResult, GOVERNANCE_TEMPLATES, GovernanceEngine, GovernanceFixer, type GovernanceResult, type GovernanceRuleConfig, type GovernanceRuleFunction, type GovernanceTemplate, type GovernanceViolation, type GraphExportOptions, GraphExporter, type GraphNode, type IncrementalState, IncrementalTracker, type LibraryBundleInfo, type LibraryVersionInfo, type MethodCallInfo, MigrationAuditLog, MigrationChain, type MigrationEvent, type MigrationEventType, type MigrationReadiness, type MigrationRequest, type MigrationTemplate, type MigrationTemplateStep, type MonorepoInfo, type MonorepoPackage, MonorepoResolver, type NotificationResult, type PackageChange, type PackageUpdatePlan, PackageUpdater, type ParallelBatch, type PerformanceAnalysisResult, PerformanceAnalyzer, type PerformanceCategory, type PerformanceWarning, type PluginLoadResult, PluginLoader, type ScaffoldedTest, SchemaAnalyzer, type SchemaComplexity, SchemaDependencyResolver, type SchemaFileSnapshot, type SchemaInfo, type SchemaLibrary, type SchemaShiftConfig, type SchemaShiftPlugin, type SchemaSnapshot, StandardSchemaAdvisor, type StandardSchemaAdvisory, type StandardSchemaInfo, type TestScaffoldResult, TestScaffolder, TransformEngine, type TransformError, type TransformHandler, type TransformOptions, type TransformResult, TypeDedupDetector, type TypeDedupResult, type VersionIssue, type WarningSuppressionRule, type WebhookConfig, WebhookNotifier, type WorkspaceManager, buildCallChain, computeParallelBatches, conditionalValidation, dependentFields, detectFormLibraries, detectSchemaLibrary, detectStandardSchema, getAllMigrationTemplates, getGovernanceTemplate, getGovernanceTemplateNames, getGovernanceTemplatesByCategory, getMigrationTemplate, getMigrationTemplateNames, getMigrationTemplatesByCategory, isInsideComment, isInsideStringLiteral, loadConfig, mutuallyExclusive, parseCallChain, requireIf, requireOneOf, shouldSuppressWarning, startsWithBase, suggestCrossFieldPattern, transformMethodChain, validateConfig, validateMigrationTemplate };