@flisk/analyze-tracking 0.7.6 → 0.8.1

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,
@@ -233,27 +296,75 @@ function resolvePropertyAccessToString(node, checker, sourceFile) {
   try {
     // Get the symbol for the property access
     const symbol = checker.getSymbolAtLocation(node);
-    if (!symbol || !symbol.valueDeclaration) {
-      return null;
-    }
-    
-    // Check if it's a property assignment with a string initializer
-    if (ts.isPropertyAssignment(symbol.valueDeclaration) && 
-        symbol.valueDeclaration.initializer &&
-        ts.isStringLiteral(symbol.valueDeclaration.initializer)) {
-      return symbol.valueDeclaration.initializer.text;
+    if (symbol && symbol.valueDeclaration) {
+      // Check if it's a property assignment with a string initializer
+      if (ts.isPropertyAssignment(symbol.valueDeclaration) &&
+          symbol.valueDeclaration.initializer &&
+          ts.isStringLiteral(symbol.valueDeclaration.initializer)) {
+        return symbol.valueDeclaration.initializer.text;
+      }
+
+      // Check if it's a variable declaration property (string literal type)
+      if (ts.isPropertySignature(symbol.valueDeclaration) ||
+          ts.isMethodSignature(symbol.valueDeclaration)) {
+        const type = checker.getTypeAtLocation(node);
+        if (type && type.isStringLiteral && type.isStringLiteral()) {
+          return type.value;
+        }
+      }
     }
-    
-    // Check if it's a variable declaration property
-    if (ts.isPropertySignature(symbol.valueDeclaration) ||
-        ts.isMethodSignature(symbol.valueDeclaration)) {
-      // Try to get the type and see if it's a string literal type
-      const type = checker.getTypeAtLocation(node);
-      if (type.isStringLiteral && type.isStringLiteral()) {
-        return type.value;
+
+    // ---------------------------------------------------------------------
+    // Fallback – manually resolve patterns like:
+    //   const CONST = { KEY: 'value' };
+    //   const CONST = Object.freeze({ KEY: 'value' });
+    // And later used as CONST.KEY
+    // ---------------------------------------------------------------------
+    if (ts.isIdentifier(node.expression)) {
+      const objIdentifier = node.expression;
+      const initializer = resolveIdentifierToInitializer(checker, objIdentifier, sourceFile);
+      if (initializer) {
+        let objectLiteral = null;
+
+        // Handle direct object literal initializers
+        if (ts.isObjectLiteralExpression(initializer)) {
+          objectLiteral = initializer;
+        }
+        // Handle Object.freeze({ ... }) pattern
+        else if (ts.isCallExpression(initializer)) {
+          const callee = initializer.expression;
+          if (
+            ts.isPropertyAccessExpression(callee) &&
+            ts.isIdentifier(callee.expression) &&
+            callee.expression.escapedText === 'Object' &&
+            callee.name.escapedText === 'freeze' &&
+            initializer.arguments.length > 0 &&
+            ts.isObjectLiteralExpression(initializer.arguments[0])
+          ) {
+            objectLiteral = initializer.arguments[0];
+          }
+        }
+
+        if (objectLiteral) {
+          const propNode = findPropertyByKey(objectLiteral, node.name.escapedText || node.name.text);
+          if (propNode && propNode.initializer && ts.isStringLiteral(propNode.initializer)) {
+            return propNode.initializer.text;
+          }
+        }
       }
     }
-    
+
+    // Final fallback – use type information at location (works for imported Object.freeze constants)
+    try {
+      const t = checker.getTypeAtLocation(node);
+      if (t && t.isStringLiteral && typeof t.isStringLiteral === 'function' && t.isStringLiteral()) {
+        return t.value;
+      }
+      if (t && t.flags && (t.flags & ts.TypeFlags.StringLiteral)) {
+        return t.value;
+      }
+    } catch (_) {/* ignore */}
+
     return null;
   } catch (error) {
     return null;
@@ -368,6 +479,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') {