@flisk/analyze-tracking 0.7.2 → 0.7.4

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

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Event extraction logic for different analytics providers
+ * @module analyze/javascript/extractors/event-extractor
+ */
+
+const { NODE_TYPES } = require('../constants');
+const { extractProperties } = require('./property-extractor');
+
+/**
+ * Event data structure
+ * @typedef {Object} EventData
+ * @property {string|null} eventName - The event name
+ * @property {Object|null} propertiesNode - AST node containing event properties
+ */
+
+/**
+ * Provider-specific extraction strategies
+ */
+const EXTRACTION_STRATEGIES = {
+  googleanalytics: extractGoogleAnalyticsEvent,
+  snowplow: extractSnowplowEvent,
+  mparticle: extractMparticleEvent,
+  default: extractDefaultEvent
+};
+
+/**
+ * Extracts event information from a CallExpression node
+ * @param {Object} node - AST CallExpression node
+ * @param {string} source - Analytics provider source
+ * @returns {EventData} Extracted event data
+ */
+function extractEventData(node, source) {
+  const strategy = EXTRACTION_STRATEGIES[source] || EXTRACTION_STRATEGIES.default;
+  return strategy(node);
+}
+
+/**
+ * Extracts Google Analytics event data
+ * @param {Object} node - CallExpression node
+ * @returns {EventData}
+ */
+function extractGoogleAnalyticsEvent(node) {
+  if (!node.arguments || node.arguments.length < 3) {
+    return { eventName: null, propertiesNode: null };
+  }
+
+  // gtag('event', 'event_name', { properties })
+  const eventName = getStringValue(node.arguments[1]);
+  const propertiesNode = node.arguments[2];
+
+  return { eventName, propertiesNode };
+}
+
+/**
+ * Extracts Snowplow event data
+ * @param {Object} node - CallExpression node
+ * @returns {EventData}
+ */
+function extractSnowplowEvent(node) {
+  if (!node.arguments || node.arguments.length === 0) {
+    return { eventName: null, propertiesNode: null };
+  }
+
+  // tracker.track(buildStructEvent({ action: 'event_name', ... }))
+  const firstArg = node.arguments[0];
+  
+  if (firstArg.type === NODE_TYPES.CALL_EXPRESSION && 
+      firstArg.arguments.length > 0) {
+    const structEventArg = firstArg.arguments[0];
+    
+    if (structEventArg.type === NODE_TYPES.OBJECT_EXPRESSION) {
+      const actionProperty = findPropertyByKey(structEventArg, 'action');
+      const eventName = actionProperty ? getStringValue(actionProperty.value) : null;
+      
+      return { eventName, propertiesNode: structEventArg };
+    }
+  }
+
+  return { eventName: null, propertiesNode: null };
+}
+
+/**
+ * Extracts mParticle event data
+ * @param {Object} node - CallExpression node
+ * @returns {EventData}
+ */
+function extractMparticleEvent(node) {
+  if (!node.arguments || node.arguments.length < 3) {
+    return { eventName: null, propertiesNode: null };
+  }
+
+  // mParticle.logEvent('event_name', mParticle.EventType.Navigation, { properties })
+  const eventName = getStringValue(node.arguments[0]);
+  const propertiesNode = node.arguments[2];
+
+  return { eventName, propertiesNode };
+}
+
+/**
+ * Default event extraction for standard providers
+ * @param {Object} node - CallExpression node
+ * @returns {EventData}
+ */
+function extractDefaultEvent(node) {
+  if (!node.arguments || node.arguments.length < 2) {
+    return { eventName: null, propertiesNode: null };
+  }
+
+  // provider.track('event_name', { properties })
+  const eventName = getStringValue(node.arguments[0]);
+  const propertiesNode = node.arguments[1];
+
+  return { eventName, propertiesNode };
+}
+
+/**
+ * Processes extracted event data into final event object
+ * @param {EventData} eventData - Raw event data
+ * @param {string} source - Analytics source
+ * @param {string} filePath - File path
+ * @param {number} line - Line number
+ * @param {string} functionName - Containing function name
+ * @returns {Object|null} Processed event object or null
+ */
+function processEventData(eventData, source, filePath, line, functionName) {
+  const { eventName, propertiesNode } = eventData;
+
+  if (!eventName || !propertiesNode || propertiesNode.type !== NODE_TYPES.OBJECT_EXPRESSION) {
+    return null;
+  }
+
+  let properties = extractProperties(propertiesNode);
+
+  // Special handling for Snowplow: remove 'action' from properties
+  if (source === 'snowplow' && properties.action) {
+    delete properties.action;
+  }
+
+  return {
+    eventName,
+    source,
+    properties,
+    filePath,
+    line,
+    functionName
+  };
+}
+
+/**
+ * Gets string value from an AST node
+ * @param {Object} node - AST node
+ * @returns {string|null} String value or null
+ */
+function getStringValue(node) {
+  if (!node) return null;
+  if (node.type === NODE_TYPES.LITERAL && typeof node.value === 'string') {
+    return node.value;
+  }
+  return null;
+}
+
+/**
+ * Finds a property by key in an ObjectExpression
+ * @param {Object} objectNode - ObjectExpression node
+ * @param {string} key - Property key to find
+ * @returns {Object|null} Property node or null
+ */
+function findPropertyByKey(objectNode, key) {
+  if (!objectNode.properties) return null;
+  
+  return objectNode.properties.find(prop => 
+    prop.key && (prop.key.name === key || prop.key.value === key)
+  );
+}
+
+module.exports = {
+  extractEventData,
+  processEventData
+};

package/src/analyze/javascript/extractors/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Central export for all extractor modules
+ * @module analyze/javascript/extractors
+ */
+
+const { extractEventData, processEventData } = require('./event-extractor');
+const { extractProperties } = require('./property-extractor');
+
+module.exports = {
+  extractEventData,
+  processEventData,
+  extractProperties
+};

package/src/analyze/javascript/extractors/property-extractor.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Property extraction from AST nodes
+ * @module analyze/javascript/extractors/property-extractor
+ */
+
+const { NODE_TYPES } = require('../constants');
+
+/**
+ * Property structure representation
+ * @typedef {Object} PropertySchema
+ * @property {string} type - The property type (string, number, boolean, object, array, any)
+ * @property {PropertySchema} [properties] - Nested properties for objects
+ * @property {Object} [items] - Item type information for arrays
+ */
+
+/**
+ * Extracts properties from an ObjectExpression node
+ * @param {Object} node - AST ObjectExpression node
+ * @returns {Object.<string, PropertySchema>} Extracted properties with their schemas
+ */
+function extractProperties(node) {
+  if (!node || node.type !== NODE_TYPES.OBJECT_EXPRESSION) {
+    return {};
+  }
+
+  const properties = {};
+
+  node.properties.forEach((prop) => {
+    const key = getPropertyKey(prop);
+    if (!key) return;
+
+    const schema = extractPropertySchema(prop.value);
+    if (schema) {
+      properties[key] = schema;
+    }
+  });
+
+  return properties;
+}
+
+/**
+ * Gets the key name from a property node
+ * @param {Object} prop - Property node
+ * @returns {string|null} Property key or null
+ */
+function getPropertyKey(prop) {
+  if (!prop.key) return null;
+  return prop.key.name || prop.key.value || null;
+}
+
+/**
+ * Extracts schema information from a property value
+ * @param {Object} valueNode - AST node representing the property value
+ * @returns {PropertySchema|null} Property schema or null
+ */
+function extractPropertySchema(valueNode) {
+  if (!valueNode) return null;
+
+  switch (valueNode.type) {
+    case NODE_TYPES.OBJECT_EXPRESSION:
+      return extractObjectSchema(valueNode);
+      
+    case NODE_TYPES.ARRAY_EXPRESSION:
+      return extractArraySchema(valueNode);
+      
+    case NODE_TYPES.LITERAL:
+      return extractLiteralSchema(valueNode);
+      
+    default:
+      return { type: 'any' };
+  }
+}
+
+/**
+ * Extracts schema for object expressions
+ * @param {Object} node - ObjectExpression node
+ * @returns {PropertySchema}
+ */
+function extractObjectSchema(node) {
+  return {
+    type: 'object',
+    properties: extractProperties(node)
+  };
+}
+
+/**
+ * Extracts schema for array expressions
+ * @param {Object} node - ArrayExpression node
+ * @returns {PropertySchema}
+ */
+function extractArraySchema(node) {
+  const itemType = inferArrayItemType(node.elements);
+  
+  return {
+    type: 'array',
+    items: {
+      type: itemType
+    }
+  };
+}
+
+/**
+ * Extracts schema for literal values
+ * @param {Object} node - Literal node
+ * @returns {PropertySchema}
+ */
+function extractLiteralSchema(node) {
+  const valueType = typeof node.value;
+  
+  // Handle null and undefined
+  if (node.value === null || valueType === 'undefined') {
+    return { type: 'any' };
+  }
+  
+  // Handle valid primitive types
+  if (['string', 'number', 'boolean'].includes(valueType)) {
+    return { type: valueType };
+  }
+  
+  // Default to 'any' for other types
+  return { type: 'any' };
+}
+
+/**
+ * Infers the item type of an array from its elements
+ * @param {Array} elements - Array of AST nodes
+ * @returns {string} Inferred type or 'any'
+ */
+function inferArrayItemType(elements) {
+  if (!elements || elements.length === 0) {
+    return 'any';
+  }
+
+  const types = new Set();
+  
+  elements.forEach(element => {
+    if (!element) return;
+    
+    const elementType = getElementType(element);
+    types.add(elementType);
+  });
+
+  // If all elements have the same type, use that type
+  if (types.size === 1) {
+    return Array.from(types)[0];
+  }
+  
+  // Mixed types default to 'any'
+  return 'any';
+}
+
+/**
+ * Gets the type of an array element
+ * @param {Object} element - AST node
+ * @returns {string} Element type
+ */
+function getElementType(element) {
+  switch (element.type) {
+    case NODE_TYPES.LITERAL:
+      return typeof element.value;
+    case NODE_TYPES.OBJECT_EXPRESSION:
+      return 'object';
+    case NODE_TYPES.ARRAY_EXPRESSION:
+      return 'array';
+    default:
+      return 'any';
+  }
+}
+
+module.exports = {
+  extractProperties
+};

package/src/analyze/javascript/index.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview JavaScript analytics tracking analyzer - main entry point
+ * @module analyze/javascript
+ */
+
+const { parseFile, findTrackingEvents, FileReadError, ParseError } = require('./parser');
+
+/**
+ * Analyzes a JavaScript file for analytics tracking calls
+ * @param {string} filePath - Path to the JavaScript file to analyze
+ * @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 = [];
+
+  try {
+    // Parse the file into an AST
+    const ast = parseFile(filePath);
+
+    // Find and extract tracking events
+    const foundEvents = findTrackingEvents(ast, filePath, customFunction);
+    events.push(...foundEvents);
+
+  } catch (error) {
+    if (error instanceof FileReadError) {
+      console.error(`Error reading file ${filePath}: ${error.originalError.message}`);
+    } else if (error instanceof ParseError) {
+      console.error(`Error parsing file ${filePath}: ${error.originalError.message}`);
+    } else {
+      console.error(`Unexpected error analyzing ${filePath}: ${error.message}`);
+    }
+  }
+
+  return events;
+}
+
+module.exports = { analyzeJsFile };

package/src/analyze/javascript/parser.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview AST parsing and walking module
+ * @module analyze/javascript/parser
+ */
+
+const fs = require('fs');
+const acorn = require('acorn');
+const jsx = require('acorn-jsx');
+const walk = require('acorn-walk');
+const { extend } = require('acorn-jsx-walk');
+const { PARSER_OPTIONS, NODE_TYPES } = require('./constants');
+const { detectAnalyticsSource } = require('./detectors');
+const { extractEventData, processEventData } = require('./extractors');
+const { findWrappingFunction } = require('./utils/function-finder');
+
+// Extend walker to support JSX
+extend(walk.base);
+
+// Configure parser with JSX support
+const parser = acorn.Parser.extend(jsx());
+
+/**
+ * Error thrown when file cannot be read
+ */
+class FileReadError extends Error {
+  constructor(filePath, originalError) {
+    super(`Failed to read file: ${filePath}`);
+    this.name = 'FileReadError';
+    this.filePath = filePath;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Error thrown when file cannot be parsed
+ */
+class ParseError extends Error {
+  constructor(filePath, originalError) {
+    super(`Failed to parse file: ${filePath}`);
+    this.name = 'ParseError';
+    this.filePath = filePath;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Parses a JavaScript file and returns its AST
+ * @param {string} filePath - Path to the JavaScript file
+ * @returns {Object} Parsed AST
+ * @throws {FileReadError} If file cannot be read
+ * @throws {ParseError} If file cannot be parsed
+ */
+function parseFile(filePath) {
+  let code;
+  
+  try {
+    code = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new FileReadError(filePath, error);
+  }
+
+  try {
+    return parser.parse(code, PARSER_OPTIONS);
+  } catch (error) {
+    throw new ParseError(filePath, error);
+  }
+}
+
+/**
+ * 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
+ */
+function findTrackingEvents(ast, filePath, customFunction) {
+  const events = [];
+
+  walk.ancestor(ast, {
+    [NODE_TYPES.CALL_EXPRESSION]: (node, ancestors) => {
+      try {
+        const event = extractTrackingEvent(node, ancestors, filePath, customFunction);
+        if (event) {
+          events.push(event);
+        }
+      } catch (error) {
+        console.error(`Error processing node in ${filePath}:`, error.message);
+      }
+    }
+  });
+
+  return events;
+}
+
+/**
+ * Extracts tracking event from a CallExpression node
+ * @param {Object} node - CallExpression node
+ * @param {Array<Object>} ancestors - Ancestor nodes
+ * @param {string} filePath - File path
+ * @param {string} [customFunction] - Custom function name
+ * @returns {Object|null} Extracted event or null
+ */
+function extractTrackingEvent(node, ancestors, filePath, customFunction) {
+  // Detect the analytics source
+  const source = detectAnalyticsSource(node, customFunction);
+  if (source === 'unknown') {
+    return null;
+  }
+
+  // Extract event data based on the source
+  const eventData = extractEventData(node, source);
+
+  // 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);
+}
+
+module.exports = {
+  parseFile,
+  findTrackingEvents,
+  FileReadError,
+  ParseError
+};

package/src/analyze/javascript/utils/function-finder.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Utilities for finding function context in AST
+ * @module analyze/javascript/utils/function-finder
+ */
+
+const { NODE_TYPES } = require('../constants');
+
+/**
+ * Finds the name of the function that wraps a given node
+ * @param {Object} node - The AST node to find the wrapper for
+ * @param {Array<Object>} ancestors - Array of ancestor nodes from acorn-walk
+ * @returns {string} The function name or 'global' if not in a function
+ */
+function findWrappingFunction(node, ancestors) {
+  // Traverse ancestors from closest to furthest
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+    const functionName = extractFunctionName(current, node, ancestors[i - 1]);
+    
+    if (functionName) {
+      return functionName;
+    }
+  }
+  
+  return 'global';
+}
+
+/**
+ * Extracts function name from different AST node types
+ * @param {Object} current - Current ancestor node
+ * @param {Object} node - Original node being analyzed
+ * @param {Object} [parent] - Parent of current node
+ * @returns {string|null} Function name or null if not a function context
+ */
+function extractFunctionName(current, node, parent) {
+  switch (current.type) {
+    case NODE_TYPES.VARIABLE_DECLARATOR:
+      return handleVariableDeclarator(current, node);
+      
+    case NODE_TYPES.FUNCTION_DECLARATION:
+      return current.id ? current.id.name : 'anonymous';
+      
+    case NODE_TYPES.METHOD_DEFINITION:
+      return current.key.name || 'anonymous';
+      
+    case NODE_TYPES.PROPERTY:
+      return handleObjectProperty(current, node);
+      
+    case NODE_TYPES.EXPORT_NAMED:
+      return handleNamedExport(current);
+      
+    default:
+      return null;
+  }
+}
+
+/**
+ * Handles variable declarator nodes (const/let/var declarations)
+ * @param {Object} declarator - VariableDeclarator node
+ * @param {Object} node - Original node being analyzed
+ * @returns {string|null} Function name or null
+ */
+function handleVariableDeclarator(declarator, node) {
+  // Direct assignment: const myFunc = () => {}
+  if (declarator.init === node) {
+    return declarator.id.name;
+  }
+  
+  // Function expression assignment
+  if (declarator.init && isFunctionNode(declarator.init)) {
+    return declarator.id.name;
+  }
+  
+  return null;
+}
+
+/**
+ * Handles object property nodes (methods in object literals)
+ * @param {Object} property - Property node
+ * @param {Object} node - Original node being analyzed
+ * @returns {string|null} Function name or null
+ */
+function handleObjectProperty(property, node) {
+  if (property.value === node || isFunctionNode(property.value)) {
+    return property.key.name || property.key.value || 'anonymous';
+  }
+  return null;
+}
+
+/**
+ * Handles named export declarations
+ * @param {Object} exportNode - ExportNamedDeclaration node
+ * @returns {string|null} Function name or null
+ */
+function handleNamedExport(exportNode) {
+  if (!exportNode.declaration || !exportNode.declaration.declarations) {
+    return null;
+  }
+  
+  const declaration = exportNode.declaration.declarations[0];
+  if (declaration && isFunctionNode(declaration.init)) {
+    return declaration.id.name;
+  }
+  
+  return null;
+}
+
+/**
+ * Checks if a node is a function (arrow function or function expression)
+ * @param {Object} node - AST node to check
+ * @returns {boolean}
+ */
+function isFunctionNode(node) {
+  return node && (
+    node.type === NODE_TYPES.ARROW_FUNCTION ||
+    node.type === NODE_TYPES.FUNCTION_EXPRESSION ||
+    node.type === NODE_TYPES.FUNCTION_DECLARATION
+  );
+}
+
+module.exports = {
+  findWrappingFunction
+};