@flisk/analyze-tracking 0.7.1 → 0.7.3

package/src/analyze/ruby/detectors.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Analytics source detection for Ruby tracking calls
+ * @module analyze/ruby/detectors
+ */
+
+/**
+ * Detects the analytics source from a Ruby AST CallNode
+ * @param {Object} node - The AST CallNode to analyze
+ * @param {string} customFunction - Optional custom function name to detect
+ * @returns {string|null} - The detected source or null
+ */
+function detectSource(node, customFunction = null) {
+  if (!node) return null;
+
+  // Check for analytics libraries
+  if (node.receiver) {
+    const objectName = node.receiver.name;
+    const methodName = node.name;
+
+    // Segment and Rudderstack (both use similar format)
+    // Analytics.track (Segment) or analytics.track (Rudderstack)
+    if ((objectName === 'Analytics' || objectName === 'analytics') && methodName === 'track') {
+      // Try to determine if it's Rudderstack based on context
+      // For now, we'll treat lowercase 'analytics' as Rudderstack
+      return objectName === 'analytics' ? 'rudderstack' : 'segment';
+    }
+    
+    // Mixpanel (Ruby SDK uses Mixpanel::Tracker instance)
+    if (methodName === 'track' && objectName === 'tracker') return 'mixpanel';
+    
+    // PostHog
+    if (objectName === 'posthog' && methodName === 'capture') return 'posthog';
+  }
+  
+  // Snowplow (typically tracker.track_struct_event)
+  if (node.name === 'track_struct_event') return 'snowplow';
+  
+  // Custom tracking function
+  if (customFunction && node.name === customFunction) return 'custom';
+
+  return null;
+}
+
+module.exports = {
+  detectSource
+};

package/src/analyze/ruby/extractors.js

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Event and property extraction utilities for Ruby analytics
+ * @module analyze/ruby/extractors
+ */
+
+const { getValueType } = require('./types');
+
+/**
+ * Extracts the event name from a tracking call based on the source
+ * @param {Object} node - The AST CallNode
+ * @param {string} source - The detected analytics source
+ * @returns {string|null} - The extracted event name or null
+ */
+function extractEventName(node, source) {
+  if (source === 'segment' || source === 'rudderstack') {
+    // Both Segment and Rudderstack use the same format
+    const params = node.arguments_.arguments_[0].elements;
+    const eventProperty = params.find(param => param?.key?.unescaped?.value === 'event');
+    return eventProperty?.value?.unescaped?.value || null;
+  }
+
+  if (source === 'mixpanel') {
+    // Mixpanel Ruby SDK format: tracker.track('distinct_id', 'event_name', {...})
+    const args = node.arguments_.arguments_;
+    if (args && args.length > 1 && args[1]?.unescaped?.value) {
+      return args[1].unescaped.value;
+    }
+  }
+
+  if (source === 'posthog') {
+    // PostHog Ruby SDK format: posthog.capture({distinct_id: '...', event: '...', properties: {...}})
+    const hashArg = node.arguments_.arguments_[0];
+    if (hashArg && hashArg.elements) {
+      const eventProperty = hashArg.elements.find(elem => elem?.key?.unescaped?.value === 'event');
+      return eventProperty?.value?.unescaped?.value || null;
+    }
+  }
+
+  if (source === 'snowplow') {
+    // Snowplow Ruby SDK: tracker.track_struct_event(category: '...', action: '...', ...)
+    const params = node.arguments_.arguments_[0].elements;
+    const actionProperty = params.find(param => param?.key?.unescaped?.value === 'action');
+    return actionProperty?.value?.unescaped?.value || null;
+  }
+  
+  if (source === 'custom') {
+    // Custom function format: customFunction('event_name', {...})
+    const args = node.arguments_.arguments_;
+    if (args && args.length > 0 && args[0]?.unescaped?.value) {
+      return args[0].unescaped.value;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extracts properties from a tracking call based on the source
+ * @param {Object} node - The AST CallNode
+ * @param {string} source - The detected analytics source
+ * @returns {Object|null} - The extracted properties or null
+ */
+async function extractProperties(node, source) {
+  const { HashNode, ArrayNode } = await import('@ruby/prism');
+
+  if (source === 'segment' || source === 'rudderstack') {
+    // Both Segment and Rudderstack use the same format
+    const params = node.arguments_.arguments_[0].elements;
+    const properties = {};
+
+    // Process all top-level fields except 'event'
+    for (const param of params) {
+      const key = param?.key?.unescaped?.value;
+      
+      if (key && key !== 'event') {
+        const value = param?.value;
+
+        if (key === 'properties' && value instanceof HashNode) {
+          // Merge properties from the 'properties' hash into the top level
+          const nestedProperties = await extractHashProperties(value);
+          Object.assign(properties, nestedProperties);
+        } else if (value instanceof HashNode) {
+          // Handle other nested hash objects
+          const hashProperties = await extractHashProperties(value);
+          properties[key] = {
+            type: 'object',
+            properties: hashProperties
+          };
+        } else if (value instanceof ArrayNode) {
+          // Handle arrays
+          const arrayItems = await extractArrayItemProperties(value);
+          properties[key] = {
+            type: 'array',
+            items: arrayItems
+          };
+        } else {
+          // Handle primitive values
+          const valueType = await getValueType(value);
+          properties[key] = {
+            type: valueType
+          };
+        }
+      }
+    }
+
+    return properties;
+  }
+
+  if (source === 'mixpanel') {
+    // Mixpanel Ruby SDK: tracker.track('distinct_id', 'event_name', {properties})
+    const args = node.arguments_.arguments_;
+    const properties = {};
+    
+    // Add distinct_id as property (even if it's a variable)
+    if (args && args.length > 0) {
+      properties.distinct_id = {
+        type: await getValueType(args[0])
+      };
+    }
+    
+    // Extract properties from third argument if it exists
+    if (args && args.length > 2 && args[2] instanceof HashNode) {
+      const propsHash = await extractHashProperties(args[2]);
+      Object.assign(properties, propsHash);
+    }
+    
+    return properties;
+  }
+
+  if (source === 'posthog') {
+    // PostHog Ruby SDK: posthog.capture({distinct_id: '...', event: '...', properties: {...}})
+    const hashArg = node.arguments_.arguments_[0];
+    const properties = {};
+    
+    if (hashArg && hashArg.elements) {
+      // Extract distinct_id if present
+      const distinctIdProperty = hashArg.elements.find(elem => elem?.key?.unescaped?.value === 'distinct_id');
+      if (distinctIdProperty?.value) {
+        properties.distinct_id = {
+          type: await getValueType(distinctIdProperty.value)
+        };
+      }
+      
+      // Extract properties
+      const propsProperty = hashArg.elements.find(elem => elem?.key?.unescaped?.value === 'properties');
+      if (propsProperty?.value instanceof HashNode) {
+        const props = await extractHashProperties(propsProperty.value);
+        Object.assign(properties, props);
+      }
+    }
+    
+    return properties;
+  }
+
+  if (source === 'snowplow') {
+    // Snowplow Ruby SDK: tracker.track_struct_event(category: '...', action: '...', ...)
+    const params = node.arguments_.arguments_[0].elements;
+    const properties = {};
+    
+    // Extract all struct event parameters except 'action' (which is used as the event name)
+    for (const param of params) {
+      const key = param?.key?.unescaped?.value;
+      if (key && key !== 'action') {
+        properties[key] = {
+          type: await getValueType(param.value)
+        };
+      }
+    }
+    
+    return properties;
+  }
+  
+  if (source === 'custom') {
+    // Custom function format: customFunction('event_name', {properties})
+    const args = node.arguments_.arguments_;
+    if (args && args.length > 1 && args[1] instanceof HashNode) {
+      return await extractHashProperties(args[1]);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extracts properties from a HashNode
+ * @param {Object} hashNode - The HashNode to extract properties from
+ * @returns {Object} - The extracted properties
+ */
+async function extractHashProperties(hashNode) {
+  const { AssocNode, HashNode, ArrayNode } = await import('@ruby/prism');
+  const properties = {};
+  
+  for (const element of hashNode.elements) {
+    if (element instanceof AssocNode) {
+      const key = element.key.unescaped?.value;
+      const value = element.value;
+
+      if (key) {
+        if (value instanceof HashNode) {
+          // Handle nested hash objects
+          const nestedProperties = await extractHashProperties(value);
+          properties[key] = {
+            type: 'object',
+            properties: nestedProperties
+          };
+        } else if (value instanceof ArrayNode) {
+          // Handle arrays
+          const items = await extractArrayItemProperties(value);
+          properties[key] = {
+            type: 'array',
+            items
+          };
+        } else {
+          // Handle primitive values
+          const valueType = await getValueType(value);
+          properties[key] = {
+            type: valueType
+          };
+        }
+      }
+    }
+  }
+
+  return properties;
+}
+
+/**
+ * Extracts property information from array items
+ * @param {Object} arrayNode - The ArrayNode to analyze
+ * @returns {Object} - Type information for array items
+ */
+async function extractArrayItemProperties(arrayNode) {
+  const { HashNode } = await import('@ruby/prism');
+
+  if (arrayNode.elements.length === 0) {
+    return { type: 'any' };
+  }
+
+  const firstItem = arrayNode.elements[0];
+  if (firstItem instanceof HashNode) {
+    return {
+      type: 'object',
+      properties: await extractHashProperties(firstItem)
+    };
+  } else {
+    const valueType = await getValueType(firstItem);
+    return {
+      type: valueType
+    };
+  }
+}
+
+module.exports = {
+  extractEventName,
+  extractProperties,
+  extractHashProperties,
+  extractArrayItemProperties
+};

package/src/analyze/ruby/index.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Ruby analytics tracking analyzer - main entry point
+ * @module analyze/ruby
+ */
+
+const fs = require('fs');
+const TrackingVisitor = require('./visitor');
+
+// Lazy-loaded parse function from Ruby Prism
+let parse = null;
+
+/**
+ * Analyzes a Ruby file for analytics tracking calls
+ * @param {string} filePath - Path to the Ruby file to analyze
+ * @param {string} customFunction - Optional custom tracking function name
+ * @returns {Promise<Array>} Array of tracking events found in the file
+ * @throws {Error} If the file cannot be read or parsed
+ */
+async function analyzeRubyFile(filePath, customFunction) {
+  // Lazy load the Ruby Prism parser
+  if (!parse) {
+    const { loadPrism } = await import('@ruby/prism');
+    parse = await loadPrism();
+  }
+
+  try {
+    // Read the file content
+    const code = fs.readFileSync(filePath, 'utf8');
+    
+    // Parse the Ruby code into an AST
+    let ast;
+    try {
+      ast = await parse(code);
+    } catch (parseError) {
+      console.error(`Error parsing file ${filePath}:`, parseError.message);
+      return []; // Return empty events array if parsing fails
+    }
+
+    // Create a visitor and analyze the AST
+    const visitor = new TrackingVisitor(code, filePath, customFunction);
+    const events = await visitor.analyze(ast);
+
+    return events;
+
+  } catch (fileError) {
+    console.error(`Error reading or processing file ${filePath}:`, fileError.message);
+    return [];
+  }
+}
+
+module.exports = { analyzeRubyFile };

package/src/analyze/ruby/traversal.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview AST traversal utilities for Ruby code analysis
+ * @module analyze/ruby/traversal
+ */
+
+/**
+ * Finds the wrapping function for a given node
+ * @param {Object} node - The current AST node
+ * @param {Array} ancestors - The ancestor nodes stack
+ * @returns {string} - The function name or 'global'/'block'
+ */
+async function findWrappingFunction(node, ancestors) {
+  const { DefNode, BlockNode, LambdaNode } = await import('@ruby/prism');
+
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+
+    // Handle method definitions
+    if (current instanceof DefNode) {
+      return current.name;
+    }
+
+    // Handle blocks and lambdas
+    if (current instanceof BlockNode || current instanceof LambdaNode) {
+      return 'block';
+    }
+  }
+  return 'global';
+}
+
+/**
+ * Recursively traverses the AST tree
+ * @param {Object} node - The current AST node
+ * @param {Function} nodeVisitor - Function to call for each node
+ * @param {Array} ancestors - The ancestor nodes stack
+ */
+async function traverseNode(node, nodeVisitor, ancestors = []) {
+  const { 
+    ProgramNode, 
+    StatementsNode, 
+    DefNode, 
+    IfNode, 
+    BlockNode, 
+    ArgumentsNode, 
+    HashNode, 
+    AssocNode, 
+    ClassNode, 
+    ModuleNode,
+    CallNode
+  } = await import('@ruby/prism');
+
+  if (!node) return;
+
+  ancestors.push(node);
+
+  // Call the visitor for this node
+  if (node instanceof CallNode) {
+    await nodeVisitor(node, ancestors);
+  }
+
+  // Visit all child nodes based on node type
+  if (node instanceof ProgramNode) {
+    await traverseNode(node.statements, nodeVisitor, ancestors);
+  } else if (node instanceof StatementsNode) {
+    for (const child of node.body) {
+      await traverseNode(child, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof ClassNode) {
+    if (node.body) {
+      await traverseNode(node.body, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof ModuleNode) {
+    if (node.body) {
+      await traverseNode(node.body, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof DefNode) {
+    if (node.body) {
+      await traverseNode(node.body, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof IfNode) {
+    if (node.statements) {
+      await traverseNode(node.statements, nodeVisitor, ancestors);
+    }
+    if (node.subsequent) {
+      await traverseNode(node.subsequent, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof BlockNode) {
+    if (node.body) {
+      await traverseNode(node.body, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof ArgumentsNode) {
+    for (const arg of node.arguments) {
+      await traverseNode(arg, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof HashNode) {
+    for (const element of node.elements) {
+      await traverseNode(element, nodeVisitor, ancestors);
+    }
+  } else if (node instanceof AssocNode) {
+    await traverseNode(node.key, nodeVisitor, ancestors);
+    await traverseNode(node.value, nodeVisitor, ancestors);
+  }
+
+  ancestors.pop();
+}
+
+/**
+ * Gets the line number for a given location in the code
+ * @param {string} code - The full source code
+ * @param {Object} location - The location object with startOffset
+ * @returns {number} - The line number (1-indexed)
+ */
+function getLineNumber(code, location) {
+  // Count the number of newlines before the start offset
+  const beforeStart = code.slice(0, location.startOffset);
+  return beforeStart.split('\n').length;
+}
+
+module.exports = {
+  findWrappingFunction,
+  traverseNode,
+  getLineNumber
+};

package/src/analyze/ruby/types.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Type definitions and constants for Ruby analytics analysis
+ * @module analyze/ruby/types
+ */
+
+async function getValueType(node) {
+  const { 
+    StringNode, 
+    IntegerNode, 
+    FloatNode, 
+    TrueNode, 
+    FalseNode, 
+    NilNode, 
+    SymbolNode, 
+    CallNode 
+  } = await import('@ruby/prism');
+
+  if (node instanceof StringNode) return 'string';
+  if (node instanceof IntegerNode || node instanceof FloatNode) return 'number';
+  if (node instanceof TrueNode || node instanceof FalseNode) return 'boolean';
+  if (node instanceof NilNode) return 'null';
+  if (node instanceof SymbolNode) return 'string';
+  if (node instanceof CallNode) return 'any'; // Dynamic values
+  
+  return 'any'; // Default type
+}
+
+module.exports = {
+  getValueType
+};

package/src/analyze/ruby/visitor.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview AST visitor for analyzing Ruby tracking events
+ * @module analyze/ruby/visitor
+ */
+
+const { detectSource } = require('./detectors');
+const { extractEventName, extractProperties } = require('./extractors');
+const { findWrappingFunction, traverseNode, getLineNumber } = require('./traversal');
+
+class TrackingVisitor {
+  constructor(code, filePath, customFunction = null) {
+    this.code = code;
+    this.filePath = filePath;
+    this.customFunction = customFunction;
+    this.events = [];
+  }
+
+  /**
+   * Processes a call node to extract tracking event information
+   * @param {Object} node - The CallNode to process
+   * @param {Array} ancestors - The ancestor nodes stack
+   */
+  async processCallNode(node, ancestors) {
+    try {
+      const source = detectSource(node, this.customFunction);
+      if (!source) return;
+
+      const eventName = extractEventName(node, source);
+      if (!eventName) return;
+
+      const line = getLineNumber(this.code, node.location);
+      const functionName = await findWrappingFunction(node, ancestors);
+      const properties = await extractProperties(node, source);
+
+      this.events.push({
+        eventName,
+        source,
+        properties,
+        filePath: this.filePath,
+        line,
+        functionName
+      });
+    } catch (nodeError) {
+      console.error(`Error processing node in ${this.filePath}:`, nodeError.message);
+    }
+  }
+
+  /**
+   * Analyzes the AST to find tracking events
+   * @param {Object} ast - The parsed AST
+   * @returns {Array} - Array of tracking events found
+   */
+  async analyze(ast) {
+    // Create a visitor function that will be called for each CallNode
+    const nodeVisitor = async (node, ancestors) => {
+      await this.processCallNode(node, ancestors);
+    };
+
+    // Traverse the AST starting from the program node
+    await traverseNode(ast.value, nodeVisitor);
+
+    return this.events;
+  }
+}
+
+module.exports = TrackingVisitor;

package/src/analyze/typescript/constants.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Constants and configurations for analytics tracking providers
+ * @module analyze/typescript/constants
+ */
+
+/**
+ * Analytics provider configurations
+ * @typedef {Object} ProviderConfig
+ * @property {string} name - Provider display name
+ * @property {string} objectName - Object name in JavaScript
+ * @property {string} methodName - Method name for tracking
+ * @property {string} type - Type of detection (member|function)
+ */
+
+/**
+ * Supported analytics providers and their detection patterns
+ * @type {Object.<string, ProviderConfig>}
+ */
+const ANALYTICS_PROVIDERS = {
+  SEGMENT: {
+    name: 'segment',
+    objectName: 'analytics',
+    methodName: 'track',
+    type: 'member'
+  },
+  MIXPANEL: {
+    name: 'mixpanel',
+    objectName: 'mixpanel',
+    methodName: 'track',
+    type: 'member'
+  },
+  AMPLITUDE: {
+    name: 'amplitude',
+    objectName: 'amplitude',
+    methodName: 'track',
+    type: 'member'
+  },
+  RUDDERSTACK: {
+    name: 'rudderstack',
+    objectName: 'rudderanalytics',
+    methodName: 'track',
+    type: 'member'
+  },
+  MPARTICLE: {
+    name: 'mparticle',
+    objectNames: ['mParticle', 'mparticle'],
+    methodName: 'logEvent',
+    type: 'member'
+  },
+  POSTHOG: {
+    name: 'posthog',
+    objectName: 'posthog',
+    methodName: 'capture',
+    type: 'member'
+  },
+  PENDO: {
+    name: 'pendo',
+    objectName: 'pendo',
+    methodName: 'track',
+    type: 'member'
+  },
+  HEAP: {
+    name: 'heap',
+    objectName: 'heap',
+    methodName: 'track',
+    type: 'member'
+  },
+  SNOWPLOW: {
+    name: 'snowplow',
+    objectName: 'tracker',
+    methodName: 'track',
+    type: 'member'
+  },
+  GOOGLE_ANALYTICS: {
+    name: 'googleanalytics',
+    functionName: 'gtag',
+    type: 'function'
+  }
+};
+
+/**
+ * TypeScript syntax kinds for node types we care about
+ * @enum {number}
+ */
+const TS_NODE_KINDS = {
+  CALL_EXPRESSION: 'CallExpression',
+  PROPERTY_ACCESS: 'PropertyAccessExpression',
+  IDENTIFIER: 'Identifier',
+  OBJECT_LITERAL: 'ObjectLiteralExpression',
+  ARRAY_LITERAL: 'ArrayLiteralExpression',
+  STRING_LITERAL: 'StringLiteral',
+  NUMERIC_LITERAL: 'NumericLiteral',
+  TRUE_KEYWORD: 'TrueKeyword',
+  FALSE_KEYWORD: 'FalseKeyword',
+  NULL_KEYWORD: 'NullKeyword',
+  UNDEFINED_KEYWORD: 'UndefinedKeyword',
+  FUNCTION_DECLARATION: 'FunctionDeclaration',
+  METHOD_DECLARATION: 'MethodDeclaration',
+  ARROW_FUNCTION: 'ArrowFunction',
+  VARIABLE_DECLARATION: 'VariableDeclaration',
+  PROPERTY_ASSIGNMENT: 'PropertyAssignment',
+  SHORTHAND_PROPERTY: 'ShorthandPropertyAssignment',
+  PARAMETER: 'Parameter'
+};
+
+module.exports = {
+  ANALYTICS_PROVIDERS,
+  TS_NODE_KINDS
+};