@flisk/analyze-tracking 0.7.6 → 0.8.1

package/src/analyze/python/pythonTrackingAnalyzer.py

@@ -53,6 +53,14 @@ ARRAY_TYPES = {'List', 'Tuple', 'Set', 'list', 'tuple', 'set'}
 # Container types that map to objects
 OBJECT_TYPES = {'Dict', 'dict'}
 
+def _safe_id(node: ast.AST) -> Optional[str]:
+    """Return the .id attribute of a node if present."""
+    return getattr(node, 'id', None)
+
+# -------------------------------------------
+# Tracking Visitor
+# -------------------------------------------
+
 class TrackingVisitor(ast.NodeVisitor):
     """
     AST visitor that identifies and extracts analytics tracking calls from Python code.
@@ -68,16 +76,16 @@ class TrackingVisitor(ast.NodeVisitor):
         function_stack: Stack of function contexts for nested functions
         var_types: Dictionary of variable types in the current scope
         var_types_stack: Stack of variable type scopes
-        custom_function: Optional name of a custom tracking function
+        custom_config: Optional custom configuration for custom tracking functions
     """
     
-    def __init__(self, filepath: str, custom_function: Optional[str] = None):
+    def __init__(self, filepath: str, custom_config: Optional[Dict[str, Any]] = None):
         """
         Initialize the tracking visitor.
         
         Args:
             filepath: Path to the Python file being analyzed
-            custom_function: Optional name of a custom tracking function to detect
+            custom_config: Optional custom configuration for custom tracking functions
         """
         self.events: List[AnalyticsEvent] = []
         self.filepath = filepath
@@ -85,7 +93,18 @@ class TrackingVisitor(ast.NodeVisitor):
         self.function_stack: List[str] = []
         self.var_types: Dict[str, PropertyType] = {}
         self.var_types_stack: List[Dict[str, PropertyType]] = []
-        self.custom_function = custom_function
+        self.custom_config = custom_config or None
+        # Store convenience attributes if config provided
+        if self.custom_config:
+            self._custom_fn_name: str = self.custom_config.get('functionName', '')
+            self._event_idx: int = self.custom_config.get('eventIndex', 0)
+            self._props_idx: int = self.custom_config.get('propertiesIndex', 1)
+            self._extra_params = self.custom_config.get('extraParams', [])
+        else:
+            self._custom_fn_name = None
+            self._event_idx = 0
+            self._props_idx = 1
+            self._extra_params = []
         
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         """
@@ -164,8 +183,11 @@ class TrackingVisitor(ast.NodeVisitor):
             
         elif isinstance(annotation, ast.Subscript):
             # Handle generic types like List[int], Dict[str, int]
-            if hasattr(annotation.value, 'id'):
-                container_type = annotation.value.id
+            container_type = getattr(annotation.value, 'id', None)
+            if container_type is None and isinstance(annotation.value, ast.Attribute):
+                container_type = getattr(annotation.value, 'attr', None)
+
+            if container_type:
                 
                 if container_type in ARRAY_TYPES:
                     # Try to get the type parameter for arrays
@@ -272,11 +294,12 @@ class TrackingVisitor(ast.NodeVisitor):
     
     def _detect_method_call_source(self, node: ast.Call) -> Optional[str]:
         """Helper method to detect analytics source from method calls."""
-        if not hasattr(node.func.value, 'id'):
+        obj_val = getattr(node.func, 'value', None)
+        if obj_val is None:
             return None
             
-        obj_id = node.func.value.id
-        method_name = node.func.attr
+        obj_id = _safe_id(obj_val) or ''
+        method_name = getattr(node.func, 'attr', '')
         
         # Check standard analytics libraries
         for source, config in ANALYTICS_SOURCES.items():
@@ -292,11 +315,17 @@ class TrackingVisitor(ast.NodeVisitor):
         if method_name == 'track' and self._is_snowplow_tracker_call(node):
             return 'snowplow'
         
+        # Handle dot-separated custom function names like CustomModule.track
+        if self._custom_fn_name and '.' in self._custom_fn_name:
+            full_name = f"{obj_id}.{method_name}"
+            if full_name == self._custom_fn_name:
+                return 'custom'
+        
         return None
     
     def _detect_function_call_source(self, node: ast.Call) -> Optional[str]:
         """Helper method to detect analytics source from direct function calls."""
-        func_name = node.func.id
+        func_name = _safe_id(node.func) or ''
         
         # Check for Snowplow direct functions
         if func_name in ['trackStructEvent', 'buildStructEvent']:
@@ -307,7 +336,7 @@ class TrackingVisitor(ast.NodeVisitor):
             return 'snowplow'
         
         # Check for custom tracking function
-        if self.custom_function and func_name == self.custom_function:
+        if self._custom_fn_name and func_name == self._custom_fn_name:
             return 'custom'
         
         return None
@@ -319,7 +348,7 @@ class TrackingVisitor(ast.NodeVisitor):
             
         first_arg = node.args[0]
         if isinstance(first_arg, ast.Call) and isinstance(first_arg.func, ast.Name):
-            return first_arg.func.id == 'BaseEvent'
+            return _safe_id(first_arg.func) == 'BaseEvent'
         return False
     
     def _is_snowplow_tracker_call(self, node: ast.Call) -> bool:
@@ -330,7 +359,7 @@ class TrackingVisitor(ast.NodeVisitor):
         first_arg = node.args[0]
         # Check if first argument is StructuredEvent
         if isinstance(first_arg, ast.Call) and isinstance(first_arg.func, ast.Name):
-            return first_arg.func.id == 'StructuredEvent'
+            return _safe_id(first_arg.func) == 'StructuredEvent'
         
         # Also check if it might be a variable (simple heuristic)
         if isinstance(first_arg, ast.Name) and hasattr(node.func, 'value'):
@@ -418,7 +447,7 @@ class TrackingVisitor(ast.NodeVisitor):
         if len(node.args) >= 1:
             first_arg = node.args[0]
             if isinstance(first_arg, ast.Call) and isinstance(first_arg.func, ast.Name):
-                if first_arg.func.id == 'StructuredEvent':
+                if _safe_id(first_arg.func) == 'StructuredEvent':
                     # Look for action in keyword arguments
                     for keyword in first_arg.keywords:
                         if keyword.arg == 'action' and isinstance(keyword.value, ast.Constant):
@@ -430,9 +459,15 @@ class TrackingVisitor(ast.NodeVisitor):
     
     def _extract_custom_event_name(self, node: ast.Call) -> Optional[str]:
         """Extract event name for custom tracking function."""
-        # Standard format: customFunction('event_name', {...})
-        if len(node.args) >= 1 and isinstance(node.args[0], ast.Constant):
-            return node.args[0].value
+        args = node.args
+
+        # Use configured index if available
+        if len(args) > self._event_idx and isinstance(args[self._event_idx], ast.Constant):
+            return args[self._event_idx].value
+
+        # Fallback heuristics
+        if len(args) >= 1 and isinstance(args[0], ast.Constant):
+            return args[0].value
         return None
     
     def extract_properties(self, node: ast.Call, source: str) -> EventProperties:
@@ -502,6 +537,19 @@ class TrackingVisitor(ast.NodeVisitor):
             # Check if event is not anonymous and extract distinct_id
             user_id_props.update(self._extract_posthog_user_id(node))
             
+        elif source == 'custom':
+            # Populate extra params defined in custom config as properties
+            if self._extra_params:
+                for extra in self._extra_params:
+                    idx = extra.get('idx')
+                    name = extra.get('name')
+                    if idx is None or name is None:
+                        continue
+                    if idx < len(node.args):
+                        prop_type = self._extract_property_type(node.args[idx])
+                        if prop_type:
+                            user_id_props[name] = prop_type
+            
         return user_id_props
     
     def _is_non_null_value(self, node: ast.AST) -> bool:
@@ -559,10 +607,13 @@ class TrackingVisitor(ast.NodeVisitor):
                         return keyword.value
                         
         elif source == 'custom':
-            # Properties are in the second argument
-            if len(node.args) > 1:
+            # Use configured indices where possible
+            if len(node.args) > self._props_idx and isinstance(node.args[self._props_idx], ast.Dict):
+                return node.args[self._props_idx]
+            # Fallbacks (legacy)
+            if len(node.args) >= 2 and isinstance(node.args[1], ast.Dict):
                 return node.args[1]
-                
+            
         elif source == 'posthog':
             # Check named parameters first, then positional
             for keyword in node.keywords:
@@ -576,7 +627,7 @@ class TrackingVisitor(ast.NodeVisitor):
             if len(node.args) >= 1:
                 first_arg = node.args[0]
                 if isinstance(first_arg, ast.Call) and isinstance(first_arg.func, ast.Name):
-                    if first_arg.func.id == 'StructuredEvent':
+                    if _safe_id(first_arg.func) == 'StructuredEvent':
                         # Return None as properties are handled differently for Snowplow
                         return None
                         
@@ -618,7 +669,7 @@ class TrackingVisitor(ast.NodeVisitor):
         if len(node.args) >= 1:
             first_arg = node.args[0]
             if isinstance(first_arg, ast.Call) and isinstance(first_arg.func, ast.Name):
-                if first_arg.func.id == 'StructuredEvent':
+                if _safe_id(first_arg.func) == 'StructuredEvent':
                     # Extract all keyword arguments except 'action'
                     for keyword in first_arg.keywords:
                         if keyword.arg and keyword.arg != 'action':
@@ -755,33 +806,56 @@ class TrackingVisitor(ast.NodeVisitor):
             return "null"
         return "any"
 
-def analyze_python_code(code: str, filepath: str, custom_function: Optional[str] = None) -> str:
+def analyze_python_code(code: str, filepath: str, custom_config: Optional[any] = None) -> str:
     """
     Analyze Python code for analytics tracking calls.
-    
-    This function parses Python code and identifies analytics tracking calls,
-    extracting event names, properties, and metadata.
-    
+
+    The function supports either a single custom configuration object or a list
+    of such objects, allowing detection of multiple custom tracking functions
+    without parsing the source code multiple times.
+
     Args:
         code: The Python source code to analyze
         filepath: Path to the file being analyzed
-        custom_function: Optional name of a custom tracking function
-        
+        custom_config: None, a single custom config dict, or a list of configs
+
     Returns:
         JSON string containing array of tracking events
     """
     try:
-        # Parse the Python code
+        # Parse the Python code only once
         tree = ast.parse(code)
-        
-        # Create visitor and analyze
-        visitor = TrackingVisitor(filepath, custom_function)
-        visitor.visit(tree)
-        
-        # Return events as JSON
-        return json.dumps(visitor.events)
-    except Exception as e:
-        # Return empty array on parse errors
+
+        events: List[AnalyticsEvent] = []
+
+        def run_visitor(cfg: Optional[dict]) -> None:
+            vis = TrackingVisitor(filepath, cfg)
+            vis.visit(tree)
+            events.extend(vis.events)
+
+        # Built-in providers pass (no custom config)
+        run_visitor(None)
+
+        # Handle list or single custom configuration
+        if custom_config:
+            if isinstance(custom_config, list):
+                for cfg in custom_config:
+                    if cfg:
+                        run_visitor(cfg)
+            else:
+                run_visitor(custom_config)  # single config for backward compat
+
+        # Deduplicate events (source|eventName|line|functionName)
+        unique: Dict[str, AnalyticsEvent] = {}
+        for evt in events:
+            key = f"{evt['source']}|{evt['eventName']}|{evt['line']}|{evt['functionName']}"
+            if key not in unique:
+                unique[key] = evt
+
+        return json.dumps(list(unique.values()))
+
+    except Exception:
+        # Return empty array on failure
         return json.dumps([])
 
 # Command-line interface

package/src/analyze/ruby/extractors.js

@@ -9,9 +9,10 @@ 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
+ * @param {Object} customConfig - Custom configuration for custom functions
  * @returns {string|null} - The extracted event name or null
  */
-function extractEventName(node, source) {
+function extractEventName(node, source, customConfig = null) {
   if (source === 'segment' || source === 'rudderstack') {
     // Both Segment and Rudderstack use the same format
     const params = node.arguments_?.arguments_?.[0]?.elements;
@@ -50,11 +51,21 @@ function extractEventName(node, source) {
   }
   
   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;
+    const args = node.arguments_?.arguments_ || [];
+
+    if (!customConfig) {
+      // Fallback: first argument string literal event name
+      if (args[0]?.unescaped?.value) {
+        return args[0].unescaped.value;
+      }
+      return null;
     }
+
+    const eventArg = args[customConfig.eventIndex];
+    if (eventArg?.unescaped?.value) {
+      return eventArg.unescaped.value;
+    }
+    return null;
   }
 
   return null;
@@ -64,9 +75,10 @@ function extractEventName(node, source) {
  * Extracts properties from a tracking call based on the source
  * @param {Object} node - The AST CallNode
  * @param {string} source - The detected analytics source
+ * @param {Object} customConfig - Custom configuration for custom functions
  * @returns {Object|null} - The extracted properties or null
  */
-async function extractProperties(node, source) {
+async function extractProperties(node, source, customConfig = null) {
   const { HashNode, ArrayNode } = await import('@ruby/prism');
 
   if (source === 'segment' || source === 'rudderstack') {
@@ -183,11 +195,35 @@ async function extractProperties(node, source) {
   }
   
   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]);
+    const args = node.arguments_?.arguments_ || [];
+
+    if (!customConfig) {
+      // Legacy fallback behavior
+      if (args.length > 1 && args[1] instanceof HashNode) {
+        return await extractHashProperties(args[1]);
+      }
+      return null;
     }
+
+    const properties = {};
+
+    // Handle extra params first
+    for (const extra of customConfig.extraParams) {
+      const argNode = args[extra.idx];
+      if (!argNode) continue;
+      properties[extra.name] = {
+        type: await getValueType(argNode)
+      };
+    }
+
+    // Handle properties object
+    const propsArg = args[customConfig.propertiesIndex];
+    if (propsArg instanceof HashNode) {
+      const hashProps = await extractHashProperties(propsArg);
+      Object.assign(properties, hashProps);
+    }
+
+    return Object.keys(properties).length > 0 ? properties : null;
   }
 
   return null;

package/src/analyze/ruby/index.js

@@ -16,7 +16,7 @@ let parse = null;
  * @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) {
+async function analyzeRubyFile(filePath, customFunctionSignatures = null) {
   // Lazy load the Ruby Prism parser
   if (!parse) {
     const { loadPrism } = await import('@ruby/prism');
@@ -26,21 +26,28 @@ async function analyzeRubyFile(filePath, customFunction) {
   try {
     // Read the file content
     const code = fs.readFileSync(filePath, 'utf8');
-    
-    // Parse the Ruby code into an AST
+
+    // Parse the Ruby code into an AST once
     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
+      return [];
     }
 
-    // Create a visitor and analyze the AST
-    const visitor = new TrackingVisitor(code, filePath, customFunction);
+    // Single visitor pass covering all custom configs
+    const visitor = new TrackingVisitor(code, filePath, customFunctionSignatures || []);
     const events = await visitor.analyze(ast);
 
-    return events;
+    // Deduplicate events
+    const unique = new Map();
+    for (const evt of events) {
+      const key = `${evt.source}|${evt.eventName}|${evt.line}|${evt.functionName}`;
+      if (!unique.has(key)) unique.set(key, evt);
+    }
+
+    return Array.from(unique.values());
 
   } catch (fileError) {
     console.error(`Error reading or processing file ${filePath}:`, fileError.message);

package/src/analyze/ruby/visitor.js

@@ -8,10 +8,10 @@ const { extractEventName, extractProperties } = require('./extractors');
 const { findWrappingFunction, traverseNode, getLineNumber } = require('./traversal');
 
 class TrackingVisitor {
-  constructor(code, filePath, customFunction = null) {
+  constructor(code, filePath, customConfigs = []) {
     this.code = code;
     this.filePath = filePath;
-    this.customFunction = customFunction;
+    this.customConfigs = Array.isArray(customConfigs) ? customConfigs : [];
     this.events = [];
   }
 
@@ -22,10 +22,27 @@ class TrackingVisitor {
    */
   async processCallNode(node, ancestors) {
     try {
-      const source = detectSource(node, this.customFunction);
+      let matchedConfig = null;
+      let source = null;
+
+      // Try to match any custom config first
+      for (const cfg of this.customConfigs) {
+        if (!cfg) continue;
+        if (detectSource(node, cfg.functionName) === 'custom') {
+          matchedConfig = cfg;
+          source = 'custom';
+          break;
+        }
+      }
+
+      // If no custom match, attempt built-in providers
+      if (!source) {
+        source = detectSource(node, null);
+      }
+
       if (!source) return;
 
-      const eventName = extractEventName(node, source);
+      const eventName = extractEventName(node, source, matchedConfig);
       if (!eventName) return;
 
       const line = getLineNumber(this.code, node.location);
@@ -33,13 +50,13 @@ class TrackingVisitor {
       // For module-scoped custom functions, use the custom function name as the functionName
       // For simple custom functions, use the wrapping function name
       let functionName;
-      if (source === 'custom' && this.customFunction && this.customFunction.includes('.')) {
-        functionName = this.customFunction;
+      if (source === 'custom' && matchedConfig && matchedConfig.functionName.includes('.')) {
+        functionName = matchedConfig.functionName;
       } else {
         functionName = await findWrappingFunction(node, ancestors);
       }
       
-      const properties = await extractProperties(node, source);
+      const properties = await extractProperties(node, source, matchedConfig);
 
       this.events.push({
         eventName,