@flisk/analyze-tracking 0.7.5 → 0.8.0

package/src/analyze/javascript/index.js

@@ -11,16 +11,22 @@ const { parseFile, findTrackingEvents, FileReadError, ParseError } = require('./
  * @param {string} [customFunction] - Optional custom function name to detect
  * @returns {Array<Object>} Array of tracking events found in the file
  */
-function analyzeJsFile(filePath, customFunction) {
-  const events = [];
-
+function analyzeJsFile(filePath, customFunctionSignatures = null) {
   try {
-    // Parse the file into an AST
+    // Parse the file into an AST once
     const ast = parseFile(filePath);
 
-    // Find and extract tracking events
-    const foundEvents = findTrackingEvents(ast, filePath, customFunction);
-    events.push(...foundEvents);
+    // Single pass extraction covering built-in + all custom configs
+    const events = findTrackingEvents(ast, filePath, customFunctionSignatures || []);
+
+    // Deduplicate events (by source | eventName | line | functionName)
+    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 (error) {
     if (error instanceof FileReadError) {
@@ -32,7 +38,7 @@ function analyzeJsFile(filePath, customFunction) {
     }
   }
 
-  return events;
+  return [];
 }
 
 module.exports = { analyzeJsFile };

package/src/analyze/javascript/parser.js

@@ -66,22 +66,95 @@ function parseFile(filePath) {
   }
 }
 
+// ---------------------------------------------
+// Helper – custom function matcher
+// ---------------------------------------------
+
+/**
+ * Determines whether a CallExpression node matches the provided custom function name.
+ * Supports both simple identifiers (e.g. myTrack) and dot-separated members (e.g. Custom.track).
+ * The logic mirrors isCustomFunction from detectors/analytics-source.js but is kept local to avoid
+ * circular dependencies.
+ * @param {Object} node  – CallExpression AST node
+ * @param {string} fnName – Custom function name (could include dots)
+ * @returns {boolean}
+ */
+function nodeMatchesCustomFunction(node, fnName) {
+  if (!fnName || !node.callee) return false;
+
+  const parts = fnName.split('.');
+
+  // Simple identifier case
+  if (parts.length === 1) {
+    return node.callee.type === NODE_TYPES.IDENTIFIER && node.callee.name === fnName;
+  }
+
+  // Member expression chain case
+  if (node.callee.type !== NODE_TYPES.MEMBER_EXPRESSION) {
+    return false;
+  }
+
+  // Walk the chain from the right-most property to the leftmost object
+  let currentNode = node.callee;
+  let idx = parts.length - 1;
+
+  while (currentNode && idx >= 0) {
+    const expected = parts[idx];
+
+    if (currentNode.type === NODE_TYPES.MEMBER_EXPRESSION) {
+      if (
+        currentNode.property.type !== NODE_TYPES.IDENTIFIER ||
+        currentNode.property.name !== expected
+      ) {
+        return false;
+      }
+      currentNode = currentNode.object;
+      idx -= 1;
+    } else if (currentNode.type === NODE_TYPES.IDENTIFIER) {
+      return idx === 0 && currentNode.name === expected;
+    } else {
+      return false;
+    }
+  }
+
+  return false;
+}
+
 /**
- * Walks the AST and finds analytics tracking calls
- * @param {Object} ast - Parsed AST
- * @param {string} filePath - Path to the file being analyzed
- * @param {string} [customFunction] - Custom function name to detect
- * @returns {Array<Object>} Array of found events
+ * Walk the AST once and find tracking events for built-in providers plus any number of custom
+ * function configurations. This avoids the previous O(n * customConfigs) behaviour.
+ *
+ * @param {Object}  ast                      – Parsed AST of the source file
+ * @param {string}  filePath                 – Absolute/relative path to the source file
+ * @param {Object[]} [customConfigs=[]]      – Array of parsed custom function configurations
+ * @returns {Array<Object>}                  – List of extracted tracking events
  */
-function findTrackingEvents(ast, filePath, customFunction) {
+function findTrackingEvents(ast, filePath, customConfigs = []) {
   const events = [];
 
   walk.ancestor(ast, {
     [NODE_TYPES.CALL_EXPRESSION]: (node, ancestors) => {
       try {
-        const event = extractTrackingEvent(node, ancestors, filePath, customFunction);
-        if (event) {
-          events.push(event);
+        let matchedCustomConfig = null;
+
+        // Attempt to match any custom function first to avoid mis-classifying built-in providers
+        if (Array.isArray(customConfigs) && customConfigs.length > 0) {
+          for (const cfg of customConfigs) {
+            if (cfg && nodeMatchesCustomFunction(node, cfg.functionName)) {
+              matchedCustomConfig = cfg;
+              break;
+            }
+          }
+        }
+
+        if (matchedCustomConfig) {
+          // Force source to 'custom' and use matched config
+          const event = extractTrackingEvent(node, ancestors, filePath, matchedCustomConfig);
+          if (event) events.push(event);
+        } else {
+          // Let built-in detector figure out source (pass undefined customFunction)
+          const event = extractTrackingEvent(node, ancestors, filePath, null);
+          if (event) events.push(event);
         }
       } catch (error) {
         console.error(`Error processing node in ${filePath}:`, error.message);
@@ -97,25 +170,25 @@ function findTrackingEvents(ast, filePath, customFunction) {
  * @param {Object} node - CallExpression node
  * @param {Array<Object>} ancestors - Ancestor nodes
  * @param {string} filePath - File path
- * @param {string} [customFunction] - Custom function name
+ * @param {Object} [customConfig] - Custom function configuration object
  * @returns {Object|null} Extracted event or null
  */
-function extractTrackingEvent(node, ancestors, filePath, customFunction) {
+function extractTrackingEvent(node, ancestors, filePath, customConfig) {
   // Detect the analytics source
-  const source = detectAnalyticsSource(node, customFunction);
+  const source = detectAnalyticsSource(node, customConfig?.functionName);
   if (source === 'unknown') {
     return null;
   }
 
   // Extract event data based on the source
-  const eventData = extractEventData(node, source);
+  const eventData = extractEventData(node, source, customConfig);
 
   // Get location and context information
   const line = node.loc.start.line;
   const functionName = findWrappingFunction(node, ancestors);
 
   // Process the event data into final format
-  return processEventData(eventData, source, filePath, line, functionName);
+  return processEventData(eventData, source, filePath, line, functionName, customConfig);
 }
 
 module.exports = {

package/src/analyze/python/index.js

@@ -40,7 +40,7 @@ async function initPyodide() {
  * libraries, extracting event names, properties, and metadata.
  * 
  * @param {string} filePath - Path to the Python file to analyze
- * @param {string} [customFunction=null] - Name of a custom tracking function to detect
+ * @param {string} [customFunctionSignature=null] - Signature of a custom tracking function to detect
  * @returns {Promise<Array<Object>>} Array of tracking events found in the file
  * @returns {Promise<Array>} Empty array if an error occurs
  * 
@@ -52,48 +52,54 @@ async function initPyodide() {
  * // With custom tracking function
  * const events = await analyzePythonFile('./app.py', 'track_event');
  */
-async function analyzePythonFile(filePath, customFunction = null) {
+async function analyzePythonFile(filePath, customFunctionSignatures = null) {
   // Validate inputs
   if (!filePath || typeof filePath !== 'string') {
     console.error('Invalid file path provided');
     return [];
   }
 
-  try {
-    // Check if file exists before reading
-    if (!fs.existsSync(filePath)) {
-      console.error(`File not found: ${filePath}`);
-      return [];
-    }
+  // Check if file exists before reading
+  if (!fs.existsSync(filePath)) {
+    console.error(`File not found: ${filePath}`);
+    return [];
+  }
 
-    // Read the Python file
+  try {
+    // Read the Python file only once
     const code = fs.readFileSync(filePath, 'utf8');
-    
+
     // Initialize Pyodide if not already done
     const py = await initPyodide();
-    
-    // Load the Python analyzer code
+
+    // Load the Python analyzer code (idempotent – redefining functions is fine)
     const analyzerPath = path.join(__dirname, 'pythonTrackingAnalyzer.py');
     if (!fs.existsSync(analyzerPath)) {
       throw new Error(`Python analyzer not found at: ${analyzerPath}`);
     }
-    
     const analyzerCode = fs.readFileSync(analyzerPath, 'utf8');
-    
-    // Set up Python environment with necessary variables
-    py.globals.set('code', code);
-    py.globals.set('filepath', filePath);
-    py.globals.set('custom_function', customFunction);
-    // Set __name__ to null to prevent execution of main block
+    // Prevent the analyzer from executing any __main__ blocks that expect CLI usage
     py.globals.set('__name__', null);
-    
-    // Load and run the analyzer
     py.runPython(analyzerCode);
-    
-    // Execute the analysis and parse results
-    const result = py.runPython('analyze_python_code(code, filepath, custom_function)');
-    const events = JSON.parse(result);
-    
+
+    // Helper to run analysis with a given custom config (can be null)
+    const runAnalysis = (customConfig) => {
+      py.globals.set('code', code);
+      py.globals.set('filepath', filePath);
+      py.globals.set('custom_config_json', customConfig ? JSON.stringify(customConfig) : null);
+      py.runPython('import json');
+      py.runPython('custom_config = None if custom_config_json == None else json.loads(custom_config_json)');
+      const result = py.runPython('analyze_python_code(code, filepath, custom_config)');
+      return JSON.parse(result);
+    };
+
+    // Prepare config argument (array or null)
+    const configArg = Array.isArray(customFunctionSignatures) && customFunctionSignatures.length > 0
+      ? customFunctionSignatures
+      : null;
+
+    const events = runAnalysis(configArg);
+
     return events;
   } catch (error) {
     // Log detailed error information for debugging

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;