@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

package/analyzer-template/packages/ai/src/lib/dataStructure/helpers/DebugTracer.ts

@@ -0,0 +1,224 @@
+/**
+ * DebugTracer
+ *
+ * Structured debug/trace system for ScopeDataStructure analysis.
+ * Enables selective tracing of specific paths or scopes without code changes.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const tracer = new DebugTracer({
+ *   enabled: true,
+ *   pathPatterns: [/user\.id/, /signature\[0\]/],
+ *   scopePatterns: [/MyComponent/],
+ *   maxDepth: 10,
+ * });
+ *
+ * // In code:
+ * tracer.trace('addToSchema', { path, value, scope: scopeNode.name });
+ * tracer.traceEnter('followEquivalencies', { path, subPath });
+ * // ... do work ...
+ * tracer.traceExit('followEquivalencies', { propagated: true });
+ * ```
+ *
+ * ## Trace Output
+ *
+ * When enabled, produces structured output like:
+ * ```
+ * [TRACE] addToSchema { path: "user.id", value: "string", scope: "MyComponent" }
+ * [ENTER] followEquivalencies { path: "user.id", subPath: "user" }
+ * [EXIT]  followEquivalencies { propagated: true }
+ * ```
+ */
+
+export interface DebugTracerOptions {
+  /** Master switch - if false, all tracing is disabled */
+  enabled: boolean;
+
+  /** Regex patterns for paths to trace (empty = trace all paths) */
+  pathPatterns?: RegExp[];
+
+  /** Regex patterns for scopes to trace (empty = trace all scopes) */
+  scopePatterns?: RegExp[];
+
+  /** Maximum trace depth (prevents runaway output) */
+  maxDepth?: number;
+
+  /** Custom output function (defaults to console.info) */
+  output?: (message: string, data?: Record<string, unknown>) => void;
+
+  /** Include timestamps in output */
+  timestamps?: boolean;
+}
+
+export interface TraceContext {
+  path?: string;
+  scope?: string;
+  [key: string]: unknown;
+}
+
+export class DebugTracer {
+  private enabled: boolean;
+  private pathPatterns: RegExp[];
+  private scopePatterns: RegExp[];
+  private maxDepth: number;
+  private output: (message: string, data?: Record<string, unknown>) => void;
+  private timestamps: boolean;
+  private depth = 0;
+  private traceCount = 0;
+
+  constructor(options: DebugTracerOptions) {
+    this.enabled = options.enabled;
+    this.pathPatterns = options.pathPatterns ?? [];
+    this.scopePatterns = options.scopePatterns ?? [];
+    this.maxDepth = options.maxDepth ?? 50;
+    this.output = options.output ?? this.defaultOutput;
+    this.timestamps = options.timestamps ?? false;
+  }
+
+  /**
+   * Check if tracing should happen for this context.
+   */
+  private shouldTrace(context: TraceContext): boolean {
+    if (!this.enabled) return false;
+    if (this.depth >= this.maxDepth) return false;
+
+    // If no patterns specified, trace everything
+    if (this.pathPatterns.length === 0 && this.scopePatterns.length === 0) {
+      return true;
+    }
+
+    // Check path patterns
+    if (context.path && this.pathPatterns.length > 0) {
+      if (this.pathPatterns.some((p) => p.test(context.path!))) {
+        return true;
+      }
+    }
+
+    // Check scope patterns
+    if (context.scope && this.scopePatterns.length > 0) {
+      if (this.scopePatterns.some((p) => p.test(context.scope!))) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Default output to console with formatting.
+   */
+  private defaultOutput = (
+    message: string,
+    data?: Record<string, unknown>,
+  ): void => {
+    const indent = '  '.repeat(this.depth);
+    const timestamp = this.timestamps ? `[${Date.now()}] ` : '';
+    if (data) {
+      console.info(`${timestamp}${indent}${message}`, JSON.stringify(data));
+    } else {
+      console.info(`${timestamp}${indent}${message}`);
+    }
+  };
+
+  /**
+   * Simple trace point - logs a message with context.
+   */
+  trace(label: string, context: TraceContext = {}): void {
+    if (!this.shouldTrace(context)) return;
+    this.traceCount++;
+    this.output(`[TRACE] ${label}`, context as Record<string, unknown>);
+  }
+
+  /**
+   * Trace entering a function/block - increases depth.
+   */
+  traceEnter(label: string, context: TraceContext = {}): void {
+    if (!this.shouldTrace(context)) return;
+    this.traceCount++;
+    this.output(`[ENTER] ${label}`, context as Record<string, unknown>);
+    this.depth++;
+  }
+
+  /**
+   * Trace exiting a function/block - decreases depth.
+   */
+  traceExit(label: string, context: TraceContext = {}): void {
+    if (this.depth > 0) this.depth--;
+    if (!this.shouldTrace(context)) return;
+    this.output(`[EXIT]  ${label}`, context as Record<string, unknown>);
+  }
+
+  /**
+   * Trace a warning condition.
+   */
+  traceWarn(label: string, context: TraceContext = {}): void {
+    if (!this.shouldTrace(context)) return;
+    this.traceCount++;
+    this.output(`[WARN]  ${label}`, context as Record<string, unknown>);
+  }
+
+  /**
+   * Enable tracing dynamically.
+   */
+  enable(): void {
+    this.enabled = true;
+  }
+
+  /**
+   * Disable tracing dynamically.
+   */
+  disable(): void {
+    this.enabled = false;
+  }
+
+  /**
+   * Reset depth counter (useful after errors).
+   */
+  resetDepth(): void {
+    this.depth = 0;
+  }
+
+  /**
+   * Get trace statistics.
+   */
+  getStats(): { traceCount: number; currentDepth: number; enabled: boolean } {
+    return {
+      traceCount: this.traceCount,
+      currentDepth: this.depth,
+      enabled: this.enabled,
+    };
+  }
+
+  /**
+   * Reset all statistics.
+   */
+  reset(): void {
+    this.depth = 0;
+    this.traceCount = 0;
+  }
+}
+
+/**
+ * Default disabled tracer instance.
+ * Use this when you want tracing infrastructure but disabled by default.
+ */
+export const defaultTracer = new DebugTracer({ enabled: false });
+
+/**
+ * Create a tracer that captures output to an array (for testing).
+ */
+export function createTestTracer(options: Partial<DebugTracerOptions> = {}): {
+  tracer: DebugTracer;
+  output: string[];
+} {
+  const output: string[] = [];
+  const tracer = new DebugTracer({
+    enabled: true,
+    ...options,
+    output: (message, data) => {
+      output.push(data ? `${message} ${JSON.stringify(data)}` : message);
+    },
+  });
+  return { tracer, output };
+}

package/analyzer-template/packages/ai/src/lib/dataStructure/helpers/PathManager.ts

@@ -0,0 +1,203 @@
+/**
+ * PathManager
+ *
+ * Centralized utility for schema path manipulation with built-in caching.
+ * Handles splitting, joining, and validating schema paths used throughout
+ * the ScopeDataStructure analysis.
+ *
+ * ## Context in the Analysis Pipeline
+ *
+ * Schema paths are dot-separated strings representing data access patterns:
+ * - `signature[0].user.id` - First argument's user.id property
+ * - `items[].name` - name property of array elements
+ * - `functionCallReturnValue(fetch).data` - Return value from fetch() call
+ *
+ * These paths are created during AST analysis and used extensively in:
+ * 1. **Equivalency tracking** - Linking data flow between scopes
+ * 2. **Schema building** - Determining the shape of function inputs/outputs
+ * 3. **Database queries** - Finding source/usage relationships
+ *
+ * ## Performance Notes
+ *
+ * Path operations are called thousands of times per analysis. Caching
+ * provides ~10x speedup for repeated operations on the same paths.
+ *
+ * ## Related Modules
+ *
+ * - `splitOutsideParentheses.ts` - Low-level split/join with parentheses awareness
+ * - `cleanPath.ts` - Normalizes paths by removing noise
+ * - `uniqueIdUtils.ts` - Creates unique keys from scope+path combinations
+ */
+
+import {
+  joinParenthesesAndArrays,
+  splitOutsideParenthesesAndArrays,
+} from '../../splitOutsideParentheses';
+import cleanOutBoundary from '../../cleanOutBoundary';
+
+export class PathManager {
+  private pathPartsCache: Map<string, string[]> = new Map();
+  private pathJoinCache: Map<string, string> = new Map();
+  private isValidPathCache: Map<string, boolean> = new Map();
+  private stripGenericsCache: Map<string, string> = new Map();
+
+  /**
+   * Splits a schema path into its component parts.
+   * Results are cached for performance.
+   *
+   * IMPORTANT: The returned array must NOT be mutated by callers.
+   * This allows us to return the cached array directly without cloning,
+   * providing significant performance gains (structuredClone is expensive).
+   *
+   * @example
+   * splitPath('user.profile.name') // ['user', 'profile', 'name']
+   * splitPath('items[].id') // ['items[]', 'id']
+   */
+  splitPath(path: string): readonly string[] {
+    const cached = this.pathPartsCache.get(path);
+    if (cached) {
+      return cached;
+    }
+    const pathParts = splitOutsideParenthesesAndArrays(path);
+    this.pathPartsCache.set(path, pathParts);
+    return pathParts;
+  }
+
+  /**
+   * Joins path parts back into a schema path string.
+   * Results are cached for performance.
+   *
+   * @example
+   * joinPathParts(['user', 'profile', 'name']) // 'user.profile.name'
+   */
+  joinPathParts(pathParts: readonly string[]): string {
+    const cacheKey = pathParts.join('|');
+    if (this.pathJoinCache.has(cacheKey)) {
+      return this.pathJoinCache.get(cacheKey)!;
+    }
+    const result = joinParenthesesAndArrays(pathParts as string[]);
+    this.pathJoinCache.set(cacheKey, result);
+    return result;
+  }
+
+  /**
+   * Validates whether a string is a valid schema path.
+   * Results are cached for performance since this is called very frequently.
+   * Rejects:
+   * - Non-strings
+   * - Empty strings
+   * - Boolean literals ('true', 'false')
+   * - Numeric strings
+   * - Quoted strings (starting with ' or ")
+   * - Paths containing whitespace outside of brackets
+   */
+  isValidPath(path: string): boolean {
+    // Quick type checks (not cacheable)
+    if (typeof path !== 'string' || !path) {
+      return false;
+    }
+
+    // Check cache first
+    if (this.isValidPathCache.has(path)) {
+      return this.isValidPathCache.get(path)!;
+    }
+
+    // Compute validity
+    let result = true;
+
+    if (path === 'true' || path === 'false') {
+      result = false;
+    } else if (!isNaN(Number(path))) {
+      result = false;
+    } else if (path.charCodeAt(0) === 39 || path.charCodeAt(0) === 34) {
+      // Check for ' (39) or " (34) at start - faster than regex
+      result = false;
+    } else {
+      // Check for whitespace in path parts
+      result = this.splitPath(path).every((part) => {
+        const cleaned = cleanOutBoundary(
+          cleanOutBoundary(cleanOutBoundary(part, '<', '>'), '[', ']'),
+        );
+        // Use indexOf instead of regex for speed
+        return (
+          cleaned.indexOf(' ') === -1 &&
+          cleaned.indexOf('\t') === -1 &&
+          cleaned.indexOf('\n') === -1
+        );
+      });
+    }
+
+    this.isValidPathCache.set(path, result);
+    return result;
+  }
+
+  /**
+   * Strips generic type parameters from a name.
+   * Cached for performance since this is called frequently.
+   *
+   * @example
+   * stripGenerics('MyComponent<Props>') // 'MyComponent'
+   * stripGenerics('Array<T>') // 'Array'
+   * stripGenerics('Simple') // 'Simple'
+   */
+  stripGenerics(name: string): string {
+    if (this.stripGenericsCache.has(name)) {
+      return this.stripGenericsCache.get(name)!;
+    }
+
+    // Find position of '<' - if not found, return original
+    const ltIndex = name.indexOf('<');
+    const result = ltIndex === -1 ? name : name.slice(0, ltIndex);
+
+    this.stripGenericsCache.set(name, result);
+    return result;
+  }
+
+  /**
+   * Clears all caches. Useful for testing or memory management.
+   */
+  clearCache(): void {
+    this.pathPartsCache.clear();
+    this.pathJoinCache.clear();
+    this.isValidPathCache.clear();
+    this.stripGenericsCache.clear();
+  }
+
+  /**
+   * Returns cache statistics for debugging/monitoring.
+   */
+  getCacheStats(): {
+    pathParts: number;
+    pathJoin: number;
+    isValidPath: number;
+    stripGenerics: number;
+  } {
+    return {
+      pathParts: this.pathPartsCache.size,
+      pathJoin: this.pathJoinCache.size,
+      isValidPath: this.isValidPathCache.size,
+      stripGenerics: this.stripGenericsCache.size,
+    };
+  }
+}
+
+// Default instance for simple use cases
+export const defaultPathManager = new PathManager();
+
+// Convenience functions that use the default instance
+// These can be used when a shared cache is acceptable
+export function splitPath(path: string): readonly string[] {
+  return defaultPathManager.splitPath(path);
+}
+
+export function joinPathParts(pathParts: readonly string[]): string {
+  return defaultPathManager.joinPathParts(pathParts);
+}
+
+export function isValidPath(path: string): boolean {
+  return defaultPathManager.isValidPath(path);
+}
+
+export function stripGenerics(name: string): string {
+  return defaultPathManager.stripGenerics(name);
+}