@schemashift/core 0.8.0 → 0.10.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;
@@ -143,6 +143,144 @@ 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;
+    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;
+    metadata?: AuditEntryMetadata;
+}
+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;
+        metadata?: AuditEntryMetadata;
+    }): 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[];
+    };
+    /**
+     * 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;
+}
+
+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;
 }
@@ -200,6 +338,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 {
@@ -340,10 +482,47 @@ interface MonorepoInfo {
     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;
 }
 
@@ -403,6 +582,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;
@@ -428,14 +668,64 @@ 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;
 }
 
+/**
+ * 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 IncrementalState {
     migrationId: string;
     from: SchemaLibrary;
@@ -476,6 +766,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;
@@ -485,6 +808,10 @@ interface SchemaShiftPlugin {
         handler: TransformHandler;
     }>;
     rules?: CustomRule[];
+    governanceRules?: Array<{
+        name: string;
+        fn: GovernanceRuleFunction;
+    }>;
 }
 interface PluginLoadResult {
     loaded: SchemaShiftPlugin[];
@@ -502,7 +829,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 ComplexityEstimate, ComplexityEstimator, type ComplexityWarning, type CustomRule, type DependencyGraphResult, type DetailedAnalysisResult, DetailedAnalyzer, EcosystemAnalyzer, type EcosystemIssue, type EcosystemReport, type EffortLevel, type FileComplexity, type FormLibraryDetection, FormResolverMigrator, type FormResolverResult, GovernanceEngine, type GovernanceResult, type GovernanceRuleConfig, type GovernanceViolation, type IncrementalState, IncrementalTracker, type LibraryVersionInfo, type MethodCallInfo, MigrationChain, type MigrationReadiness, type MonorepoInfo, type MonorepoPackage, MonorepoResolver, 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 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 };