@flisk/analyze-tracking 0.2.8 → 0.3.0

package/README.md

@@ -24,9 +24,12 @@ npx @flisk/analyze-tracking /path/to/project [options]
 ```
 
 ### Key Options:
+- `-g, --generateDescription`: Generate descriptions of fields (default: `false`)
 - `-o, --output <output_file>`: Name of the output file (default: `tracking-schema.yaml`)
 - `-c, --customFunction <function_name>`: Specify a custom tracking function
 
+🔑&nbsp; **Important:** you must set the `OPENAI_API_KEY` environment variable to use `generateDescription`
+
 <details>
   <summary>Note on Custom Functions 💡</summary>
 
@@ -53,18 +56,23 @@ source:
   timestamp: <commit_timestamp>
 events:
   <event_name>:
+    description: <ai_generated_description>
     implementations:
-      - path: <path_to_file>
+      - description: <ai_generated_description>
+        path: <path_to_file>
         line: <line_number>
         function: <function_name>
         destination: <platform_name>
     properties:
       <property_name>:
+        description: <ai_generated_description>
         type: <property_type>
 ```
 
 Use this to understand where your events live in the code and how they’re being tracked.
 
+[GPT-4o mini](https://platform.openai.com/docs/models/gpt-4o-mini) is used for generating descriptions of events, properties, and implementations.
+
 See [schema.json](schema.json) for a JSON Schema of the output.
 
 

package/bin/cli.js

@@ -13,6 +13,12 @@ const optionDefinitions = [
     type: String,
     defaultOption: true,
   },
+  {
+    name: 'generateDescription',
+    alias: 'g',
+    type: Boolean,
+    defaultValue: false,
+  },
   {
     name: 'output',
     alias: 'o',
@@ -48,6 +54,7 @@ const optionDefinitions = [
 const options = commandLineArgs(optionDefinitions);
 const {
   targetDir,
+  generateDescription,
   output,
   customFunction,
   repositoryUrl,
@@ -73,4 +80,11 @@ if (!targetDir) {
   process.exit(1);
 }
 
-run(path.resolve(targetDir), output, customFunction, customSourceDetails);
+if (generateDescription) {
+  if (!process.env.OPENAI_API_KEY) {
+    console.error('Please set the `OPENAI_API_KEY` environment variable to use `generateDescription`.');
+    process.exit(1);
+  }
+}
+
+run(path.resolve(targetDir), output, customFunction, customSourceDetails, generateDescription);

package/bin/help.js

@@ -38,6 +38,14 @@ const helpContent = [
         description: 'Display this usage guide.',
         type: Boolean
       },
+      {
+        name: 'generateDescription',
+        alias: 'g',
+        description: 'Generate descriptions of fields.',
+        type: Boolean,
+        defaultValue: false,
+        typeLabel: '{underline false}'
+      },
       {
         name: 'output',
         alias: 'o',
@@ -51,7 +59,7 @@ const helpContent = [
         alias: 'c',
         description: 'Specify a custom tracking function.',
         type: String,
-        typeLabel: '{underline yourCustomFunctionName}'
+        typeLabel: '{italic yourCustomFunctionName}'
       }
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk/analyze-tracking",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Analyzes tracking code in a project and generates data schemas",
   "main": "src/index.js",
   "bin": {
@@ -29,7 +29,9 @@
     "command-line-usage": "^7.0.3",
     "isomorphic-git": "^1.27.1",
     "js-yaml": "^4.1.0",
-    "typescript": "^5.5.4"
+    "openai": "^4.67.1",
+    "typescript": "^5.5.4",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/analyze/analyzeJsFile.js

@@ -10,47 +10,61 @@ const parserOptions = { ecmaVersion: 'latest', sourceType: 'module', locations:
 extend(walk.base);
 
 function analyzeJsFile(filePath, customFunction) {
-  const code = fs.readFileSync(filePath, 'utf8');
-  const ast = parser.parse(code, parserOptions);
-  const events = [];
-
-  walk.ancestor(ast, {
-    CallExpression(node, ancestors) {
-      const source = detectSourceJs(node, customFunction);
-      if (source === 'unknown') return;
-
-      let eventName = null;
-      let propertiesNode = null;
-
-      if (source === 'googleanalytics' && node.arguments.length >= 3) {
-        eventName = node.arguments[1]?.value || null;
-        propertiesNode = node.arguments[2];
-      } else if (source === 'snowplow' && node.arguments.length >= 2) {
-        const actionProperty = node.arguments[1].properties.find(prop => prop.key.name === 'action');
-        eventName = actionProperty ? actionProperty.value.value : null;
-        propertiesNode = node.arguments[1];
-      } else if (node.arguments.length >= 2) {
-        eventName = node.arguments[0]?.value || null;
-        propertiesNode = node.arguments[1];
-      }
-
-      const line = node.loc.start.line;
-      const functionName = findWrappingFunctionJs(node, ancestors);
-
-      if (eventName && propertiesNode && propertiesNode.type === 'ObjectExpression') {
-        const properties = extractJsProperties(propertiesNode);
-
-        events.push({
-          eventName,
-          source,
-          properties,
-          filePath,
-          line,
-          functionName
-        });
-      }
-    },
-  });
+  let events = [];
+  try {
+    const code = fs.readFileSync(filePath, 'utf8');
+    let ast;
+    try {
+      ast = parser.parse(code, parserOptions);
+    } catch (parseError) {
+      console.error(`Error parsing file ${filePath}`);
+      return events; // Return empty events array if parsing fails
+    }
+
+    walk.ancestor(ast, {
+      CallExpression(node, ancestors) {
+        try {
+          const source = detectSourceJs(node, customFunction);
+          if (source === 'unknown') return;
+
+          let eventName = null;
+          let propertiesNode = null;
+
+          if (source === 'googleanalytics' && node.arguments.length >= 3) {
+            eventName = node.arguments[1]?.value || null;
+            propertiesNode = node.arguments[2];
+          } else if (source === 'snowplow' && node.arguments.length >= 2) {
+            const actionProperty = node.arguments[1].properties.find(prop => prop.key.name === 'action');
+            eventName = actionProperty ? actionProperty.value.value : null;
+            propertiesNode = node.arguments[1];
+          } else if (node.arguments.length >= 2) {
+            eventName = node.arguments[0]?.value || null;
+            propertiesNode = node.arguments[1];
+          }
+
+          const line = node.loc.start.line;
+          const functionName = findWrappingFunctionJs(node, ancestors);
+
+          if (eventName && propertiesNode && propertiesNode.type === 'ObjectExpression') {
+            const properties = extractJsProperties(propertiesNode);
+
+            events.push({
+              eventName,
+              source,
+              properties,
+              filePath,
+              line,
+              functionName
+            });
+          }
+        } catch (nodeError) {
+          console.error(`Error processing node in ${filePath}`);
+        }
+      },
+    });
+  } catch (fileError) {
+    console.error(`Error reading or processing file ${filePath}`);
+  }
 
   return events;
 }

package/src/analyze/analyzeTsFile.js

@@ -2,49 +2,66 @@ const ts = require('typescript');
 const { detectSourceTs, findWrappingFunctionTs, extractTsProperties } = require('./helpers');
 
 function analyzeTsFile(filePath, program, customFunction) {
-  const sourceFile = program.getSourceFile(filePath);
-  const checker = program.getTypeChecker();
-  const events = [];
-
-  function visit(node) {
-    if (ts.isCallExpression(node)) {
-      const source = detectSourceTs(node, customFunction);
-      if (source === 'unknown') return;
-
-      let eventName = null;
-      let propertiesNode = null;
-
-      if (source === 'googleanalytics' && node.arguments.length >= 3) {
-        eventName = node.arguments[1]?.text || null;
-        propertiesNode = node.arguments[2];
-      } else if (source === 'snowplow' && node.arguments.length >= 2) {
-        const actionProperty = node.arguments[1].properties.find(prop => prop.name.escapedText === 'action');
-        eventName = actionProperty ? actionProperty.initializer.text : null;
-        propertiesNode = node.arguments[1];
-      } else if (node.arguments.length >= 2) {
-        eventName = node.arguments[0]?.text || null;
-        propertiesNode = node.arguments[1];
-      }
+  let events = [];
+  try {
+    const sourceFile = program.getSourceFile(filePath);
+    if (!sourceFile) {
+      console.error(`Error: Unable to get source file for ${filePath}`);
+      return events;
+    }
+
+    const checker = program.getTypeChecker();
+
+    function visit(node) {
+      try {
+        if (ts.isCallExpression(node)) {
+          const source = detectSourceTs(node, customFunction);
+          if (source === 'unknown') return;
+
+          let eventName = null;
+          let propertiesNode = null;
 
-      const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
-      const functionName = findWrappingFunctionTs(node);
-
-      if (eventName && propertiesNode && ts.isObjectLiteralExpression(propertiesNode)) {
-        const properties = extractTsProperties(checker, propertiesNode);
-        events.push({
-          eventName,
-          source,
-          properties,
-          filePath,
-          line,
-          functionName
-        });
+          if (source === 'googleanalytics' && node.arguments.length >= 3) {
+            eventName = node.arguments[1]?.text || null;
+            propertiesNode = node.arguments[2];
+          } else if (source === 'snowplow' && node.arguments.length >= 2) {
+            const actionProperty = node.arguments[1].properties.find(prop => prop.name.escapedText === 'action');
+            eventName = actionProperty ? actionProperty.initializer.text : null;
+            propertiesNode = node.arguments[1];
+          } else if (node.arguments.length >= 2) {
+            eventName = node.arguments[0]?.text || null;
+            propertiesNode = node.arguments[1];
+          }
+
+          const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
+          const functionName = findWrappingFunctionTs(node);
+
+          if (eventName && propertiesNode && ts.isObjectLiteralExpression(propertiesNode)) {
+            try {
+              const properties = extractTsProperties(checker, propertiesNode);
+              events.push({
+                eventName,
+                source,
+                properties,
+                filePath,
+                line,
+                functionName
+              });
+            } catch (propertyError) {
+              console.error(`Error extracting properties in ${filePath} at line ${line}`);
+            }
+          }
+        }
+        ts.forEachChild(node, visit);
+      } catch (nodeError) {
+        console.error(`Error processing node in ${filePath}`);
       }
     }
-    ts.forEachChild(node, visit);
-  }
 
-  ts.forEachChild(sourceFile, visit);
+    ts.forEachChild(sourceFile, visit);
+  } catch (fileError) {
+    console.error(`Error analyzing TypeScript file ${filePath}`);
+  }
 
   return events;
 }

package/src/generateDescriptions.js

@@ -0,0 +1,162 @@
+const fs = require('fs');
+const path = require('path');
+const OpenAI = require('openai');
+const { z } = require('zod');
+const { zodResponseFormat } = require('openai/helpers/zod');
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+function createPrompt(eventName, properties, implementations, codebaseDir) {
+  // Initialize the prompt
+  let prompt = `You are an expert at structured data extraction. Generate detailed descriptions for the following analytics event, its properties, and implementations.\n\n`;
+
+  // Add event name
+  prompt += `Event Name: "${eventName}"\n\n`;
+
+  // Add properties
+  prompt += `Properties:\n`;
+  for (const propName in properties) {
+    const prop = properties[propName];
+    prompt += `- "${propName}" (type: ${prop.type})\n`;
+  }
+
+  // Add implementations with code snippets
+  prompt += `\nImplementations:\n`;
+  for (const impl of implementations) {
+    const codeSnippet = getCodeSnippet(path.join(codebaseDir, impl.path), impl.line);
+    prompt += `- Path: "${impl.path}", Line: ${impl.line}, Function: "${impl.function}", Destination: "${impl.destination}"\n`;
+    prompt += `Code Snippet:\n`;
+    prompt += '```\n';
+    prompt += codeSnippet + '\n';
+    prompt += '```\n';
+  }
+
+  return prompt;
+}
+
+function getCodeSnippet(filePath, lineNumber, contextLines = 5) {
+  // Extract a code snippet from the file around the specified line
+  try {
+    const fileContent = fs.readFileSync(filePath, 'utf8');
+    const lines = fileContent.split('\n');
+    const startLine = Math.max(0, lineNumber - contextLines - 1);
+    const endLine = Math.min(lines.length, lineNumber + contextLines);
+
+    const snippetLines = lines.slice(startLine, endLine);
+    return snippetLines.join('\n');
+  } catch (e) {
+    console.error(`Failed to read file ${filePath}:`, e);
+    return '';
+  }
+}
+
+function createEventDescriptionSchema(properties) {
+  // Define the schema for properties
+  const propertiesSchema = {};
+  for (const propName in properties) {
+    propertiesSchema[propName] = z.object({
+      description: z.string().describe('A maximum of 10 words describing the property and what it means'),
+    });
+  }
+
+  // Define the schema for implementations
+  const implementationsSchema = z.array(
+    z.object({
+      description: z.string().describe('A maximum of 10 words describing when this event is triggered'),
+      path: z.string(),
+      line: z.number(),
+    })
+  );
+
+  // Construct the full schema
+  const eventDescriptionSchema = z.object({
+    eventDescription: z.string().describe('A maximum of 10 words describing the event and what it describes'),
+    properties: z.object(propertiesSchema),
+    implementations: implementationsSchema,
+  });
+
+  return eventDescriptionSchema;
+}
+
+async function sendPromptToLLM(prompt, schema) {
+  try {
+    const completion = await openai.beta.chat.completions.parse({
+      model: 'gpt-4o-mini',
+      messages: [
+        {
+          role: 'system',
+          content: 'You are an expert at structured data extraction. Generate detailed descriptions for the following analytics event, its properties, and implementations',
+        },
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+      response_format: zodResponseFormat(schema, 'event_description'),
+    });
+
+    return completion.choices[0].message.parsed;
+  } catch (error) {
+    console.error('Error during LLM response parsing:', error);
+    return null;
+  }
+}
+
+async function generateEventDescription(eventName, event, codebaseDir) {
+  const properties = event.properties || {};
+  const implementations = event.implementations || [];
+
+  // Create prompt for the LLM
+  const prompt = createPrompt(eventName, properties, implementations, codebaseDir);
+
+  // Define the output schema using Zod
+  const eventDescriptionSchema = createEventDescriptionSchema(properties);
+
+  // Send prompt to the LLM and get the structured response
+  const descriptions = await sendPromptToLLM(prompt, eventDescriptionSchema);
+
+  return { eventName, descriptions };
+}
+
+async function generateDescriptions(events, codebaseDir) {
+  const eventPromises = Object.entries(events).map(([eventName, event]) =>
+    generateEventDescription(eventName, event, codebaseDir)
+  );
+
+  const results = await Promise.all(eventPromises);
+
+  // Process results and update the events object
+  results.forEach(({ eventName, descriptions }) => {
+    if (descriptions) {
+      const event = events[eventName];
+      event.description = descriptions.eventDescription;
+
+      // Update property descriptions
+      for (const propName in descriptions.properties) {
+        if (event.properties[propName]) {
+          event.properties[propName].description = descriptions.properties[propName].description;
+        }
+      }
+
+      // Update implementations with descriptions
+      for (let i = 0; i < descriptions.implementations.length; i++) {
+        if (event.implementations[i]) {
+          if (event.implementations[i].path === descriptions.implementations[i].path && 
+              event.implementations[i].line === descriptions.implementations[i].line) {
+            event.implementations[i].description = descriptions.implementations[i].description;
+          } else {
+            console.error(`Returned implementation description does not match path or line for event: ${eventName}`);
+          }
+        }
+      }
+    } else {
+      console.error(`Failed to get description for event: ${eventName}`);
+    }
+  });
+
+  return events;
+}
+
+module.exports = { generateDescriptions };

package/src/index.js

@@ -1,9 +1,13 @@
 const { analyzeDirectory } = require('./analyze');
 const { getRepoDetails } = require('./repoDetails');
 const { generateYamlSchema } = require('./yamlGenerator');
+const { generateDescriptions } = require('./generateDescriptions');
 
-async function run(targetDir, outputPath, customFunction, customSourceDetails) {
-  const events = analyzeDirectory(targetDir, customFunction);
+async function run(targetDir, outputPath, customFunction, customSourceDetails, generateDescription) {
+  let events = analyzeDirectory(targetDir, customFunction);
+  if (generateDescription) {
+    events = await generateDescriptions(events, targetDir);
+  }
   const repoDetails = await getRepoDetails(targetDir, customSourceDetails);
   generateYamlSchema(events, repoDetails, outputPath);
 }

package/src/repoDetails.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const git = require('isomorphic-git');
+const { execSync } = require('child_process');
 
 async function getRepositoryUrl(targetDir) {
   try {
@@ -10,8 +11,13 @@ async function getRepositoryUrl(targetDir) {
     });
     return repoUrl.trim();
   } catch (error) {
-    console.warn('Could not determine repository URL. Will exclude.');
-    return null;
+    try {
+      const repoUrl = execSync('git config --get remote.origin.url', { cwd: targetDir, encoding: 'utf8' });
+      return repoUrl.trim();
+    } catch (error) {
+      console.warn('Could not determine repository URL. Will exclude.');
+      return null;
+    }
   }
 }
 
@@ -24,8 +30,13 @@ async function getCommitHash(targetDir) {
     });
     return commitHash.trim();
   } catch (error) {
-    console.warn('Could not determine latest commit hash. Will exclude.');
-    return null;
+    try {
+      const commitHash = execSync('git rev-parse HEAD', { cwd: targetDir, encoding: 'utf8' });
+      return commitHash.trim();
+    } catch (error) {
+      console.warn('Could not determine latest commit hash. Will exclude.');
+      return null;
+    }
   }
 }
 
@@ -39,8 +50,14 @@ async function getCommitTimestamp(targetDir, commitHash) {
     const unixTimeSeconds = commit.committer.timestamp;
     return new Date(unixTimeSeconds * 1000);
   } catch (error) {
-    console.warn('Could not retrieve commit timestamp. Using current timestamp as default.');
-    return new Date();
+    try {
+      const commitTimestamp = execSync(`git --no-pager show -s --format=%ct ${commitHash}`, { cwd: targetDir, encoding: 'utf8' });
+      const unixTimeSeconds = commitTimestamp.trim();
+      return new Date(unixTimeSeconds * 1000);
+    } catch (error) {
+      console.warn('Could not retrieve commit timestamp. Using current timestamp as default.');
+      return new Date();
+    }
   }
 }