multiple custom functions spec

Author: skarim

README.md

@@ -57,6 +57,13 @@ yourCustomTrackFunctionName(userId, EVENT_NAME, PROPERTIES)
 
 If your function follows the standard format `yourCustomTrackFunctionName(EVENT_NAME, PROPERTIES)`, you can simply pass in `yourCustomTrackFunctionName` to `--customFunction` as a shorthand.
 
+You can also pass in multiple custom function signatures by passing in the `--customFunction` option multiple times or by passing in a space-separated list of function signatures.
+
+```sh
+npx @flisk/analyze-tracking /path/to/project --customFunction "yourFunc1" --customFunction "yourFunc2(userId, EVENT_NAME, PROPERTIES)"
+npx @flisk/analyze-tracking /path/to/project -c "yourFunc1" "yourFunc2(userId, EVENT_NAME, PROPERTIES)"
+```
+
 
 ## What's Generated?
 A clear YAML schema that shows where your events are tracked, their properties, and more.

bin/cli.js

@@ -43,6 +43,7 @@ const optionDefinitions = [
     name: 'customFunction',
     alias: 'c',
     type: String,
+    multiple: true,
   },
   {
     name: 'repositoryUrl',

src/analyze/go/index.js

@@ -8,8 +8,6 @@ const { extractGoAST } = require('./goAstParser');
 const { buildTypeContext } = require('./typeContext');
 const { deduplicateEvents } = require('./eventDeduplicator');
 const { extractEventsFromBody } = require('./astTraversal');
-const { processGoFile } = require('./utils');
-const { parseCustomFunctionSignature } = require('../utils/customFunctionParser');
 
 /**
  * Analyze a Go file and extract tracking events
@@ -18,9 +16,10 @@ const { parseCustomFunctionSignature } = require('../utils/customFunctionParser'
  * @returns {Promise<Array>} Array of tracking events found in the file
  * @throws {Error} If the file cannot be read or parsed
  */
-async function analyzeGoFile(filePath, customFunctionSignature) {
+async function analyzeGoFile(filePath, customFunctionSignatures = null) {
   try {
-    const customConfig = customFunctionSignature ? parseCustomFunctionSignature(customFunctionSignature) : null;
+    // temporary: only support one custom function signature for now, will add support for multiple in the future
+    const customConfig = !!customFunctionSignatures?.length ? customFunctionSignatures[0] : null;
 
     // Read the Go file
     const source = fs.readFileSync(filePath, 'utf8');

src/analyze/index.js

@@ -5,16 +5,19 @@
 
 const path = require('path');
 const ts = require('typescript');
+const { parseCustomFunctionSignature } = require('./utils/customFunctionParser');
 const { getAllFiles } = require('../utils/fileProcessor');
 const { analyzeJsFile } = require('./javascript');
 const { analyzeTsFile } = require('./typescript');
 const { analyzePythonFile } = require('./python');
 const { analyzeRubyFile } = require('./ruby');
 const { analyzeGoFile } = require('./go');
 
-async function analyzeDirectory(dirPath, customFunction) {
+async function analyzeDirectory(dirPath, customFunctions) {
   const allEvents = {};
 
+  const customFunctionSignatures = (customFunctions && customFunctions?.length > 0) ? customFunctions.map(parseCustomFunctionSignature) : null;
+
   const files = getAllFiles(dirPath);
   const tsFiles = files.filter(file => /\.(tsx?)$/.test(file));
   const tsProgram = ts.createProgram(tsFiles, {
@@ -32,15 +35,15 @@ async function analyzeDirectory(dirPath, customFunction) {
     const isGoFile = /\.(go)$/.test(file);
 
     if (isJsFile) {
-      events = analyzeJsFile(file, customFunction);
+      events = analyzeJsFile(file, customFunctionSignatures);
     } else if (isTsFile) {
-      events = analyzeTsFile(file, tsProgram, customFunction);
+      events = analyzeTsFile(file, tsProgram, customFunctionSignatures);
     } else if (isPythonFile) {
-      events = await analyzePythonFile(file, customFunction);
+      events = await analyzePythonFile(file, customFunctionSignatures);
     } else if (isRubyFile) {
-      events = await analyzeRubyFile(file, customFunction);
+      events = await analyzeRubyFile(file, customFunctionSignatures);
     } else if (isGoFile) {
-      events = await analyzeGoFile(file, customFunction);
+      events = await analyzeGoFile(file, customFunctionSignatures);
     } else {
       continue;
     }

src/analyze/javascript/index.js

@@ -4,17 +4,18 @@
  */
 
 const { parseFile, findTrackingEvents, FileReadError, ParseError } = require('./parser');
-const { parseCustomFunctionSignature } = require('../utils/customFunctionParser');
 
 /**
  * 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, customFunctionSignature) {
+function analyzeJsFile(filePath, customFunctionSignatures = null) {
   const events = [];
-  const customConfig = customFunctionSignature ? parseCustomFunctionSignature(customFunctionSignature) : null;
+
+  // temporary: only support one custom function signature for now, will add support for multiple in the future
+  const customConfig = !!customFunctionSignatures?.length ? customFunctionSignatures[0] : null;
 
   try {
     // Parse the file into an AST

src/analyze/python/index.js

@@ -5,7 +5,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseCustomFunctionSignature } = require('../utils/customFunctionParser');
 
 // Singleton instance of Pyodide
 let pyodide = null;
@@ -53,8 +52,9 @@ async function initPyodide() {
  * // With custom tracking function
  * const events = await analyzePythonFile('./app.py', 'track_event');
  */
-async function analyzePythonFile(filePath, customFunctionSignature = null) {
-  const customConfig = customFunctionSignature ? parseCustomFunctionSignature(customFunctionSignature) : null;
+async function analyzePythonFile(filePath, customFunctionSignatures = null) {
+  // temporary: only support one custom function signature for now, will add support for multiple in the future
+  const customConfig = !!customFunctionSignatures?.length ? customFunctionSignatures[0] : null;
 
   // Validate inputs
   if (!filePath || typeof filePath !== 'string') {

src/analyze/ruby/index.js

@@ -5,7 +5,6 @@
 
 const fs = require('fs');
 const TrackingVisitor = require('./visitor');
-const { parseCustomFunctionSignature } = require('../utils/customFunctionParser');
 
 // Lazy-loaded parse function from Ruby Prism
 let parse = null;
@@ -17,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, customFunctionSignature) {
+async function analyzeRubyFile(filePath, customFunctionSignatures = null) {
   // Lazy load the Ruby Prism parser
   if (!parse) {
     const { loadPrism } = await import('@ruby/prism');
@@ -37,8 +36,10 @@ async function analyzeRubyFile(filePath, customFunctionSignature) {
       return []; // Return empty events array if parsing fails
     }
 
+    // temporary: only support one custom function signature for now, will add support for multiple in the future
+    const customConfig = !!customFunctionSignatures?.length ? customFunctionSignatures[0] : null;
+
     // Create a visitor and analyze the AST
-    const customConfig = customFunctionSignature ? parseCustomFunctionSignature(customFunctionSignature) : null;
     const visitor = new TrackingVisitor(code, filePath, customConfig);
     const events = await visitor.analyze(ast);
 

src/analyze/typescript/index.js

@@ -4,7 +4,6 @@
  */
 
 const { getProgram, findTrackingEvents, ProgramError, SourceFileError } = require('./parser');
-const { parseCustomFunctionSignature } = require('../utils/customFunctionParser');
 
 /**
  * Analyzes a TypeScript file for analytics tracking calls
@@ -13,9 +12,11 @@ const { parseCustomFunctionSignature } = require('../utils/customFunctionParser'
  * @param {string} [customFunctionSignature] - Optional custom function signature to detect
  * @returns {Array<Object>} Array of tracking events found in the file
  */
-function analyzeTsFile(filePath, program = null, customFunctionSignature = null) {
+function analyzeTsFile(filePath, program = null, customFunctionSignatures = null) {
   const events = [];
-  const customConfig = customFunctionSignature ? parseCustomFunctionSignature(customFunctionSignature) : null;
+
+  // temporary: only support one custom function signature for now, will add support for multiple in the future
+  const customConfig = !!customFunctionSignatures?.length ? customFunctionSignatures[0] : null;
 
   try {
     // Get or create TypeScript program

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') {

tests/analyzeGo.test.js

@@ -2,14 +2,16 @@ const test = require('node:test');
 const assert = require('node:assert');
 const path = require('path');
 const { analyzeGoFile } = require('../src/analyze/go');
+const { parseCustomFunctionSignature } = require('../src/analyze/utils/customFunctionParser');
 
 test.describe('analyzeGoFile', () => {
   const fixturesDir = path.join(__dirname, 'fixtures');
   const testFilePath = path.join(fixturesDir, 'go', 'main.go');
 
   test('should correctly analyze Go file with multiple tracking providers', async () => {
     const customFunction = 'customTrackFunction(userId, EVENT_NAME, PROPERTIES)';
-    const events = await analyzeGoFile(testFilePath, customFunction);
+    const customFunctionSignatures = [parseCustomFunctionSignature(customFunction)];
+    const events = await analyzeGoFile(testFilePath, customFunctionSignatures);
 
     // Sort events by eventName for consistent ordering
     events.sort((a, b) => a.eventName.localeCompare(b.eventName));
@@ -103,7 +105,8 @@ test.describe('analyzeGoFile', () => {
 
   test('should handle files without tracking events', async () => {
     const emptyTestFile = path.join(fixturesDir, 'go', 'empty.go');
-    const events = await analyzeGoFile(emptyTestFile, 'customTrack');
+    const customFunctionSignatures = [parseCustomFunctionSignature('customTrack')];
+    const events = await analyzeGoFile(emptyTestFile, customFunctionSignatures);
     assert.deepStrictEqual(events, []);
   });
 
@@ -117,7 +120,8 @@ test.describe('analyzeGoFile', () => {
 
   test('should handle nested property types correctly', async () => {
     const customFunction = 'customTrackFunction(userId, EVENT_NAME, PROPERTIES)';
-    const events = await analyzeGoFile(testFilePath, customFunction);
+    const customFunctionSignatures = [parseCustomFunctionSignature(customFunction)];
+    const events = await analyzeGoFile(testFilePath, customFunctionSignatures);
 
     const customEvent = events.find(e => e.eventName === 'custom_event');
     assert.ok(customEvent);
@@ -141,7 +145,8 @@ test.describe('analyzeGoFile', () => {
 
   test('should match expected tracking-schema.yaml output', async () => {
     const customFunction = 'customTrackFunction(userId, EVENT_NAME, PROPERTIES)';
-    const events = await analyzeGoFile(testFilePath, customFunction);
+    const customFunctionSignatures = [parseCustomFunctionSignature(customFunction)];
+    const events = await analyzeGoFile(testFilePath, customFunctionSignatures);
 
     // Create a map of events by name for easier verification
     const eventMap = {};
@@ -252,7 +257,8 @@ test.describe('analyzeGoFile', () => {
     ];
 
     for (const { sig, event } of variants) {
-      const events = await analyzeGoFile(testFilePath, sig);
+      const customFunctionSignatures = [parseCustomFunctionSignature(sig)];
+      const events = await analyzeGoFile(testFilePath, customFunctionSignatures);
       const found = events.find(e => e.eventName === event && e.source === 'custom');
       assert.ok(found, `Should detect ${event} for signature ${sig}`);
     }