@flisk/analyze-tracking 0.7.2 → 0.7.4

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

@@ -0,0 +1,427 @@
+/**
+ * @fileoverview Property extraction from TypeScript AST nodes
+ * @module analyze/typescript/extractors/property-extractor
+ */
+
+const ts = require('typescript');
+const { 
+  getTypeOfNode, 
+  resolveTypeToProperties, 
+  getBasicTypeOfArrayElement,
+  isCustomType 
+} = require('../utils/type-resolver');
+
+/**
+ * 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
+ * @property {string} [__unresolved] - Unresolved type name marker
+ */
+
+/**
+ * Extracts properties from a TypeScript ObjectLiteralExpression node
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} node - ObjectLiteralExpression node
+ * @returns {Object.<string, PropertySchema>} Extracted properties with their schemas
+ */
+function extractProperties(checker, node) {
+  if (!node || !ts.isObjectLiteralExpression(node)) {
+    return {};
+  }
+
+  const properties = {};
+
+  for (const prop of node.properties) {
+    const key = getPropertyKey(prop);
+    if (!key) continue;
+
+    const schema = extractPropertySchema(checker, prop);
+    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.name) {
+    // Shorthand property assignment
+    if (ts.isShorthandPropertyAssignment(prop)) {
+      return prop.name.escapedText;
+    }
+    return null;
+  }
+  
+  // Regular property with name
+  if (ts.isIdentifier(prop.name)) {
+    return prop.name.escapedText;
+  }
+  
+  if (ts.isStringLiteral(prop.name)) {
+    return prop.name.text;
+  }
+  
+  return null;
+}
+
+/**
+ * Extracts schema information from a property
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} prop - Property node
+ * @returns {PropertySchema|null} Property schema or null
+ */
+function extractPropertySchema(checker, prop) {
+  // Handle shorthand property assignments
+  if (ts.isShorthandPropertyAssignment(prop)) {
+    return extractShorthandPropertySchema(checker, prop);
+  }
+  
+  // Handle property assignments with initializers
+  if (ts.isPropertyAssignment(prop)) {
+    if (prop.initializer) {
+      return extractValueSchema(checker, prop.initializer);
+    }
+    
+    // Property with type annotation but no initializer
+    if (prop.type) {
+      const typeString = checker.typeToString(checker.getTypeFromTypeNode(prop.type));
+      return resolveTypeSchema(checker, typeString);
+    }
+  }
+  
+  // Handle method declarations
+  if (ts.isMethodDeclaration(prop)) {
+    return { type: 'function' };
+  }
+  
+  return null;
+}
+
+/**
+ * Extracts schema for shorthand property assignments
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} prop - ShorthandPropertyAssignment node
+ * @returns {PropertySchema}
+ */
+function extractShorthandPropertySchema(checker, prop) {
+  const symbol = checker.getSymbolAtLocation(prop.name);
+  if (!symbol) {
+    return { type: 'any' };
+  }
+  const declarations = symbol.declarations || [];
+  for (const decl of declarations) {
+    // Detect destructuring from useState: const [state, setState] = useState<Type>(...)
+    if (
+      ts.isBindingElement(decl) &&
+      decl.parent &&
+      ts.isArrayBindingPattern(decl.parent) &&
+      decl.parent.parent &&
+      ts.isVariableDeclaration(decl.parent.parent) &&
+      decl.parent.parent.initializer &&
+      ts.isCallExpression(decl.parent.parent.initializer) &&
+      ts.isIdentifier(decl.parent.parent.initializer.expression) &&
+      decl.parent.parent.initializer.expression.escapedText === 'useState'
+    ) {
+      // Try to get type from generic argument
+      const callExpr = decl.parent.parent.initializer;
+      if (callExpr.typeArguments && callExpr.typeArguments.length > 0) {
+        const typeNode = callExpr.typeArguments[0];
+        const type = checker.getTypeFromTypeNode(typeNode);
+        const typeString = checker.typeToString(type);
+        return resolveTypeToProperties(checker, typeString);
+      }
+      // Fallback: get type from initial value
+      if (callExpr.arguments && callExpr.arguments.length > 0) {
+        const initType = checker.getTypeAtLocation(callExpr.arguments[0]);
+        const typeString = checker.typeToString(initType);
+        return resolveTypeToProperties(checker, typeString);
+      }
+      // Default to any
+      return { type: 'any' };
+    }
+  }
+  
+  const propType = checker.getTypeAtLocation(prop.name);
+  const typeString = checker.typeToString(propType);
+  
+  // Handle array types
+  if (isArrayType(typeString)) {
+    return extractArrayTypeSchema(checker, propType, typeString);
+  }
+  
+  // Handle other types
+  const resolvedType = resolveTypeToProperties(checker, typeString);
+  
+  // If it's an unresolved custom type, try to extract interface properties
+  if (resolvedType.__unresolved) {
+    const interfaceProps = extractInterfaceProperties(checker, propType);
+    if (Object.keys(interfaceProps).length > 0) {
+      return {
+        type: 'object',
+        properties: interfaceProps
+      };
+    }
+  }
+  
+  return resolvedType;
+}
+
+/**
+ * Extracts schema from a value node
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} valueNode - Value node to extract schema from
+ * @returns {PropertySchema}
+ */
+function extractValueSchema(checker, valueNode) {
+  // Object literal
+  if (ts.isObjectLiteralExpression(valueNode)) {
+    return {
+      type: 'object',
+      properties: extractProperties(checker, valueNode)
+    };
+  }
+  
+  // Array literal
+  if (ts.isArrayLiteralExpression(valueNode)) {
+    return extractArrayLiteralSchema(checker, valueNode);
+  }
+  
+  // Identifier (variable reference)
+  if (ts.isIdentifier(valueNode)) {
+    return extractIdentifierSchema(checker, valueNode);
+  }
+  
+  // Literal values
+  const literalType = getLiteralType(valueNode);
+  if (literalType) {
+    return { type: literalType };
+  }
+  
+  // For other expressions, get the type from TypeChecker
+  const typeString = getTypeOfNode(checker, valueNode);
+  return resolveTypeSchema(checker, typeString);
+}
+
+/**
+ * Extracts schema for array literals
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} node - ArrayLiteralExpression node
+ * @returns {PropertySchema}
+ */
+function extractArrayLiteralSchema(checker, node) {
+  if (node.elements.length === 0) {
+    return {
+      type: 'array',
+      items: { type: 'any' }
+    };
+  }
+  
+  // Check types of all elements
+  const elementTypes = new Set();
+  for (const element of node.elements) {
+    const elemType = getBasicTypeOfArrayElement(checker, element);
+    elementTypes.add(elemType);
+  }
+  
+  // If all elements are the same type, use that type
+  const itemType = elementTypes.size === 1 ? Array.from(elementTypes)[0] : 'any';
+  
+  return {
+    type: 'array',
+    items: { type: itemType }
+  };
+}
+
+/**
+ * Extracts schema for identifier references
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} identifier - Identifier node
+ * @returns {PropertySchema}
+ */
+function extractIdentifierSchema(checker, identifier) {
+  const identifierType = checker.getTypeAtLocation(identifier);
+  const typeString = checker.typeToString(identifierType);
+  
+  // Handle array types
+  if (isArrayType(typeString)) {
+    return extractArrayTypeSchema(checker, identifierType, typeString);
+  }
+  
+  // Handle other types
+  const resolvedType = resolveTypeToProperties(checker, typeString);
+  
+  // If it's an unresolved custom type, try to extract interface properties
+  if (resolvedType.__unresolved) {
+    const interfaceProps = extractInterfaceProperties(checker, identifierType);
+    if (Object.keys(interfaceProps).length > 0) {
+      return {
+        type: 'object',
+        properties: interfaceProps
+      };
+    }
+  }
+  
+  return resolvedType;
+}
+
+/**
+ * Extracts schema for array types
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} type - TypeScript Type object
+ * @param {string} typeString - String representation of the type
+ * @returns {PropertySchema}
+ */
+function extractArrayTypeSchema(checker, type, typeString) {
+  let elementType = null;
+  
+  // Try to get type arguments for generic types
+  if (type.target && type.typeArguments && type.typeArguments.length > 0) {
+    elementType = type.typeArguments[0];
+  }
+  // Try indexed access for array types
+  else {
+    try {
+      const numberType = checker.getNumberType();
+      elementType = checker.getIndexedAccessType(type, numberType);
+    } catch (e) {
+      // Indexed access failed
+    }
+  }
+  
+  if (elementType) {
+    const elementInterfaceProps = extractInterfaceProperties(checker, elementType);
+    if (Object.keys(elementInterfaceProps).length > 0) {
+      return {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: elementInterfaceProps
+        }
+      };
+    } else {
+      const elementTypeString = checker.typeToString(elementType);
+      if (isCustomType(elementTypeString)) {
+        return {
+          type: 'array',
+          items: { type: 'object' }
+        };
+      }
+      return {
+        type: 'array',
+        items: resolveTypeToProperties(checker, elementTypeString)
+      };
+    }
+  }
+  
+  return {
+    type: 'array',
+    items: { type: 'any' }
+  };
+}
+
+/**
+ * Resolves a type string to a schema
+ * @param {Object} checker - TypeScript type checker
+ * @param {string} typeString - Type string
+ * @returns {PropertySchema}
+ */
+function resolveTypeSchema(checker, typeString) {
+  const resolvedType = resolveTypeToProperties(checker, typeString);
+  
+  // Clean up any unresolved markers for simple types
+  if (resolvedType.__unresolved) {
+    delete resolvedType.__unresolved;
+  }
+  
+  return resolvedType;
+}
+
+/**
+ * Gets the literal type of a node
+ * @param {Object} node - AST node
+ * @returns {string|null} Literal type or null
+ */
+function getLiteralType(node) {
+  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 (node.kind === ts.SyntaxKind.NullKeyword) return 'null';
+  if (node.kind === ts.SyntaxKind.UndefinedKeyword) return 'undefined';
+  return null;
+}
+
+/**
+ * Checks if a type string represents an array type
+ * @param {string} typeString - Type string to check
+ * @returns {boolean}
+ */
+function isArrayType(typeString) {
+  return typeString.includes('[]') || 
+         typeString.startsWith('Array<') || 
+         typeString.startsWith('ReadonlyArray<') ||
+         typeString.startsWith('readonly ');
+}
+
+/**
+ * Extracts properties from a TypeScript interface or type
+ * @param {Object} checker - TypeScript type checker
+ * @param {Object} type - TypeScript Type object
+ * @returns {Object.<string, PropertySchema>}
+ */
+function extractInterfaceProperties(checker, type) {
+  const properties = {};
+  const typeSymbol = type.getSymbol();
+  
+  if (!typeSymbol) return properties;
+  
+  // Get all properties of the type
+  const members = checker.getPropertiesOfType(type);
+  
+  for (const member of members) {
+    try {
+      const memberType = checker.getTypeOfSymbolAtLocation(member, member.valueDeclaration);
+      const memberTypeString = checker.typeToString(memberType);
+      
+      // Recursively resolve the member type
+      const resolvedType = resolveTypeToProperties(checker, memberTypeString);
+      
+      // If it's an unresolved object type, try to extract its properties
+      if (resolvedType.__unresolved) {
+        const nestedProperties = extractInterfaceProperties(checker, memberType);
+        if (Object.keys(nestedProperties).length > 0) {
+          properties[member.name] = {
+            type: 'object',
+            properties: nestedProperties
+          };
+        } else {
+          properties[member.name] = resolvedType;
+          delete properties[member.name].__unresolved;
+        }
+      } else if (resolvedType.type === 'array' && memberType.target) {
+        // Handle array types in interfaces
+        const arraySchema = extractArrayTypeSchema(checker, memberType, memberTypeString);
+        properties[member.name] = arraySchema;
+      } else {
+        properties[member.name] = resolvedType;
+      }
+    } catch (error) {
+      // Skip properties that cause errors
+      properties[member.name] = { type: 'any' };
+    }
+  }
+  
+  return properties;
+}
+
+module.exports = {
+  extractProperties,
+  extractInterfaceProperties
+};

package/src/analyze/typescript/index.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview TypeScript analytics tracking analyzer - main entry point
+ * @module analyze/typescript
+ */
+
+const { getProgram, findTrackingEvents, ProgramError, SourceFileError } = require('./parser');
+
+/**
+ * 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
+ * @returns {Array<Object>} Array of tracking events found in the file
+ */
+function analyzeTsFile(filePath, program, customFunction) {
+  const events = [];
+
+  try {
+    // Get or create TypeScript program
+    const tsProgram = getProgram(filePath, program);
+    
+    // Get source file from program
+    const sourceFile = tsProgram.getSourceFile(filePath);
+    if (!sourceFile) {
+      throw new SourceFileError(filePath);
+    }
+
+    // Get type checker
+    const checker = tsProgram.getTypeChecker();
+
+    // Find and extract tracking events
+    const foundEvents = findTrackingEvents(sourceFile, checker, filePath, customFunction);
+    events.push(...foundEvents);
+
+  } catch (error) {
+    if (error instanceof ProgramError) {
+      console.error(`Error creating TypeScript program for ${filePath}: ${error.originalError?.message || error.message}`);
+    } else if (error instanceof SourceFileError) {
+      console.error(`Error: Unable to get source file for ${filePath}`);
+    } else {
+      console.error(`Error analyzing TypeScript file ${filePath}: ${error.message}`);
+    }
+  }
+
+  return events;
+}
+
+module.exports = { analyzeTsFile };

package/src/analyze/typescript/parser.js

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview TypeScript AST parsing and walking module
+ * @module analyze/typescript/parser
+ */
+
+const ts = require('typescript');
+const { detectAnalyticsSource } = require('./detectors');
+const { extractEventData, processEventData } = require('./extractors');
+const { findWrappingFunction } = require('./utils/function-finder');
+
+/**
+ * Error thrown when TypeScript program cannot be created
+ */
+class ProgramError extends Error {
+  constructor(filePath, originalError) {
+    super(`Failed to create TypeScript program for: ${filePath}`);
+    this.name = 'ProgramError';
+    this.filePath = filePath;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Error thrown when source file cannot be retrieved
+ */
+class SourceFileError extends Error {
+  constructor(filePath) {
+    super(`Failed to get source file: ${filePath}`);
+    this.name = 'SourceFileError';
+    this.filePath = filePath;
+  }
+}
+
+/**
+ * Gets or creates a TypeScript program for analysis
+ * @param {string} filePath - Path to the TypeScript file
+ * @param {Object} [existingProgram] - Existing TypeScript program to reuse
+ * @returns {Object} TypeScript program
+ * @throws {ProgramError} If program cannot be created
+ */
+function getProgram(filePath, existingProgram) {
+  if (existingProgram) {
+    return existingProgram;
+  }
+
+  try {
+    // Create a minimal program for single file analysis
+    const options = {
+      target: ts.ScriptTarget.Latest,
+      module: ts.ModuleKind.CommonJS,
+      allowJs: true,
+      checkJs: false,
+      noEmit: true
+    };
+
+    const program = ts.createProgram([filePath], options);
+    return program;
+  } catch (error) {
+    throw new ProgramError(filePath, error);
+  }
+}
+
+/**
+ * Walks the TypeScript AST and finds analytics tracking calls
+ * @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
+ * @returns {Array<Object>} Array of found events
+ */
+function findTrackingEvents(sourceFile, checker, filePath, customFunction) {
+  const events = [];
+
+  /**
+   * Visitor function for AST traversal
+   * @param {Object} node - Current AST node
+   */
+  function visit(node) {
+    try {
+      if (ts.isCallExpression(node)) {
+        const event = extractTrackingEvent(node, sourceFile, checker, filePath, customFunction);
+        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;
+}
+
+/**
+ * Extracts tracking event from a CallExpression node
+ * @param {Object} node - CallExpression node
+ * @param {Object} sourceFile - TypeScript source file
+ * @param {Object} checker - TypeScript type checker
+ * @param {string} filePath - File path
+ * @param {string} [customFunction] - Custom function name
+ * @returns {Object|null} Extracted event or null
+ */
+function extractTrackingEvent(node, sourceFile, checker, 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, checker, sourceFile);
+
+  // 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);
+}
+
+module.exports = {
+  getProgram,
+  findTrackingEvents,
+  ProgramError,
+  SourceFileError
+};