@flisk/analyze-tracking 0.7.3 → 0.7.5

package/README.md

@@ -29,6 +29,8 @@ npx @flisk/analyze-tracking /path/to/project [options]
 - `-m, --model <model>`: Specify a model (ex: `gpt-4.1-nano`, `gpt-4o-mini`, `gemini-2.0-flash-lite-001`)
 - `-o, --output <output_file>`: Name of the output file (default: `tracking-schema.yaml`)
 - `-c, --customFunction <function_name>`: Specify a custom tracking function
+- `--format <format>`: Output format, either `yaml` (default) or `json`. If an invalid value is provided, the CLI will exit with an error.
+- `--stdout`: Print the output to the terminal instead of writing to a file (works with both YAML and JSON)
 
 🔑&nbsp; **Important:** If you are using `generateDescription`, you must set the appropriate credentials for the LLM provider you are using as an environment variable. OpenAI uses `OPENAI_API_KEY` and Google Vertex AI uses `GOOGLE_APPLICATION_CREDENTIALS`.
 
@@ -416,3 +418,5 @@ See [schema.json](schema.json) for a JSON Schema of the output.
 
 ## Contribute
 We're actively improving this package. Found a bug? Have a feature request? Open an issue or submit a pull request!
+
+[![Slack](https://img.shields.io/badge/Join%20Us%20on%20Slack-Flisk%20Community-611f69.svg?logo=slack)](https://join.slack.com/t/fliskcommunity/shared_invite/zt-354hesfnm-BbNzveERo9C4JwVQEWvXoA)

package/bin/cli.js

@@ -64,6 +64,17 @@ const optionDefinitions = [
     alias: 'h',
     type: Boolean,
   },
+  {
+    name: 'stdout',
+    type: Boolean,
+    defaultValue: false,
+  },
+  {
+    name: 'format',
+    alias: 'f',
+    type: String,
+    defaultValue: 'yaml',
+  },
 ]
 const options = commandLineArgs(optionDefinitions);
 const {
@@ -77,6 +88,8 @@ const {
   commitHash,
   commitTimestamp,
   help,
+  stdout,
+  format,
 } = options;
 
 if (help) {
@@ -113,4 +126,19 @@ if (generateDescription) {
   }
 }
 
-run(path.resolve(targetDir), output, customFunction, customSourceDetails, generateDescription, provider, model);
+if (format !== 'yaml' && format !== 'json') {
+  console.error(`Invalid format: ${format}. Please use --format yaml or --format json.`);
+  process.exit(1);
+}
+
+run(
+  path.resolve(targetDir),
+  output,
+  customFunction,
+  customSourceDetails,
+  generateDescription,
+  provider,
+  model,
+  stdout,
+  format
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk/analyze-tracking",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Analyzes tracking code in a project and generates data schemas",
   "main": "src/index.js",
   "bin": {
@@ -53,6 +53,8 @@
   },
   "devDependencies": {
     "ajv": "^8.17.1",
-    "lodash": "^4.17.21"
+    "lodash": "^4.17.21",
+    "react": "^19.1.0",
+    "@types/react": "^19.1.6"
   }
 }

package/src/analyze/ruby/detectors.js

@@ -36,7 +36,18 @@ function detectSource(node, customFunction = null) {
   if (node.name === 'track_struct_event') return 'snowplow';
   
   // Custom tracking function
-  if (customFunction && node.name === customFunction) return 'custom';
+  if (customFunction) {
+    // Handle simple function names (e.g., 'customTrackFunction')
+    if (node.name === customFunction) return 'custom';
+    
+    // Handle module-scoped function names (e.g., 'CustomModule.track')
+    if (customFunction.includes('.')) {
+      const [moduleName, methodName] = customFunction.split('.');
+      if (node.receiver && node.receiver.name === moduleName && node.name === methodName) {
+        return 'custom';
+      }
+    }
+  }
 
   return null;
 }

package/src/analyze/ruby/extractors.js

@@ -14,14 +14,17 @@ const { getValueType } = require('./types');
 function extractEventName(node, source) {
   if (source === 'segment' || source === 'rudderstack') {
     // Both Segment and Rudderstack use the same format
-    const params = node.arguments_.arguments_[0].elements;
+    const params = node.arguments_?.arguments_?.[0]?.elements;
+    if (!params || !Array.isArray(params)) {
+      return null;
+    }
     const eventProperty = params.find(param => param?.key?.unescaped?.value === 'event');
     return eventProperty?.value?.unescaped?.value || null;
   }
 
   if (source === 'mixpanel') {
     // Mixpanel Ruby SDK format: tracker.track('distinct_id', 'event_name', {...})
-    const args = node.arguments_.arguments_;
+    const args = node.arguments_?.arguments_;
     if (args && args.length > 1 && args[1]?.unescaped?.value) {
       return args[1].unescaped.value;
     }
@@ -29,8 +32,8 @@ function extractEventName(node, source) {
 
   if (source === 'posthog') {
     // PostHog Ruby SDK format: posthog.capture({distinct_id: '...', event: '...', properties: {...}})
-    const hashArg = node.arguments_.arguments_[0];
-    if (hashArg && hashArg.elements) {
+    const hashArg = node.arguments_?.arguments_?.[0];
+    if (hashArg && hashArg.elements && Array.isArray(hashArg.elements)) {
       const eventProperty = hashArg.elements.find(elem => elem?.key?.unescaped?.value === 'event');
       return eventProperty?.value?.unescaped?.value || null;
     }
@@ -38,14 +41,17 @@ function extractEventName(node, source) {
 
   if (source === 'snowplow') {
     // Snowplow Ruby SDK: tracker.track_struct_event(category: '...', action: '...', ...)
-    const params = node.arguments_.arguments_[0].elements;
+    const params = node.arguments_?.arguments_?.[0]?.elements;
+    if (!params || !Array.isArray(params)) {
+      return null;
+    }
     const actionProperty = params.find(param => param?.key?.unescaped?.value === 'action');
     return actionProperty?.value?.unescaped?.value || null;
   }
   
   if (source === 'custom') {
     // Custom function format: customFunction('event_name', {...})
-    const args = node.arguments_.arguments_;
+    const args = node.arguments_?.arguments_;
     if (args && args.length > 0 && args[0]?.unescaped?.value) {
       return args[0].unescaped.value;
     }
@@ -65,7 +71,10 @@ async function extractProperties(node, source) {
 
   if (source === 'segment' || source === 'rudderstack') {
     // Both Segment and Rudderstack use the same format
-    const params = node.arguments_.arguments_[0].elements;
+    const params = node.arguments_?.arguments_?.[0]?.elements;
+    if (!params || !Array.isArray(params)) {
+      return null;
+    }
     const properties = {};
 
     // Process all top-level fields except 'event'
@@ -108,7 +117,7 @@ async function extractProperties(node, source) {
 
   if (source === 'mixpanel') {
     // Mixpanel Ruby SDK: tracker.track('distinct_id', 'event_name', {properties})
-    const args = node.arguments_.arguments_;
+    const args = node.arguments_?.arguments_;
     const properties = {};
     
     // Add distinct_id as property (even if it's a variable)
@@ -129,10 +138,10 @@ async function extractProperties(node, source) {
 
   if (source === 'posthog') {
     // PostHog Ruby SDK: posthog.capture({distinct_id: '...', event: '...', properties: {...}})
-    const hashArg = node.arguments_.arguments_[0];
+    const hashArg = node.arguments_?.arguments_?.[0];
     const properties = {};
     
-    if (hashArg && hashArg.elements) {
+    if (hashArg && hashArg.elements && Array.isArray(hashArg.elements)) {
       // Extract distinct_id if present
       const distinctIdProperty = hashArg.elements.find(elem => elem?.key?.unescaped?.value === 'distinct_id');
       if (distinctIdProperty?.value) {
@@ -154,7 +163,10 @@ async function extractProperties(node, source) {
 
   if (source === 'snowplow') {
     // Snowplow Ruby SDK: tracker.track_struct_event(category: '...', action: '...', ...)
-    const params = node.arguments_.arguments_[0].elements;
+    const params = node.arguments_?.arguments_?.[0]?.elements;
+    if (!params || !Array.isArray(params)) {
+      return null;
+    }
     const properties = {};
     
     // Extract all struct event parameters except 'action' (which is used as the event name)
@@ -172,7 +184,7 @@ async function extractProperties(node, source) {
   
   if (source === 'custom') {
     // Custom function format: customFunction('event_name', {properties})
-    const args = node.arguments_.arguments_;
+    const args = node.arguments_?.arguments_;
     if (args && args.length > 1 && args[1] instanceof HashNode) {
       return await extractHashProperties(args[1]);
     }

package/src/analyze/ruby/visitor.js

@@ -29,7 +29,16 @@ class TrackingVisitor {
       if (!eventName) return;
 
       const line = getLineNumber(this.code, node.location);
-      const functionName = await findWrappingFunction(node, ancestors);
+      
+      // 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;
+      } else {
+        functionName = await findWrappingFunction(node, ancestors);
+      }
+      
       const properties = await extractProperties(node, source);
 
       this.events.push({

package/src/analyze/typescript/detectors/analytics-source.js

@@ -44,8 +44,13 @@ function detectAnalyticsSource(node, customFunction) {
  * @returns {boolean}
  */
 function isCustomFunction(node, customFunction) {
-  return ts.isIdentifier(node.expression) && 
-         node.expression.escapedText === customFunction;
+  const canBeCustomFunction = ts.isIdentifier(node.expression) ||
+    ts.isPropertyAccessExpression(node.expression) ||
+    ts.isCallExpression(node.expression) || // For chained calls like getTracker().track()
+    ts.isElementAccessExpression(node.expression) || // For array/object access like trackers['analytics'].track()
+    (ts.isPropertyAccessExpression(node.expression?.expression) && ts.isThisExpression(node.expression.expression.expression)); // For class methods like this.analytics.track()
+
+  return canBeCustomFunction && node.expression.getText() === customFunction;
 }
 
 /**
@@ -59,7 +64,7 @@ function detectFunctionBasedProvider(node) {
   }
 
   const functionName = node.expression.escapedText;
-  
+
   for (const provider of Object.values(ANALYTICS_PROVIDERS)) {
     if (provider.type === 'function' && provider.functionName === functionName) {
       return provider.name;
@@ -79,8 +84,8 @@ function detectMemberBasedProvider(node) {
     return 'unknown';
   }
 
-  const objectName = node.expression.expression.escapedText;
-  const methodName = node.expression.name.escapedText;
+  const objectName = node.expression.expression?.escapedText;
+  const methodName = node.expression.name?.escapedText;
 
   if (!objectName || !methodName) {
     return 'unknown';

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

@@ -116,6 +116,38 @@ function extractShorthandPropertySchema(checker, prop) {
   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);
@@ -318,6 +350,7 @@ function resolveTypeSchema(checker, typeString) {
  * @returns {string|null} Literal type or null
  */
 function getLiteralType(node) {
+  if (!node) return null;
   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';

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

@@ -4,6 +4,7 @@
  */
 
 const ts = require('typescript');
+const { isReactHookCall } = require('./type-resolver');
 
 /**
  * Finds the name of the function that wraps a given node
@@ -12,17 +13,17 @@ const ts = require('typescript');
  */
 function findWrappingFunction(node) {
   let current = node;
-  
+
   while (current) {
     const functionName = extractFunctionName(current);
-    
+
     if (functionName) {
       return functionName;
     }
-    
+
     current = current.parent;
   }
-  
+
   return 'global';
 }
 
@@ -36,27 +37,27 @@ function extractFunctionName(node) {
   if (ts.isFunctionDeclaration(node)) {
     return node.name ? node.name.escapedText : 'anonymous';
   }
-  
+
   // Method declaration in class
   if (ts.isMethodDeclaration(node)) {
     return node.name ? node.name.escapedText : 'anonymous';
   }
-  
+
   // Arrow function or function expression
   if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
     return findParentFunctionName(node) || 'anonymous';
   }
-  
+
   // Constructor
   if (ts.isConstructorDeclaration(node)) {
     return 'constructor';
   }
-  
+
   // Getter/Setter
   if (ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
     return node.name ? `${ts.isGetAccessorDeclaration(node) ? 'get' : 'set'} ${node.name.escapedText}` : 'anonymous';
   }
-  
+
   return null;
 }
 
@@ -67,14 +68,38 @@ function extractFunctionName(node) {
  */
 function findParentFunctionName(node) {
   const parent = node.parent;
-  
+
   if (!parent) return null;
-  
+
+  if (
+    ts.isCallExpression(parent) &&
+    ts.isIdentifier(parent.expression) &&
+    isReactHookCall(parent)
+  ) {
+    if (
+      parent.parent &&
+      ts.isVariableDeclaration(parent.parent) &&
+      parent.parent.name
+    ) {
+      return `${parent.expression.escapedText}(${parent.parent.name.escapedText})`;
+    }
+    return `${parent.expression.escapedText}()`;
+  }
+
   // Variable declaration: const myFunc = () => {}
   if (ts.isVariableDeclaration(parent) && parent.name) {
+    // Check if initializer is a recognized React hook call
+    if (
+      parent.initializer &&
+      ts.isCallExpression(parent.initializer) &&
+      ts.isIdentifier(parent.initializer.expression) &&
+      isReactHookCall(parent.initializer)
+    ) {
+      return `${parent.initializer.expression.escapedText}(${parent.name.escapedText})`;
+    }
     return parent.name.escapedText;
   }
-  
+
   // Property assignment: { myFunc: () => {} }
   if (ts.isPropertyAssignment(parent) && parent.name) {
     if (ts.isIdentifier(parent.name)) {
@@ -84,20 +109,20 @@ function findParentFunctionName(node) {
       return parent.name.text;
     }
   }
-  
+
   // Method property in object literal: { myFunc() {} }
   if (ts.isMethodDeclaration(parent) && parent.name) {
     return parent.name.escapedText;
   }
-  
+
   // Binary expression assignment: obj.myFunc = () => {}
-  if (ts.isBinaryExpression(parent) && 
-      parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+  if (ts.isBinaryExpression(parent) &&
+    parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
     if (ts.isPropertyAccessExpression(parent.left)) {
       return parent.left.name.escapedText;
     }
   }
-  
+
   // Call expression argument: someFunc(() => {})
   if (ts.isCallExpression(parent)) {
     const argIndex = parent.arguments.indexOf(node);
@@ -105,7 +130,7 @@ function findParentFunctionName(node) {
       return `anonymous-callback-${argIndex}`;
     }
   }
-  
+
   return null;
 }
 

package/src/analyze/typescript/utils/type-resolver.js

@@ -184,10 +184,25 @@ function getBasicTypeOfArrayElement(checker, element) {
   return 'any';
 }
 
+/**
+ * Checks if a CallExpression is a React hook (useCallback, useState, etc)
+ * @param {Object} node - CallExpression node
+ * @param {string[]} hookNames - List of hook names to check
+ * @returns {boolean}
+ */
+function isReactHookCall(node, hookNames = ['useCallback', 'useState', 'useEffect', 'useMemo', 'useReducer']) {
+  if (!node || !node.expression) return false;
+  if (ts.isIdentifier(node.expression)) {
+    return hookNames.includes(node.expression.escapedText);
+  }
+  return false;
+}
+
 module.exports = {
   resolveIdentifierToInitializer,
   getTypeOfNode,
   resolveTypeToProperties,
   isCustomType,
-  getBasicTypeOfArrayElement
+  getBasicTypeOfArrayElement,
+  isReactHookCall
 };

package/src/index.js

@@ -5,13 +5,13 @@
 
 const { analyzeDirectory } = require('./analyze');
 const { getRepoDetails } = require('./utils/repoDetails');
-const { generateYamlSchema } = require('./utils/yamlGenerator');
+const { generateYamlSchema, generateJsonSchema } = require('./utils/yamlGenerator');
 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) {
+async function run(targetDir, outputPath, customFunction, customSourceDetails, generateDescription, provider, model, stdout, format) {
   let events = await analyzeDirectory(targetDir, customFunction);
   if (generateDescription) {
     let llm;
@@ -35,7 +35,11 @@ async function run(targetDir, outputPath, customFunction, customSourceDetails, g
     events = await generateDescriptions(events, targetDir, llm);
   }
   const repoDetails = await getRepoDetails(targetDir, customSourceDetails);
-  generateYamlSchema(events, repoDetails, outputPath);
+  if (format === 'json') {
+    generateJsonSchema(events, repoDetails, outputPath, stdout);
+  } else {
+    generateYamlSchema(events, repoDetails, outputPath, stdout);
+  }
 }
 
 module.exports = { run };

package/src/utils/yamlGenerator.js

@@ -9,7 +9,7 @@ const yaml = require('js-yaml');
 const VERSION = 1
 const SCHEMA_URL = "https://raw.githubusercontent.com/fliskdata/analyze-tracking/main/schema.json";
 
-function generateYamlSchema(events, repository, outputPath) {
+function generateYamlSchema(events, repository, outputPath, stdout = false) {
   const schema = {
     version: VERSION,
     source: repository,
@@ -21,8 +21,27 @@ function generateYamlSchema(events, repository, outputPath) {
   };
   const yamlOutput = yaml.dump(schema, options);
   const yamlFile = `# yaml-language-server: $schema=${SCHEMA_URL}\n${yamlOutput}`;
-  fs.writeFileSync(outputPath, yamlFile, 'utf8');
-  console.log(`Tracking schema YAML file generated: ${outputPath}`);
+  if (stdout) {
+    process.stdout.write(yamlFile);
+  } else {
+    fs.writeFileSync(outputPath, yamlFile, 'utf8');
+    console.log(`Tracking schema YAML file generated: ${outputPath}`);
+  }
 }
 
-module.exports = { generateYamlSchema };
+function generateJsonSchema(events, repository, outputPath, stdout = false) {
+  const schema = {
+    version: VERSION,
+    source: repository,
+    events,
+  };
+  const jsonFile = JSON.stringify(schema, null, 2);
+  if (stdout) {
+    process.stdout.write(jsonFile);
+  } else {
+    fs.writeFileSync(outputPath, jsonFile, 'utf8');
+    console.log(`Tracking schema JSON file generated: ${outputPath}`);
+  }
+}
+
+module.exports = { generateYamlSchema, generateJsonSchema };