@flisk/analyze-tracking 0.7.6 → 0.8.0

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,

package/src/analyze/typescript/extractors/event-extractor.js

@@ -21,6 +21,7 @@ const EXTRACTION_STRATEGIES = {
   googleanalytics: extractGoogleAnalyticsEvent,
   snowplow: extractSnowplowEvent,
   mparticle: extractMparticleEvent,
+  custom: extractCustomEvent,
   default: extractDefaultEvent
 };
 
@@ -30,10 +31,14 @@ const EXTRACTION_STRATEGIES = {
  * @param {string} source - Analytics provider source
  * @param {Object} checker - TypeScript type checker
  * @param {Object} sourceFile - TypeScript source file
+ * @param {Object} customConfig - Custom configuration for custom extraction
  * @returns {EventData} Extracted event data
  */
-function extractEventData(node, source, checker, sourceFile) {
+function extractEventData(node, source, checker, sourceFile, customConfig) {
   const strategy = EXTRACTION_STRATEGIES[source] || EXTRACTION_STRATEGIES.default;
+  if (source === 'custom') {
+    return strategy(node, checker, sourceFile, customConfig);
+  }
   return strategy(node, checker, sourceFile);
 }
 
@@ -121,6 +126,32 @@ function extractMparticleEvent(node, checker, sourceFile) {
   return { eventName, propertiesNode };
 }
 
+/**
+ * Custom extraction
+ * @param {Object} node - CallExpression node
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} sourceFile - TypeScript source file
+ * @param {Object} customConfig - Custom configuration for custom extraction
+ * @returns {EventData}
+ */
+function extractCustomEvent(node, checker, sourceFile, customConfig) {
+  const args = node.arguments || [];
+
+  const eventArg = args[customConfig?.eventIndex ?? 0];
+  const propertiesArg = args[customConfig?.propertiesIndex ?? 1];
+
+  const eventName = getStringValue(eventArg, checker, sourceFile);
+
+  const extraArgs = {};
+  if (customConfig && customConfig.extraParams) {
+    customConfig.extraParams.forEach(extra => {
+      extraArgs[extra.name] = args[extra.idx];
+    });
+  }
+
+  return { eventName, propertiesNode: propertiesArg, extraArgs };
+}
+
 /**
  * Default event extraction for standard providers
  * @param {Object} node - CallExpression node
@@ -149,9 +180,10 @@ function extractDefaultEvent(node, checker, sourceFile) {
  * @param {string} functionName - Containing function name
  * @param {Object} checker - TypeScript type checker
  * @param {Object} sourceFile - TypeScript source file
+ * @param {Object} customConfig - Custom configuration for custom extraction
  * @returns {Object|null} Processed event object or null
  */
-function processEventData(eventData, source, filePath, line, functionName, checker, sourceFile) {
+function processEventData(eventData, source, filePath, line, functionName, checker, sourceFile, customConfig) {
   const { eventName, propertiesNode } = eventData;
 
   if (!eventName || !propertiesNode) {
@@ -184,6 +216,37 @@ function processEventData(eventData, source, filePath, line, functionName, check
   // Clean up any unresolved type markers
   const cleanedProperties = cleanupProperties(properties);
 
+  // Handle custom extra params
+  if (source === 'custom' && customConfig && eventData.extraArgs) {
+    for (const [paramName, argNode] of Object.entries(eventData.extraArgs)) {
+      if (argNode && ts.isObjectLiteralExpression(argNode)) {
+        // Extract detailed properties from object literal expression
+        cleanedProperties[paramName] = {
+          type: 'object',
+          properties: extractProperties(checker, argNode)
+        };
+      } else if (argNode && ts.isIdentifier(argNode)) {
+        // Handle identifier references to objects
+        const resolvedNode = resolveIdentifierToInitializer(checker, argNode, sourceFile);
+        if (resolvedNode && ts.isObjectLiteralExpression(resolvedNode)) {
+          cleanedProperties[paramName] = {
+            type: 'object',
+            properties: extractProperties(checker, resolvedNode)
+          };
+        } else {
+          cleanedProperties[paramName] = {
+            type: inferNodeValueType(argNode)
+          };
+        }
+      } else {
+        // For non-object arguments, use simple type inference
+        cleanedProperties[paramName] = {
+          type: inferNodeValueType(argNode)
+        };
+      }
+    }
+  }
+
   return {
     eventName,
     source,
@@ -368,6 +431,16 @@ function cleanupProperties(properties) {
   return cleaned;
 }
 
+function inferNodeValueType(node) {
+  if (!node) return 'any';
+  if (ts.isStringLiteral(node)) return 'string';
+  if (ts.isNumericLiteral(node)) return 'number';
+  if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) return 'boolean';
+  if (ts.isArrayLiteralExpression(node)) return 'array';
+  if (ts.isObjectLiteralExpression(node)) return 'object';
+  return 'any';
+}
+
 module.exports = {
   extractEventData,
   processEventData

package/src/analyze/typescript/index.js

@@ -9,16 +9,14 @@ const { getProgram, findTrackingEvents, ProgramError, SourceFileError } = requir
  * Analyzes a TypeScript file for analytics tracking calls
  * @param {string} filePath - Path to the TypeScript file to analyze
  * @param {Object} [program] - Optional existing TypeScript program to reuse
- * @param {string} [customFunction] - Optional custom function name to detect
+ * @param {string} [customFunctionSignature] - Optional custom function signature to detect
  * @returns {Array<Object>} Array of tracking events found in the file
  */
-function analyzeTsFile(filePath, program, customFunction) {
-  const events = [];
-
+function analyzeTsFile(filePath, program = null, customFunctionSignatures = null) {
   try {
-    // Get or create TypeScript program
+    // Get or create TypeScript program (only once)
     const tsProgram = getProgram(filePath, program);
-    
+
     // Get source file from program
     const sourceFile = tsProgram.getSourceFile(filePath);
     if (!sourceFile) {
@@ -28,9 +26,17 @@ function analyzeTsFile(filePath, program, customFunction) {
     // Get type checker
     const checker = tsProgram.getTypeChecker();
 
-    // Find and extract tracking events
-    const foundEvents = findTrackingEvents(sourceFile, checker, filePath, customFunction);
-    events.push(...foundEvents);
+    // Single-pass collection covering built-in + all custom configs
+    const events = findTrackingEvents(sourceFile, checker, filePath, customFunctionSignatures || []);
+
+    // 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 (error) {
     if (error instanceof ProgramError) {
@@ -42,7 +48,7 @@ function analyzeTsFile(filePath, program, customFunction) {
     }
   }
 
-  return events;
+  return [];
 }
 
 module.exports = { analyzeTsFile };

package/src/analyze/typescript/parser.js

@@ -65,32 +65,55 @@ function getProgram(filePath, existingProgram) {
  * @param {Object} sourceFile - TypeScript source file
  * @param {Object} checker - TypeScript type checker
  * @param {string} filePath - Path to the file being analyzed
- * @param {string} [customFunction] - Custom function name to detect
+ * @param {Array<Object>} [customConfigs] - Array of custom function configurations
  * @returns {Array<Object>} Array of found events
  */
-function findTrackingEvents(sourceFile, checker, filePath, customFunction) {
+function findTrackingEvents(sourceFile, checker, filePath, customConfigs = []) {
   const events = [];
 
   /**
-   * Visitor function for AST traversal
-   * @param {Object} node - Current AST node
+   * Helper to test if a CallExpression matches a custom function name.
+   * We simply rely on node.expression.getText() which preserves the fully qualified name.
    */
+  const matchesCustomFn = (callNode, fnName) => {
+    if (!fnName) return false;
+    try {
+      return callNode.expression && callNode.expression.getText() === fnName;
+    } catch {
+      return false;
+    }
+  };
+
   function visit(node) {
     try {
       if (ts.isCallExpression(node)) {
-        const event = extractTrackingEvent(node, sourceFile, checker, filePath, customFunction);
-        if (event) {
-          events.push(event);
+        let matchedCustom = null;
+
+        if (Array.isArray(customConfigs) && customConfigs.length > 0) {
+          for (const cfg of customConfigs) {
+            if (cfg && matchesCustomFn(node, cfg.functionName)) {
+              matchedCustom = cfg;
+              break;
+            }
+          }
         }
+
+        const event = extractTrackingEvent(
+          node,
+          sourceFile,
+          checker,
+          filePath,
+          matchedCustom /* may be null */
+        );
+        if (event) events.push(event);
       }
-      // Continue traversing the AST
+
       ts.forEachChild(node, visit);
     } catch (error) {
       console.error(`Error processing node in ${filePath}:`, error.message);
     }
   }
 
-  // Start traversal from the root
   ts.forEachChild(sourceFile, visit);
 
   return events;
@@ -102,25 +125,25 @@ function findTrackingEvents(sourceFile, checker, filePath, customFunction) {
  * @param {Object} sourceFile - TypeScript source file
  * @param {Object} checker - TypeScript type checker
  * @param {string} filePath - File path
- * @param {string} [customFunction] - Custom function name
+ * @param {Object} [customConfig] - Custom function configuration
  * @returns {Object|null} Extracted event or null
  */
-function extractTrackingEvent(node, sourceFile, checker, filePath, customFunction) {
+function extractTrackingEvent(node, sourceFile, checker, 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, checker, sourceFile);
+  const eventData = extractEventData(node, source, checker, sourceFile, customConfig);
 
   // Get location and context information
   const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
   const functionName = findWrappingFunction(node);
 
   // Process the event data into final format
-  return processEventData(eventData, source, filePath, line, functionName, checker, sourceFile);
+  return processEventData(eventData, source, filePath, line, functionName, checker, sourceFile, customConfig);
 }
 
 module.exports = {

package/src/analyze/utils/customFunctionParser.js

@@ -0,0 +1,55 @@
+// Create new file with parser implementation
+function parseCustomFunctionSignature(signature) {
+  if (!signature || typeof signature !== 'string') {
+    return null;
+  }
+
+  // Match function name and optional parameter list
+  // Supports names with module prefix like Module.func
+  const match = signature.match(/^\s*([A-Za-z0-9_.]+)\s*(?:\(([^)]*)\))?\s*$/);
+  if (!match) {
+    return null;
+  }
+
+  const functionName = match[1].trim();
+  const paramsPart = match[2];
+
+  // Default legacy behaviour: EVENT_NAME, PROPERTIES
+  if (!paramsPart) {
+    return {
+      functionName,
+      eventIndex: 0,
+      propertiesIndex: 1,
+      extraParams: []
+    };
+  }
+
+  // Split params by comma, trimming whitespace
+  const params = paramsPart.split(',').map(p => p.trim()).filter(Boolean);
+
+  const eventIndex = params.findIndex(p => p.toUpperCase() === 'EVENT_NAME');
+  let propertiesIndex = params.findIndex(p => p.toUpperCase() === 'PROPERTIES');
+
+  if (eventIndex === -1) {
+    throw new Error('EVENT_NAME is required in custom function signature');
+  }
+
+  if (propertiesIndex === -1) {
+    // If PROPERTIES is missing, assume it's at the end of the parameters
+    propertiesIndex = params.length;
+  }
+
+  const extraParams = params.map((name, idx) => ({ idx, name }))
+    .filter(p => !(p.idx === eventIndex || p.idx === propertiesIndex));
+
+  return {
+    functionName,
+    eventIndex,
+    propertiesIndex,
+    extraParams
+  };
+}
+
+module.exports = {
+  parseCustomFunctionSignature
+};

package/src/index.js

@@ -11,8 +11,8 @@ const { generateDescriptions } = require('./generateDescriptions');
 const { ChatOpenAI } = require('@langchain/openai');
 const { ChatVertexAI } = require('@langchain/google-vertexai');
 
-async function run(targetDir, outputPath, customFunction, customSourceDetails, generateDescription, provider, model, stdout, format) {
-  let events = await analyzeDirectory(targetDir, customFunction);
+async function run(targetDir, outputPath, customFunctions, customSourceDetails, generateDescription, provider, model, stdout, format) {
+  let events = await analyzeDirectory(targetDir, customFunctions);
   if (generateDescription) {
     let llm;
     if (provider === 'openai') {