@flisk/analyze-tracking 0.2.9 → 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.9",
+  "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/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);
 }