@codeyam/codeyam-cli 0.1.0-staging.e38f7bd → 0.1.0-staging.fef152f

package/analyzer-template/packages/analyze/src/lib/files/scenarios/TransformationTracer.ts

@@ -0,0 +1,1315 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * TransformationTracer
+ *
+ * A tracer that captures data structure transformations during analysis.
+ * Captures everything at both coarse-grained (stage snapshots) and fine-grained
+ * (individual operations) levels for post-hoc analysis without rerunning.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Enable via environment variable
+ * CODEYAM_TRACE_TRANSFORMS=1 codeyam analyze
+ *
+ * // In code
+ * transformationTracer.startEntity(entity);
+ * transformationTracer.snapshot(entity.name, 'isolated', { signatureSchema, ... });
+ * transformationTracer.operation(entity.name, { operation: 'mergePostfix', path: 'sig[0].user', ... });
+ * transformationTracer.snapshot(entity.name, 'merged', { signatureSchema, ... });
+ * ```
+ *
+ * ## Analyzing Traces
+ *
+ * ```typescript
+ * const tracer = TransformationTracer.loadTrace('/tmp/codeyam/transform-trace.json');
+ * console.log(tracer.getSummary());
+ * console.log(tracer.getEntitySummary('DashboardPage'));
+ * console.log(tracer.tracePath('DashboardPage', 'signature[0].user'));
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SchemaDiff {
+  added: Record<string, string>;
+  removed: Record<string, string>;
+  changed: Record<string, { from: string; to: string }>;
+}
+
+export interface StageSnapshot {
+  stage: string;
+  timestamp: number;
+  data: {
+    signatureSchema?: Record<string, string>;
+    returnValueSchema?: Record<string, string>;
+    dependencySchemas?: Record<string, Record<string, any>>;
+    dataForMocks?: Record<string, any>;
+  };
+  diffFromPrevious?: {
+    signatureSchema?: SchemaDiff;
+    returnValueSchema?: SchemaDiff;
+    dependencySchemas?: Record<string, SchemaDiff>;
+  };
+}
+
+export interface Operation {
+  operation: string;
+  stage?: string;
+  path?: string;
+  before?: any;
+  after?: any;
+  context?: Record<string, any>;
+  timestamp?: number;
+}
+
+export interface EntityTrace {
+  entityName: string;
+  entityType: string;
+  filePath: string;
+  stages: StageSnapshot[];
+  operations: Operation[];
+}
+
+export interface TraceFile {
+  meta: {
+    timestamp: string;
+    projectSlug?: string;
+    entityCount: number;
+  };
+  summary: {
+    stageChangeCounts: Record<
+      string,
+      { added: number; removed: number; changed: number }
+    >;
+    entitiesWithMostChanges: string[];
+  };
+  entities: Record<string, EntityTrace>;
+}
+
+export interface CoarseSummary {
+  entityCount: number;
+  stageChangeCounts: Record<
+    string,
+    { added: number; removed: number; changed: number }
+  >;
+  entitiesWithMostChanges: Array<{ name: string; totalChanges: number }>;
+}
+
+export interface EntityStageSummary {
+  entityName: string;
+  stages: Array<{
+    stage: string;
+    diffFromPrevious?: {
+      signatureSchema?: SchemaDiff;
+      returnValueSchema?: SchemaDiff;
+    };
+  }>;
+}
+
+export interface PathHistory {
+  entityName: string;
+  path: string;
+  history: Array<{
+    stage?: string;
+    operation?: string;
+    value: any;
+    context?: Record<string, any>;
+  }>;
+}
+
+export interface TransformationTracerOptions {
+  enabled: boolean;
+  outputPath?: string;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Compute the diff between two schema objects.
+ */
+export function computeSchemaDiff(
+  before: Record<string, string> | undefined,
+  after: Record<string, string> | undefined,
+): SchemaDiff {
+  const diff: SchemaDiff = {
+    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: SchemaDiff): boolean {
+  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: SchemaDiff): number {
+  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 {
+  private enabled: boolean;
+  private outputPath: string;
+  private traces: Map<string, EntityTrace> = new Map();
+  private currentEntity: string | null = null;
+  private currentStage: string | null = null;
+  private projectSlug: string | undefined;
+  private tracerId: number;
+
+  constructor(options?: TransformationTracerOptions) {
+    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).
+   */
+  private log(message: string): void {
+    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(): boolean {
+    // 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(): void {
+    this.enabled = true;
+  }
+
+  /**
+   * Disable tracing.
+   */
+  disable(): void {
+    this.enabled = false;
+  }
+
+  /**
+   * Set the output path for the trace file.
+   */
+  setOutputPath(outputPath: string): void {
+    this.outputPath = outputPath;
+  }
+
+  /**
+   * Set the project slug for metadata.
+   */
+  setProjectSlug(slug: string): void {
+    this.projectSlug = slug;
+  }
+
+  /**
+   * Start tracing a new entity.
+   * If the entity already exists, preserves its existing stages and operations.
+   */
+  startEntity(entity: {
+    name: string;
+    entityType: string;
+    filePath: string;
+  }): void {
+    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: string,
+    stage: string,
+    data: StageSnapshot['data'],
+  ): void {
+    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: StageSnapshot = {
+      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: string, op: Omit<Operation, 'timestamp'>): void {
+    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(): void {
+    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: Record<
+      string,
+      { added: number; removed: number; changed: number }
+    > = {};
+    const entityChangeCounts: Map<string, number> = 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: 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(): void {
+    this.traces.clear();
+    this.currentEntity = null;
+    this.currentStage = null;
+  }
+
+  // ============================================================================
+  // Analysis Utilities
+  // ============================================================================
+
+  /**
+   * Load a trace from a file.
+   */
+  static loadTrace(tracePath: string): TransformationTracer {
+    const content = fs.readFileSync(tracePath, 'utf-8');
+    const traceFile: 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(): CoarseSummary {
+    const stageChangeCounts: Record<
+      string,
+      { added: number; removed: number; changed: number }
+    > = {};
+    const entityChangeCounts: Map<string, number> = 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: string): EntityStageSummary | null {
+    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: string, pathPattern?: RegExp): Operation[] {
+    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: string, targetPath: string): PathHistory {
+    const trace = this.traces.get(entityName);
+    const history: PathHistory['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: string): EntityTrace | undefined {
+    return this.traces.get(entityName);
+  }
+
+  /**
+   * Get all entity names in the trace.
+   */
+  getEntityNames(): string[] {
+    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: string,
+    propertyName: string,
+  ): Array<{
+    stage: string;
+    path: string;
+    type: string;
+    schemaType: 'signature' | 'returnValue' | 'dependency';
+  }> {
+    const trace = this.traces.get(entityName);
+    if (!trace) return [];
+
+    const results: Array<{
+      stage: string;
+      path: string;
+      type: string;
+      schemaType: 'signature' | 'returnValue' | 'dependency';
+    }> = [];
+    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 as Record<
+            string,
+            { returnValueSchema?: Record<string, string> }
+          >,
+        )) {
+          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: string): Array<{
+    propertyName: string;
+    paths: Array<{ path: string; type: string; stage: string }>;
+  }> {
+    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<
+      string,
+      Array<{ path: string; type: string }>
+    >();
+
+    const addToGroup = (path: string, type: string) => {
+      // 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 as Record<
+          string,
+          { returnValueSchema?: Record<string, string> }
+        >,
+      )) {
+        for (const [path, type] of Object.entries(
+          depData.returnValueSchema ?? {},
+        )) {
+          addToGroup(path, type);
+        }
+      }
+    }
+
+    // Find inconsistencies (same terminal pattern, different types)
+    const inconsistencies: Array<{
+      propertyName: string;
+      paths: Array<{ path: string; type: string; stage: string }>;
+    }> = [];
+
+    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: string,
+    fromStage: string,
+    toStage: string,
+  ): {
+    added: string[];
+    removed: string[];
+    typeChanged: Array<{ path: string; from: string; to: string }>;
+  } | null {
+    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: [] as string[],
+      removed: [] as string[],
+      typeChanged: [] as Array<{ path: string; from: string; to: string }>,
+    };
+
+    // 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<T extends Record<string, string>>(
+    entityName: string,
+    operationName: string,
+    schema: T,
+    transformFn: (schema: T) => void,
+    context?: Record<string, any>,
+  ): T {
+    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: string,
+    operationName: string,
+    before: Record<string, string>,
+    after: Record<string, string>,
+    context?: Record<string, any>,
+  ): void {
+    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: string,
+    operationName: string,
+    dependencySchemas: Record<
+      string,
+      Record<
+        string,
+        {
+          signatureSchema?: Record<string, string>;
+          returnValueSchema?: Record<string, string>;
+        }
+      >
+    >,
+    transformFn: (schema: Record<string, string>) => void,
+    schemaType: 'signature' | 'returnValue' | 'both' = 'both',
+  ): void {
+    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: string,
+    operationName: string,
+    dependencySchemas: Record<
+      string,
+      Record<
+        string,
+        {
+          signatureSchema?: Record<string, string>;
+          returnValueSchema?: Record<string, string>;
+        }
+      >
+    >,
+    transformFn: () => void,
+  ): void {
+    if (!this.enabled) {
+      transformFn();
+      return;
+    }
+
+    // Capture before state (deep copy of all schemas)
+    const beforeState: Record<
+      string,
+      Record<
+        string,
+        { sig: Record<string, string>; rv: Record<string, string> }
+      >
+    > = {};
+    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(): boolean {
+  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;