@schemashift/core 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -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')`
@@ -232,6 +297,12 @@ declare class MigrationAuditLog {
      * Clear the audit log.
      */
     clear(): void;
+    /**
+     * Export a compliance report in SOC2 or HIPAA format.
+     */
+    exportComplianceReport(format: 'soc2' | 'hipaa'): string;
+    private generateSoc2Report;
+    private generateHipaaReport;
     private collectMetadata;
     private write;
     private hashContent;
@@ -392,8 +463,13 @@ interface ComplexityEstimate {
     warnings: ComplexityWarning[];
     riskAreas: string[];
 }
+interface DurationEstimate {
+    label: string;
+    rangeMinutes: [number, number];
+}
 declare class ComplexityEstimator {
     estimate(files: SourceFile[]): ComplexityEstimate;
+    estimateDuration(estimate: ComplexityEstimate): DurationEstimate;
     private calculateEffort;
 }
 
@@ -454,6 +530,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[];
@@ -691,6 +807,50 @@ 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
  *
@@ -726,6 +886,42 @@ declare function getGovernanceTemplatesByCategory(category: GovernanceTemplate['
  */
 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;
@@ -752,10 +948,144 @@ declare class IncrementalTracker {
         total: number;
         percent: number;
     } | null;
+    /**
+     * Get a canary batch — a percentage of remaining files, sorted simplest first.
+     * Used for phased rollouts where you migrate a small batch, verify, then continue.
+     */
+    getCanaryBatch(percent: number, fileSizes?: Map<string, number>): string[];
     clear(): void;
     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;
+}
+type WebhookType = 'generic' | 'slack' | 'teams';
+interface WebhookConfig {
+    url: string;
+    events?: MigrationEventType[];
+    headers?: Record<string, string>;
+    secret?: string;
+    type?: WebhookType;
+}
+/**
+ * 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[]>;
+    /**
+     * Format event as Slack Block Kit message.
+     */
+    formatSlackPayload(event: MigrationEvent): Record<string, unknown>;
+    /**
+     * Format event as Microsoft Teams Adaptive Card.
+     */
+    formatTeamsPayload(event: MigrationEvent): Record<string, unknown>;
+    private getEventEmoji;
+    private getEventTitle;
+    /**
+     * 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[];
@@ -822,6 +1152,56 @@ declare class PluginLoader {
     private validatePlugin;
 }
 
+interface VerificationSample {
+    name: string;
+    input: unknown;
+    expectedValid: boolean;
+}
+interface SchemaVerificationResult {
+    schemaName: string;
+    filePath: string;
+    totalSamples: number;
+    matchingSamples: number;
+    mismatches: VerificationMismatch[];
+    parityScore: number;
+}
+interface VerificationMismatch {
+    sampleName: string;
+    input: unknown;
+    sourceResult: {
+        valid: boolean;
+        error?: string;
+    };
+    targetResult: {
+        valid: boolean;
+        error?: string;
+    };
+}
+interface VerificationReport {
+    from: string;
+    to: string;
+    totalSchemas: number;
+    results: SchemaVerificationResult[];
+    overallParityScore: number;
+    timestamp: string;
+}
+/**
+ * Extracts schema definition names from source file text.
+ */
+declare function extractSchemaNames(sourceText: string): string[];
+/**
+ * Generates test samples based on detected schema patterns.
+ */
+declare function generateSamples(sourceText: string, schemaName: string, maxSamples: number): VerificationSample[];
+/**
+ * Creates a verification report comparing source and target schemas.
+ */
+declare function createVerificationReport(from: string, to: string, results: SchemaVerificationResult[]): VerificationReport;
+/**
+ * Format verification report for terminal output.
+ */
+declare function formatVerificationReport(report: VerificationReport): string;
+
 interface StandardSchemaInfo {
     detected: boolean;
     compatibleLibraries: Array<{
@@ -834,6 +1214,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;
@@ -894,4 +1306,4 @@ declare class TypeDedupDetector {
     private namesRelated;
 }
 
-export { type AnalysisResult, 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 CustomRule, type DependencyGraphResult, type DetailedAnalysisResult, DetailedAnalyzer, DriftDetector, type DriftModification, type DriftResult, type DuplicateTypeCandidate, EcosystemAnalyzer, type EcosystemIssue, type EcosystemReport, type EffortLevel, type FileComplexity, type FormLibraryDetection, FormResolverMigrator, type FormResolverResult, GOVERNANCE_TEMPLATES, GovernanceEngine, type GovernanceResult, type GovernanceRuleConfig, type GovernanceRuleFunction, type GovernanceTemplate, 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 SchemaFileSnapshot, type SchemaInfo, type SchemaLibrary, type SchemaShiftConfig, type SchemaShiftPlugin, type SchemaSnapshot, 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, getGovernanceTemplate, getGovernanceTemplateNames, getGovernanceTemplatesByCategory, 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, type DurationEstimate, 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, type SchemaVerificationResult, StandardSchemaAdvisor, type StandardSchemaAdvisory, type StandardSchemaInfo, type TestScaffoldResult, TestScaffolder, TransformEngine, type TransformError, type TransformHandler, type TransformOptions, type TransformResult, TypeDedupDetector, type TypeDedupResult, type VerificationMismatch, type VerificationReport, type VerificationSample, type VersionIssue, type WarningSuppressionRule, type WebhookConfig, WebhookNotifier, type WebhookType, type WorkspaceManager, buildCallChain, computeParallelBatches, conditionalValidation, createVerificationReport, dependentFields, detectFormLibraries, detectSchemaLibrary, detectStandardSchema, extractSchemaNames, formatVerificationReport, generateSamples, getAllMigrationTemplates, getGovernanceTemplate, getGovernanceTemplateNames, getGovernanceTemplatesByCategory, getMigrationTemplate, getMigrationTemplateNames, getMigrationTemplatesByCategory, isInsideComment, isInsideStringLiteral, loadConfig, mutuallyExclusive, parseCallChain, requireIf, requireOneOf, shouldSuppressWarning, startsWithBase, suggestCrossFieldPattern, transformMethodChain, validateConfig, validateMigrationTemplate };