@schemashift/core 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -143,6 +143,120 @@ declare function transformMethodChain(chain: CallChainInfo, newBase: string, fac
     args: string[];
 }[] | null | undefined): string;
 
+interface AuditEntry {
+    timestamp: string;
+    migrationId: string;
+    filePath: string;
+    action: 'transform' | 'rollback' | 'skip';
+    from: string;
+    to: string;
+    success: boolean;
+    beforeHash: string;
+    afterHash?: string;
+    warningCount: number;
+    errorCount: number;
+    riskScore?: number;
+    user?: string;
+    duration?: number;
+}
+interface AuditLog {
+    version: number;
+    entries: AuditEntry[];
+}
+declare class MigrationAuditLog {
+    private logDir;
+    private logPath;
+    constructor(projectPath: string);
+    /**
+     * Append a new entry to the audit log.
+     */
+    append(entry: AuditEntry): void;
+    /**
+     * Create an audit entry for a file transformation.
+     */
+    createEntry(params: {
+        migrationId: string;
+        filePath: string;
+        from: string;
+        to: string;
+        originalCode: string;
+        transformedCode?: string;
+        success: boolean;
+        warningCount: number;
+        errorCount: number;
+        riskScore?: number;
+        duration?: number;
+    }): AuditEntry;
+    /**
+     * Read the current audit log.
+     */
+    read(): AuditLog;
+    /**
+     * Get entries for a specific migration.
+     */
+    getByMigration(migrationId: string): AuditEntry[];
+    /**
+     * Get summary statistics for the audit log.
+     */
+    getSummary(): {
+        totalMigrations: number;
+        totalFiles: number;
+        successCount: number;
+        failureCount: number;
+        migrationPaths: string[];
+    };
+    /**
+     * Clear the audit log.
+     */
+    clear(): void;
+    private write;
+    private hashContent;
+    private getCurrentUser;
+}
+
+interface BehavioralWarning {
+    category: BehavioralCategory;
+    message: string;
+    detail: string;
+    filePath: string;
+    lineNumber?: number;
+    severity: 'info' | 'warning' | 'error';
+    migration: string;
+}
+type BehavioralCategory = 'type-coercion' | 'error-handling' | 'default-values' | 'error-format' | 'form-input' | 'validation-behavior' | 'null-handling';
+interface BehavioralAnalysisResult {
+    warnings: BehavioralWarning[];
+    migrationPath: string;
+    summary: string;
+}
+declare class BehavioralWarningAnalyzer {
+    analyze(sourceFiles: SourceFile[], from: SchemaLibrary, to: SchemaLibrary): BehavioralAnalysisResult;
+    private fileUsesLibrary;
+    private generateSummary;
+}
+
+interface BundleSizeEstimate {
+    from: LibraryBundleInfo;
+    to: LibraryBundleInfo;
+    estimatedDelta: number;
+    deltaPercent: number;
+    summary: string;
+    caveats: string[];
+}
+interface LibraryBundleInfo {
+    library: string;
+    minifiedGzipKb: number;
+    treeShakable: boolean;
+    estimatedUsedKb: number;
+}
+declare class BundleEstimator {
+    estimate(sourceFiles: SourceFile[], from: SchemaLibrary, to: SchemaLibrary): BundleSizeEstimate;
+    private countUsedValidators;
+    private getLibraryInfo;
+    private generateCaveats;
+    private generateSummary;
+}
+
 interface TransformHandler {
     transform(sourceFile: SourceFile, options: TransformOptions): TransformResult;
 }
@@ -191,6 +305,7 @@ interface EcosystemIssue {
     suggestion: string;
     severity: 'info' | 'warning' | 'error';
     category: 'orm' | 'form' | 'api' | 'validation-util' | 'openapi' | 'ui';
+    upgradeCommand?: string;
 }
 interface EcosystemReport {
     dependencies: EcosystemIssue[];
@@ -199,6 +314,10 @@ interface EcosystemReport {
 }
 declare class EcosystemAnalyzer {
     analyze(projectPath: string, from: string, to: string): EcosystemReport;
+    /**
+     * Returns a list of npm install commands needed to resolve ecosystem issues.
+     */
+    getUpgradeCommands(report: EcosystemReport): string[];
 }
 
 interface VersionIssue {
@@ -226,6 +345,34 @@ declare class CompatibilityAnalyzer {
     checkCompatibility(projectPath: string, from?: string, to?: string): CompatibilityResult;
 }
 
+type EffortLevel = 'trivial' | 'low' | 'moderate' | 'high' | 'extreme';
+interface ComplexityWarning {
+    file: string;
+    line?: number;
+    message: string;
+    severity: 'info' | 'warning' | 'error';
+}
+interface FileComplexity {
+    filePath: string;
+    schemaCount: number;
+    advancedPatterns: string[];
+    chainDepth: number;
+    lineCount: number;
+}
+interface ComplexityEstimate {
+    effort: EffortLevel;
+    totalSchemas: number;
+    totalFiles: number;
+    advancedPatternCount: number;
+    files: FileComplexity[];
+    warnings: ComplexityWarning[];
+    riskAreas: string[];
+}
+declare class ComplexityEstimator {
+    estimate(files: SourceFile[]): ComplexityEstimate;
+    private calculateEffort;
+}
+
 interface SchemaShiftConfig {
     include: string[];
     exclude: string[];
@@ -300,6 +447,60 @@ declare class SchemaDependencyResolver {
     private topologicalSort;
     private shortenPath;
 }
+interface MonorepoPackage {
+    name: string;
+    path: string;
+    schemaLibrary?: string;
+    dependencies: string[];
+}
+interface MonorepoInfo {
+    isMonorepo: boolean;
+    packages: MonorepoPackage[];
+    suggestedOrder: string[];
+}
+/**
+ * Groups monorepo packages into parallelizable batches.
+ * Packages within the same batch have no dependencies on each other.
+ * Batches must be executed in order (batch 0 first, then batch 1, etc.).
+ */
+interface ParallelBatch {
+    /** Batch index (0-based, execute in order) */
+    index: number;
+    /** Package names that can be processed in parallel */
+    packages: string[];
+}
+/**
+ * Computes parallel execution batches from a topological ordering.
+ * Packages are grouped by their "depth" in the dependency graph — packages
+ * at the same depth have no mutual dependencies and can run concurrently.
+ */
+declare function computeParallelBatches(packages: MonorepoPackage[], suggestedOrder: string[]): ParallelBatch[];
+type WorkspaceManager = 'npm' | 'pnpm' | 'yarn';
+declare class MonorepoResolver {
+    detect(projectPath: string): boolean;
+    /**
+     * Detect which workspace manager is being used.
+     */
+    detectManager(projectPath: string): WorkspaceManager;
+    analyze(projectPath: string): MonorepoInfo;
+    private suggestOrder;
+    /**
+     * Resolve workspace glob patterns from any supported format.
+     * Supports: npm/yarn workspaces (package.json), pnpm-workspace.yaml
+     */
+    private resolveWorkspaceGlobs;
+    /**
+     * Parse pnpm-workspace.yaml to extract workspace package globs.
+     * Simple YAML parsing for the common format:
+     * ```
+     * packages:
+     *   - 'packages/*'
+     *   - 'apps/*'
+     * ```
+     */
+    private parsePnpmWorkspace;
+    private resolveWorkspaceDirs;
+}
 
 interface SchemaComplexity {
     schemaName: string;
@@ -357,6 +558,16 @@ interface FormLibraryDetection {
 }
 declare function detectFormLibraries(sourceFile: SourceFile): FormLibraryDetection[];
 
+interface FormResolverResult {
+    success: boolean;
+    transformedCode: string;
+    changes: string[];
+    warnings: string[];
+}
+declare class FormResolverMigrator {
+    migrate(sourceFile: SourceFile, from: string, to: string): FormResolverResult;
+}
+
 interface GovernanceViolation {
     rule: string;
     message: string;
@@ -372,11 +583,26 @@ interface GovernanceResult {
     schemasChecked: number;
     passed: boolean;
 }
+/**
+ * Custom governance rule function interface.
+ * Plugins can define rules as functions that receive a source file and config,
+ * and return violations found.
+ */
+type GovernanceRuleFunction = (sourceFile: SourceFile, config: GovernanceRuleConfig) => GovernanceViolation[];
 declare class GovernanceEngine {
     private rules;
+    private customRuleFunctions;
     configure(rules: Record<string, GovernanceRuleConfig>): void;
+    /**
+     * Register a custom governance rule function.
+     * Custom rules are executed per-file alongside built-in rules.
+     */
+    registerRule(name: string, fn: GovernanceRuleFunction): void;
     analyze(project: Project): GovernanceResult;
     private detectFileLibrary;
+    private measureNestingDepth;
+    private detectDynamicSchemas;
+    private getSchemaPrefix;
     private isSchemaExpression;
 }
 
@@ -420,6 +646,39 @@ declare class PackageUpdater {
     apply(projectPath: string, plan: PackageUpdatePlan): void;
 }
 
+interface PerformanceWarning {
+    category: PerformanceCategory;
+    message: string;
+    detail: string;
+    filePath: string;
+    lineNumber?: number;
+    severity: 'info' | 'warning' | 'error';
+}
+type PerformanceCategory = 'jit-overhead' | 'cold-start' | 'repeated-parsing' | 'schema-creation' | 'dynamic-schemas';
+interface PerformanceAnalysisResult {
+    warnings: PerformanceWarning[];
+    parseCallSites: number;
+    dynamicSchemaCount: number;
+    recommendation: string;
+    summary: string;
+}
+/**
+ * Analyzes performance implications of schema library migration.
+ *
+ * Key considerations:
+ * - Zod v4 uses JIT compilation: 17x slower schema creation, 8x faster repeated parsing
+ * - Valibot is ~2x faster than Zod v3, similar to v4 for runtime
+ * - Serverless/edge: Zod v4 JIT penalizes cold starts
+ * - Long-lived servers: Zod v4 JIT amortizes well over repeated parses
+ */
+declare class PerformanceAnalyzer {
+    analyze(sourceFiles: SourceFile[], from: SchemaLibrary, to: SchemaLibrary): PerformanceAnalysisResult;
+    private detectDynamicSchemas;
+    private addMigrationWarnings;
+    private getRecommendation;
+    private generateSummary;
+}
+
 interface SchemaShiftPlugin {
     name: string;
     version: string;
@@ -429,6 +688,10 @@ interface SchemaShiftPlugin {
         handler: TransformHandler;
     }>;
     rules?: CustomRule[];
+    governanceRules?: Array<{
+        name: string;
+        fn: GovernanceRuleFunction;
+    }>;
 }
 interface PluginLoadResult {
     loaded: SchemaShiftPlugin[];
@@ -446,7 +709,69 @@ interface StandardSchemaInfo {
         version: string;
     }>;
     recommendation: string;
+    adoptionPath?: string;
+    interopTools: string[];
 }
 declare function detectStandardSchema(projectPath: string): StandardSchemaInfo;
 
-export { type AnalysisResult, type CallChainInfo, type ChainResult, type ChainStep, type ChainStepResult, type ChainValidation, CompatibilityAnalyzer, type CompatibilityResult, type CustomRule, type DependencyGraphResult, type DetailedAnalysisResult, DetailedAnalyzer, EcosystemAnalyzer, type EcosystemIssue, type EcosystemReport, type FormLibraryDetection, GovernanceEngine, type GovernanceResult, type GovernanceRuleConfig, type GovernanceViolation, type IncrementalState, IncrementalTracker, type LibraryVersionInfo, type MethodCallInfo, MigrationChain, type MigrationReadiness, type PackageUpdatePlan, PackageUpdater, type PluginLoadResult, PluginLoader, SchemaAnalyzer, type SchemaComplexity, SchemaDependencyResolver, type SchemaInfo, type SchemaLibrary, type SchemaShiftConfig, type SchemaShiftPlugin, type StandardSchemaInfo, TransformEngine, type TransformError, type TransformHandler, type TransformOptions, type TransformResult, type VersionIssue, type WarningSuppressionRule, buildCallChain, detectFormLibraries, detectSchemaLibrary, detectStandardSchema, isInsideComment, isInsideStringLiteral, loadConfig, parseCallChain, shouldSuppressWarning, startsWithBase, transformMethodChain, validateConfig };
+interface ScaffoldedTest {
+    filePath: string;
+    testCode: string;
+    schemaCount: number;
+}
+interface TestScaffoldResult {
+    tests: ScaffoldedTest[];
+    totalSchemas: number;
+    summary: string;
+}
+/**
+ * Generates test files that validate pre/post migration behavior equivalence.
+ *
+ * For each schema file, generates a test that:
+ * 1. Imports the schema
+ * 2. Tests validation of sample data (valid + invalid)
+ * 3. Verifies error behavior is consistent
+ */
+declare class TestScaffolder {
+    scaffold(sourceFiles: SourceFile[], from: SchemaLibrary, to: SchemaLibrary): TestScaffoldResult;
+    private extractSchemaNames;
+    private getLibraryPrefixes;
+    private generateTestFile;
+    private getParseMethod;
+    private getErrorClass;
+    private generateSchemaTests;
+}
+
+interface DuplicateTypeCandidate {
+    typeName: string;
+    typeFilePath: string;
+    typeLineNumber: number;
+    schemaName: string;
+    schemaFilePath: string;
+    schemaLineNumber: number;
+    matchedFields: string[];
+    confidence: 'high' | 'medium' | 'low';
+    suggestion: string;
+}
+interface TypeDedupResult {
+    candidates: DuplicateTypeCandidate[];
+    summary: string;
+}
+/**
+ * Detects TypeScript interfaces/types that mirror schema shapes.
+ *
+ * In Joi and Yup codebases, developers often maintain duplicate type definitions
+ * alongside schemas because those libraries don't infer TypeScript types.
+ * After migrating to Zod, these duplicates can be replaced with z.infer<typeof schema>.
+ */
+declare class TypeDedupDetector {
+    detect(sourceFiles: SourceFile[]): TypeDedupResult;
+    private collectTypeDefinitions;
+    private collectSchemaDefinitions;
+    private extractSchemaFields;
+    private findMatches;
+    private getMatchedFields;
+    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 };