@codeyam/codeyam-cli 0.1.0-staging.d0ad4ae → 0.1.0-staging.d3e886e

package/packages/analyze/src/lib/files/scenarios/TransformationTracer.js

@@ -0,0 +1,880 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Compute the diff between two schema objects.
+ */
+export function computeSchemaDiff(before, after) {
+    const diff = {
+        added: {},
+        removed: {},
+        changed: {},
+    };
+    const beforeKeys = new Set(Object.keys(before ?? {}));
+    const afterKeys = new Set(Object.keys(after ?? {}));
+    // Find added keys
+    for (const key of afterKeys) {
+        if (!beforeKeys.has(key)) {
+            diff.added[key] = after[key];
+        }
+    }
+    // Find removed keys
+    for (const key of beforeKeys) {
+        if (!afterKeys.has(key)) {
+            diff.removed[key] = before[key];
+        }
+    }
+    // Find changed keys
+    for (const key of beforeKeys) {
+        if (afterKeys.has(key) && before[key] !== after[key]) {
+            diff.changed[key] = { from: before[key], to: after[key] };
+        }
+    }
+    return diff;
+}
+/**
+ * Check if a diff has any changes.
+ */
+export function hasDiffChanges(diff) {
+    return (Object.keys(diff.added).length > 0 ||
+        Object.keys(diff.removed).length > 0 ||
+        Object.keys(diff.changed).length > 0);
+}
+/**
+ * Count total changes in a diff.
+ */
+export function countDiffChanges(diff) {
+    return (Object.keys(diff.added).length +
+        Object.keys(diff.removed).length +
+        Object.keys(diff.changed).length);
+}
+// ============================================================================
+// TransformationTracer Class
+// ============================================================================
+// Global counter to identify tracer instances
+let tracerInstanceCounter = 0;
+export class TransformationTracer {
+    constructor(options) {
+        this.traces = new Map();
+        this.currentEntity = null;
+        this.currentStage = null;
+        this.tracerId = ++tracerInstanceCounter;
+        this.enabled = options?.enabled ?? false;
+        this.outputPath =
+            options?.outputPath ?? '/tmp/codeyam/transform-trace.json';
+        if (this.enabled) {
+            console.log(`[Tracer] Initialized (id=${this.tracerId}, output=${this.outputPath})`);
+        }
+    }
+    /**
+     * Log a message (only when tracing is enabled).
+     */
+    log(message) {
+        if (this.isEnabled()) {
+            console.log(`[Tracer] ${message}`);
+        }
+    }
+    /**
+     * Check if tracing is enabled.
+     * Dynamically checks environment variable so it works even if set after module load.
+     */
+    isEnabled() {
+        // Check environment variable dynamically - allows setting after module load
+        const envValue = process.env.CODEYAM_TRACE_TRANSFORMS;
+        if (envValue === '1' || envValue === 'true') {
+            return true;
+        }
+        return this.enabled;
+    }
+    /**
+     * Enable tracing.
+     */
+    enable() {
+        this.enabled = true;
+    }
+    /**
+     * Disable tracing.
+     */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Set the output path for the trace file.
+     */
+    setOutputPath(outputPath) {
+        this.outputPath = outputPath;
+    }
+    /**
+     * Set the project slug for metadata.
+     */
+    setProjectSlug(slug) {
+        this.projectSlug = slug;
+    }
+    /**
+     * Start tracing a new entity.
+     * If the entity already exists, preserves its existing stages and operations.
+     */
+    startEntity(entity) {
+        if (!this.isEnabled())
+            return;
+        this.currentEntity = entity.name;
+        // Preserve existing trace data if entity was already started
+        // (e.g., early stages from generateEntityDataStructure.ts)
+        const existing = this.traces.get(entity.name);
+        if (existing) {
+            this.log(`startEntity: ${entity.name} already exists, preserving ${existing.stages.length} stages`);
+            return; // Keep existing trace data
+        }
+        this.log(`startEntity: ${entity.name}`);
+        this.traces.set(entity.name, {
+            entityName: entity.name,
+            entityType: entity.entityType,
+            filePath: entity.filePath,
+            stages: [],
+            operations: [],
+        });
+    }
+    /**
+     * Take a coarse-grained snapshot at a transformation stage.
+     */
+    snapshot(entityName, stage, data) {
+        if (!this.isEnabled())
+            return;
+        const trace = this.traces.get(entityName);
+        if (!trace) {
+            this.log(`snapshot: no trace for ${entityName}, creating one`);
+            this.startEntity({
+                name: entityName,
+                entityType: 'unknown',
+                filePath: 'unknown',
+            });
+            return this.snapshot(entityName, stage, data);
+        }
+        this.log(`snapshot: ${entityName} → ${stage}`);
+        this.currentStage = stage;
+        // Deep clone the data to avoid capturing references that change later
+        const clonedData = JSON.parse(JSON.stringify(data));
+        const snapshot = {
+            stage,
+            timestamp: Date.now(),
+            data: clonedData,
+        };
+        // Compute diff from previous stage if there is one
+        const previousSnapshot = trace.stages[trace.stages.length - 1];
+        if (previousSnapshot) {
+            snapshot.diffFromPrevious = {
+                signatureSchema: computeSchemaDiff(previousSnapshot.data.signatureSchema, clonedData.signatureSchema),
+                returnValueSchema: computeSchemaDiff(previousSnapshot.data.returnValueSchema, clonedData.returnValueSchema),
+            };
+            // Compute diffs for dependency schemas
+            if (clonedData.dependencySchemas ||
+                previousSnapshot.data.dependencySchemas) {
+                snapshot.diffFromPrevious.dependencySchemas = {};
+                const allDepKeys = new Set([
+                    ...Object.keys(clonedData.dependencySchemas ?? {}),
+                    ...Object.keys(previousSnapshot.data.dependencySchemas ?? {}),
+                ]);
+                for (const depKey of allDepKeys) {
+                    const prevDep = previousSnapshot.data.dependencySchemas?.[depKey];
+                    const currDep = clonedData.dependencySchemas?.[depKey];
+                    // Compare returnValueSchema for each dependency
+                    for (const entityKey of new Set([
+                        ...Object.keys(prevDep ?? {}),
+                        ...Object.keys(currDep ?? {}),
+                    ])) {
+                        const fullKey = `${depKey}::${entityKey}`;
+                        const prevSchema = prevDep?.[entityKey]?.returnValueSchema;
+                        const currSchema = currDep?.[entityKey]?.returnValueSchema;
+                        const depDiff = computeSchemaDiff(prevSchema, currSchema);
+                        if (hasDiffChanges(depDiff)) {
+                            snapshot.diffFromPrevious.dependencySchemas[fullKey] = depDiff;
+                        }
+                    }
+                }
+            }
+        }
+        trace.stages.push(snapshot);
+    }
+    /**
+     * Log a fine-grained operation within the current stage.
+     */
+    operation(entityName, op) {
+        if (!this.isEnabled())
+            return;
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return;
+        trace.operations.push({
+            ...op,
+            stage: op.stage ?? this.currentStage ?? undefined,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Write the trace to the output file.
+     */
+    flush() {
+        if (!this.isEnabled())
+            return;
+        if (this.traces.size === 0) {
+            this.log('flush: no traces to write');
+            return;
+        }
+        const entities = Array.from(this.traces.keys());
+        const stageCounts = entities
+            .map((e) => `${e}(${this.traces.get(e).stages.length})`)
+            .join(', ');
+        this.log(`flush: writing ${entities.length} entities: ${stageCounts}`);
+        // Compute summary
+        const stageChangeCounts = {};
+        const entityChangeCounts = new Map();
+        for (const [entityName, trace] of this.traces) {
+            let entityTotal = 0;
+            for (const snapshot of trace.stages) {
+                if (!snapshot.diffFromPrevious)
+                    continue;
+                const previousStage = trace.stages[trace.stages.indexOf(snapshot) - 1]?.stage ?? 'start';
+                const transitionKey = `${previousStage}→${snapshot.stage}`;
+                if (!stageChangeCounts[transitionKey]) {
+                    stageChangeCounts[transitionKey] = {
+                        added: 0,
+                        removed: 0,
+                        changed: 0,
+                    };
+                }
+                // Count signature schema changes
+                if (snapshot.diffFromPrevious.signatureSchema) {
+                    const diff = snapshot.diffFromPrevious.signatureSchema;
+                    stageChangeCounts[transitionKey].added += Object.keys(diff.added).length;
+                    stageChangeCounts[transitionKey].removed += Object.keys(diff.removed).length;
+                    stageChangeCounts[transitionKey].changed += Object.keys(diff.changed).length;
+                    entityTotal += countDiffChanges(diff);
+                }
+                // Count return value schema changes
+                if (snapshot.diffFromPrevious.returnValueSchema) {
+                    const diff = snapshot.diffFromPrevious.returnValueSchema;
+                    stageChangeCounts[transitionKey].added += Object.keys(diff.added).length;
+                    stageChangeCounts[transitionKey].removed += Object.keys(diff.removed).length;
+                    stageChangeCounts[transitionKey].changed += Object.keys(diff.changed).length;
+                    entityTotal += countDiffChanges(diff);
+                }
+            }
+            entityChangeCounts.set(entityName, entityTotal);
+        }
+        // Get top 10 entities with most changes
+        const entitiesWithMostChanges = [...entityChangeCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([name]) => name);
+        const traceFile = {
+            meta: {
+                timestamp: new Date().toISOString(),
+                projectSlug: this.projectSlug,
+                entityCount: this.traces.size,
+            },
+            summary: {
+                stageChangeCounts,
+                entitiesWithMostChanges,
+            },
+            entities: Object.fromEntries(this.traces),
+        };
+        // Ensure directory exists
+        const dir = path.dirname(this.outputPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(this.outputPath, JSON.stringify(traceFile, null, 2));
+        this.log(`flush: wrote trace to ${this.outputPath}`);
+    }
+    /**
+     * Clear all traces (useful for testing).
+     */
+    clear() {
+        this.traces.clear();
+        this.currentEntity = null;
+        this.currentStage = null;
+    }
+    // ============================================================================
+    // Analysis Utilities
+    // ============================================================================
+    /**
+     * Load a trace from a file.
+     */
+    static loadTrace(tracePath) {
+        const content = fs.readFileSync(tracePath, 'utf-8');
+        const traceFile = JSON.parse(content);
+        const tracer = new TransformationTracer({ enabled: false });
+        tracer.projectSlug = traceFile.meta.projectSlug;
+        for (const [entityName, entityTrace] of Object.entries(traceFile.entities)) {
+            tracer.traces.set(entityName, entityTrace);
+        }
+        return tracer;
+    }
+    /**
+     * Get a high-level summary of the trace.
+     */
+    getSummary() {
+        const stageChangeCounts = {};
+        const entityChangeCounts = new Map();
+        for (const [entityName, trace] of this.traces) {
+            let entityTotal = 0;
+            for (let i = 1; i < trace.stages.length; i++) {
+                const snapshot = trace.stages[i];
+                const previousStage = trace.stages[i - 1]?.stage ?? 'start';
+                const transitionKey = `${previousStage}→${snapshot.stage}`;
+                if (!stageChangeCounts[transitionKey]) {
+                    stageChangeCounts[transitionKey] = {
+                        added: 0,
+                        removed: 0,
+                        changed: 0,
+                    };
+                }
+                if (snapshot.diffFromPrevious?.signatureSchema) {
+                    const diff = snapshot.diffFromPrevious.signatureSchema;
+                    stageChangeCounts[transitionKey].added += Object.keys(diff.added).length;
+                    stageChangeCounts[transitionKey].removed += Object.keys(diff.removed).length;
+                    stageChangeCounts[transitionKey].changed += Object.keys(diff.changed).length;
+                    entityTotal += countDiffChanges(diff);
+                }
+                if (snapshot.diffFromPrevious?.returnValueSchema) {
+                    const diff = snapshot.diffFromPrevious.returnValueSchema;
+                    stageChangeCounts[transitionKey].added += Object.keys(diff.added).length;
+                    stageChangeCounts[transitionKey].removed += Object.keys(diff.removed).length;
+                    stageChangeCounts[transitionKey].changed += Object.keys(diff.changed).length;
+                    entityTotal += countDiffChanges(diff);
+                }
+            }
+            entityChangeCounts.set(entityName, entityTotal);
+        }
+        const entitiesWithMostChanges = [...entityChangeCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([name, totalChanges]) => ({ name, totalChanges }));
+        return {
+            entityCount: this.traces.size,
+            stageChangeCounts,
+            entitiesWithMostChanges,
+        };
+    }
+    /**
+     * Get a summary of stages for a specific entity.
+     */
+    getEntitySummary(entityName) {
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return null;
+        return {
+            entityName,
+            stages: trace.stages.map((s) => ({
+                stage: s.stage,
+                diffFromPrevious: s.diffFromPrevious
+                    ? {
+                        signatureSchema: s.diffFromPrevious.signatureSchema,
+                        returnValueSchema: s.diffFromPrevious.returnValueSchema,
+                    }
+                    : undefined,
+            })),
+        };
+    }
+    /**
+     * Get operations for an entity, optionally filtered by path pattern.
+     */
+    getOperations(entityName, pathPattern) {
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return [];
+        if (!pathPattern)
+            return trace.operations;
+        return trace.operations.filter((op) => op.path && pathPattern.test(op.path));
+    }
+    /**
+     * Trace the full history of a specific path through all transformations.
+     */
+    tracePath(entityName, targetPath) {
+        const trace = this.traces.get(entityName);
+        const history = [];
+        if (!trace) {
+            return { entityName, path: targetPath, history };
+        }
+        // Track value through stages
+        for (const snapshot of trace.stages) {
+            const sigValue = snapshot.data.signatureSchema?.[targetPath];
+            const retValue = snapshot.data.returnValueSchema?.[targetPath];
+            const value = sigValue ?? retValue;
+            if (value !== undefined) {
+                history.push({
+                    stage: snapshot.stage,
+                    value,
+                });
+            }
+        }
+        // Track value through operations
+        for (const op of trace.operations) {
+            if (op.path === targetPath) {
+                history.push({
+                    operation: op.operation,
+                    stage: op.stage,
+                    value: op.after ?? op.before,
+                    context: op.context,
+                });
+            }
+        }
+        return { entityName, path: targetPath, history };
+    }
+    /**
+     * Get the raw entity trace for direct inspection.
+     */
+    getEntityTrace(entityName) {
+        return this.traces.get(entityName);
+    }
+    /**
+     * Get all entity names in the trace.
+     */
+    getEntityNames() {
+        return [...this.traces.keys()];
+    }
+    // ============================================================================
+    // Debugging Utilities
+    // ============================================================================
+    /**
+     * Find all paths containing a property name across all stages.
+     * Useful for debugging: "where does 'analyses' appear in the schema?"
+     */
+    findProperty(entityName, propertyName) {
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return [];
+        const results = [];
+        const pattern = new RegExp(`(^|\\.)${propertyName}(\\.|\\[|$)`);
+        for (const snapshot of trace.stages) {
+            // Search signature schema
+            for (const [path, type] of Object.entries(snapshot.data.signatureSchema ?? {})) {
+                if (pattern.test(path)) {
+                    results.push({
+                        stage: snapshot.stage,
+                        path,
+                        type,
+                        schemaType: 'signature',
+                    });
+                }
+            }
+            // Search return value schema
+            for (const [path, type] of Object.entries(snapshot.data.returnValueSchema ?? {})) {
+                if (pattern.test(path)) {
+                    results.push({
+                        stage: snapshot.stage,
+                        path,
+                        type,
+                        schemaType: 'returnValue',
+                    });
+                }
+            }
+            // Search dependency schemas
+            for (const [depPath, depEntities] of Object.entries(snapshot.data.dependencySchemas ?? {})) {
+                for (const [depName, depData] of Object.entries(depEntities)) {
+                    for (const [path, type] of Object.entries(depData.returnValueSchema ?? {})) {
+                        if (pattern.test(path)) {
+                            results.push({
+                                stage: snapshot.stage,
+                                path: `${depPath}/${depName}::${path}`,
+                                type,
+                                schemaType: 'dependency',
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Find properties that have inconsistent types across different paths.
+     * Useful for debugging: "why does 'analyses' have different types?"
+     *
+     * Only compares paths that end with the same pattern (e.g., both end in `.analyses`
+     * or both end in `.analyses[]`). Ignores built-in properties like `.length`.
+     */
+    findTypeInconsistencies(entityName) {
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return [];
+        // Find the best stage for comparison (last one with dependency schemas)
+        let targetStage = trace.stages[trace.stages.length - 1];
+        for (let i = trace.stages.length - 1; i >= 0; i--) {
+            if (Object.keys(trace.stages[i].data.dependencySchemas ?? {}).length > 0) {
+                targetStage = trace.stages[i];
+                break;
+            }
+        }
+        if (!targetStage)
+            return [];
+        // Built-in properties to ignore
+        const builtIns = new Set(['length', 'toString', 'valueOf', 'constructor']);
+        // Group paths by their terminal pattern (e.g., ".analyses" or ".analyses[]")
+        const propertyGroups = new Map();
+        const addToGroup = (path, type) => {
+            // Extract terminal property pattern (e.g., "foo.bar.analyses[]" -> "analyses[]")
+            const match = path.match(/\.([a-zA-Z_][a-zA-Z0-9_]*)(\[\])?$/);
+            if (!match)
+                return;
+            const propName = match[1];
+            const isArray = match[2] === '[]';
+            // Skip built-in properties
+            if (builtIns.has(propName))
+                return;
+            // Use pattern as key (includes [] suffix)
+            const pattern = propName + (isArray ? '[]' : '');
+            if (!propertyGroups.has(pattern)) {
+                propertyGroups.set(pattern, []);
+            }
+            propertyGroups.get(pattern).push({ path, type });
+        };
+        // Collect from dependency schemas (where inconsistencies usually appear)
+        for (const [, depEntities] of Object.entries(targetStage.data.dependencySchemas ?? {})) {
+            for (const [, depData] of Object.entries(depEntities)) {
+                for (const [path, type] of Object.entries(depData.returnValueSchema ?? {})) {
+                    addToGroup(path, type);
+                }
+            }
+        }
+        // Find inconsistencies (same terminal pattern, different types)
+        const inconsistencies = [];
+        for (const [pattern, paths] of propertyGroups) {
+            // Normalize types for comparison (treat "unknown | undefined" and "unknown" as similar)
+            const normalizedTypes = new Set(paths.map((p) => p.type.replace(/ \| undefined/g, '').replace(/ \| null/g, '')));
+            if (normalizedTypes.size > 1) {
+                inconsistencies.push({
+                    propertyName: pattern,
+                    paths: paths.map((p) => ({ ...p, stage: targetStage.stage })),
+                });
+            }
+        }
+        // Sort by number of different types (most inconsistent first)
+        inconsistencies.sort((a, b) => {
+            const aTypes = new Set(a.paths.map((p) => p.type)).size;
+            const bTypes = new Set(b.paths.map((p) => p.type)).size;
+            return bTypes - aTypes;
+        });
+        return inconsistencies;
+    }
+    /**
+     * Get a human-readable summary of changes between two stages.
+     */
+    getStageDiffSummary(entityName, fromStage, toStage) {
+        const trace = this.traces.get(entityName);
+        if (!trace)
+            return null;
+        const from = trace.stages.find((s) => s.stage === fromStage);
+        const to = trace.stages.find((s) => s.stage === toStage);
+        if (!from || !to)
+            return null;
+        const result = {
+            added: [],
+            removed: [],
+            typeChanged: [],
+        };
+        // Compare return value schemas (most common)
+        const fromSchema = from.data.returnValueSchema ?? {};
+        const toSchema = to.data.returnValueSchema ?? {};
+        const fromKeys = new Set(Object.keys(fromSchema));
+        const toKeys = new Set(Object.keys(toSchema));
+        for (const key of toKeys) {
+            if (!fromKeys.has(key)) {
+                result.added.push(`${key}: ${toSchema[key]}`);
+            }
+            else if (fromSchema[key] !== toSchema[key]) {
+                result.typeChanged.push({
+                    path: key,
+                    from: fromSchema[key],
+                    to: toSchema[key],
+                });
+            }
+        }
+        for (const key of fromKeys) {
+            if (!toKeys.has(key)) {
+                result.removed.push(`${key}: ${fromSchema[key]}`);
+            }
+        }
+        return result;
+    }
+    /**
+     * Trace a schema transformation by capturing before/after and logging operations for all changes.
+     *
+     * This is a helper to wrap transformative functions like:
+     * - cleanKnownObjectFunctionsFromMapping
+     * - clearAttributesFromMapping
+     * - fillInDirectSchemaGapsAndUnknowns
+     * - deduplicateFunctionSchemas
+     *
+     * @param entityName - The entity being traced
+     * @param operationName - Name of the transformation (e.g., 'cleanKnownObjectFunctions')
+     * @param schema - The schema to transform (will be mutated)
+     * @param transformFn - The transformation function to run
+     * @param context - Optional context to include in operation logs
+     * @returns The schema (same reference, mutated)
+     */
+    traceSchemaTransform(entityName, operationName, schema, transformFn, context) {
+        if (!this.enabled) {
+            transformFn(schema);
+            return schema;
+        }
+        // Capture before state
+        const before = { ...schema };
+        // Run the transformation
+        transformFn(schema);
+        // Compute diff and log operations
+        const diff = computeSchemaDiff(before, schema);
+        // Log added paths
+        for (const [path, value] of Object.entries(diff.added)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: undefined,
+                after: value,
+                context: { ...context, changeType: 'added' },
+            });
+        }
+        // Log removed paths
+        for (const [path, value] of Object.entries(diff.removed)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: value,
+                after: undefined,
+                context: { ...context, changeType: 'removed' },
+            });
+        }
+        // Log changed paths
+        for (const [path, { from, to }] of Object.entries(diff.changed)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: from,
+                after: to,
+                context: { ...context, changeType: 'changed' },
+            });
+        }
+        return schema;
+    }
+    /**
+     * Trace a schema transformation where the function returns a new schema (non-mutating).
+     *
+     * Use this for functions like deduplicateFunctionSchemas that return a new object
+     * rather than mutating the input.
+     *
+     * @param entityName - The entity being traced
+     * @param operationName - Name of the transformation
+     * @param before - The schema before transformation
+     * @param after - The schema after transformation
+     * @param context - Optional context to include in operation logs
+     */
+    traceSchemaTransformResult(entityName, operationName, before, after, context) {
+        if (!this.enabled)
+            return;
+        // Compute diff and log operations
+        const diff = computeSchemaDiff(before, after);
+        // Log added paths
+        for (const [path, value] of Object.entries(diff.added)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: undefined,
+                after: value,
+                context: { ...context, changeType: 'added' },
+            });
+        }
+        // Log removed paths
+        for (const [path, value] of Object.entries(diff.removed)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: value,
+                after: undefined,
+                context: { ...context, changeType: 'removed' },
+            });
+        }
+        // Log changed paths
+        for (const [path, { from, to }] of Object.entries(diff.changed)) {
+            this.operation(entityName, {
+                operation: operationName,
+                path,
+                before: from,
+                after: to,
+                context: { ...context, changeType: 'changed' },
+            });
+        }
+    }
+    /**
+     * Trace multiple schemas in a dependency schemas structure.
+     * Useful for tracing transformations that apply to all dependency schemas.
+     *
+     * @param entityName - The entity being traced
+     * @param operationName - Name of the transformation
+     * @param dependencySchemas - The dependency schemas structure
+     * @param transformFn - Function to apply to each schema (signature or returnValue)
+     * @param schemaType - Which schema to transform: 'signature', 'returnValue', or 'both'
+     */
+    traceDependencySchemaTransform(entityName, operationName, dependencySchemas, transformFn, schemaType = 'both') {
+        if (!this.enabled) {
+            // Still run the transform even if not tracing
+            for (const filePath in dependencySchemas) {
+                for (const depName in dependencySchemas[filePath]) {
+                    const depSchema = dependencySchemas[filePath][depName];
+                    if ((schemaType === 'signature' || schemaType === 'both') &&
+                        depSchema.signatureSchema) {
+                        transformFn(depSchema.signatureSchema);
+                    }
+                    if ((schemaType === 'returnValue' || schemaType === 'both') &&
+                        depSchema.returnValueSchema) {
+                        transformFn(depSchema.returnValueSchema);
+                    }
+                }
+            }
+            return;
+        }
+        for (const filePath in dependencySchemas) {
+            for (const depName in dependencySchemas[filePath]) {
+                const depSchema = dependencySchemas[filePath][depName];
+                const depContext = { filePath, dependencyName: depName };
+                if ((schemaType === 'signature' || schemaType === 'both') &&
+                    depSchema.signatureSchema) {
+                    this.traceSchemaTransform(entityName, operationName, depSchema.signatureSchema, transformFn, { ...depContext, schemaType: 'signature' });
+                }
+                if ((schemaType === 'returnValue' || schemaType === 'both') &&
+                    depSchema.returnValueSchema) {
+                    this.traceSchemaTransform(entityName, operationName, depSchema.returnValueSchema, transformFn, { ...depContext, schemaType: 'returnValue' });
+                }
+            }
+        }
+    }
+    /**
+     * Trace changes to dependency schemas before/after a function call.
+     *
+     * Use this for functions like enrichArrayTypesFromChildSignatures or
+     * enrichUnknownTypesFromSourceEquivalencies that modify dependency schemas in place.
+     *
+     * @param entityName - The entity being traced
+     * @param operationName - Name of the transformation
+     * @param dependencySchemas - The dependency schemas to track
+     * @param transformFn - The function to run (should mutate dependencySchemas)
+     */
+    traceDependencySchemaChanges(entityName, operationName, dependencySchemas, transformFn) {
+        if (!this.enabled) {
+            transformFn();
+            return;
+        }
+        // Capture before state (deep copy of all schemas)
+        const beforeState = {};
+        for (const filePath in dependencySchemas) {
+            beforeState[filePath] = {};
+            for (const depName in dependencySchemas[filePath]) {
+                const depSchema = dependencySchemas[filePath][depName];
+                beforeState[filePath][depName] = {
+                    sig: { ...(depSchema.signatureSchema || {}) },
+                    rv: { ...(depSchema.returnValueSchema || {}) },
+                };
+            }
+        }
+        // Run the transformation
+        transformFn();
+        // Compare and log changes
+        for (const filePath in dependencySchemas) {
+            for (const depName in dependencySchemas[filePath]) {
+                const depSchema = dependencySchemas[filePath][depName];
+                const before = beforeState[filePath]?.[depName];
+                const context = { filePath, dependencyName: depName };
+                // Check signature schema changes
+                if (depSchema.signatureSchema) {
+                    const sigBefore = before?.sig || {};
+                    const diff = computeSchemaDiff(sigBefore, depSchema.signatureSchema);
+                    for (const [path, value] of Object.entries(diff.added)) {
+                        this.operation(entityName, {
+                            operation: operationName,
+                            path,
+                            before: undefined,
+                            after: value,
+                            context: {
+                                ...context,
+                                schemaType: 'signature',
+                                changeType: 'added',
+                            },
+                        });
+                    }
+                    for (const [path, { from, to }] of Object.entries(diff.changed)) {
+                        this.operation(entityName, {
+                            operation: operationName,
+                            path,
+                            before: from,
+                            after: to,
+                            context: {
+                                ...context,
+                                schemaType: 'signature',
+                                changeType: 'changed',
+                            },
+                        });
+                    }
+                }
+                // Check return value schema changes
+                if (depSchema.returnValueSchema) {
+                    const rvBefore = before?.rv || {};
+                    const diff = computeSchemaDiff(rvBefore, depSchema.returnValueSchema);
+                    for (const [path, value] of Object.entries(diff.added)) {
+                        this.operation(entityName, {
+                            operation: operationName,
+                            path,
+                            before: undefined,
+                            after: value,
+                            context: {
+                                ...context,
+                                schemaType: 'returnValue',
+                                changeType: 'added',
+                            },
+                        });
+                    }
+                    for (const [path, { from, to }] of Object.entries(diff.changed)) {
+                        this.operation(entityName, {
+                            operation: operationName,
+                            path,
+                            before: from,
+                            after: to,
+                            context: {
+                                ...context,
+                                schemaType: 'returnValue',
+                                changeType: 'changed',
+                            },
+                        });
+                    }
+                }
+            }
+        }
+    }
+}
+// ============================================================================
+// Global Instance
+// ============================================================================
+/**
+ * Check if tracing is enabled via environment variable.
+ */
+function isTracingEnabled() {
+    const envValue = process.env.CODEYAM_TRACE_TRANSFORMS;
+    return envValue === '1' || envValue === 'true';
+}
+/**
+ * Global tracer instance.
+ * Enabled via CODEYAM_TRACE_TRANSFORMS=1 environment variable.
+ * Output is always written to /tmp/codeyam/transform-trace.json
+ */
+export const transformationTracer = new TransformationTracer({
+    enabled: isTracingEnabled(),
+    outputPath: '/tmp/codeyam/transform-trace.json',
+});
+// Auto-flush on process exit if tracing is enabled and there's data
+process.on('beforeExit', () => {
+    if (transformationTracer.isEnabled()) {
+        transformationTracer.flush();
+    }
+});
+export default transformationTracer;
+//# sourceMappingURL=TransformationTracer.js.map