@flisk/analyze-tracking 0.2.9 → 0.3.1

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.1",
   "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/schema.json

@@ -71,6 +71,10 @@
                       "unknown"
                     ],
                     "description": "Name of the platform where the event is sent"
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Description of how the event is triggered"
                   }
                 },
                 "required": [
@@ -89,6 +93,10 @@
                   "$ref": "#/definitions/property"
                 }
               }
+            },
+            "description": {
+              "type": "string",
+              "description": "Description of the event"
             }
           },
           "required": [

package/src/generateDescriptions.js

@@ -0,0 +1,218 @@
+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,
+});
+const model = 'gpt-4o-mini';
+
+function createPrompt(eventName, properties, implementations, codebaseDir) {
+  let prompt = `Event Name: "${eventName}"\n\n`;
+  prompt += `Properties:\n`;
+
+  function appendPropertiesToPrompt(properties, indent = '') {
+    for (const propName in properties) {
+      const prop = properties[propName];
+      prompt += `${indent}- "${propName}" (type: ${prop.type})\n`;
+      if (prop.properties) {
+        prompt += `${indent}  Sub-properties:\n`;
+        appendPropertiesToPrompt(prop.properties, indent + '    ');
+      }
+    }
+  }
+
+  appendPropertiesToPrompt(properties);
+
+  // 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) {
+  function buildPropertySchema(prop) {
+    if (prop.properties) {
+      const subPropertiesSchema = {};
+      for (const subPropName in prop.properties) {
+        subPropertiesSchema[subPropName] = buildPropertySchema(prop.properties[subPropName]);
+      }
+      return z.object({
+        description: z
+          .string()
+          .describe('A maximum of 10 words describing the property and what it means'),
+        properties: z.object(subPropertiesSchema),
+      });
+    } else {
+      return z.object({
+        description: z
+          .string()
+          .describe('A maximum of 10 words describing the property and what it means'),
+      });
+    }
+  }
+
+  // Define the schema for properties
+  const propertiesSchema = {};
+  for (const propName in properties) {
+    propertiesSchema[propName] = buildPropertySchema(properties[propName]);
+  }
+
+  // Define the schema for implementations
+  const implementationsSchema = z.array(
+    z.object({
+      description: z
+        .string()
+        .describe('A maximum of 10 words describing how this event is triggered without using the word "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 tracks without using the word "tracks"'),
+    properties: z.object(propertiesSchema),
+    implementations: implementationsSchema,
+  });
+
+  return eventDescriptionSchema;
+}
+
+async function sendPromptToLLM(prompt, schema) {
+  try {
+    const completion = await openai.beta.chat.completions.parse({
+      model,
+      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 {
+      descriptions: completion.choices[0].message.parsed,
+      usage: completion.usage,
+    };
+  } 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, usage } = await sendPromptToLLM(prompt, eventDescriptionSchema);
+
+  return { eventName, descriptions, usage };
+}
+
+async function generateDescriptions(events, codebaseDir) {
+  console.log(`Generating descriptions using ${model}`);
+
+  const eventPromises = Object.entries(events).map(([eventName, event]) =>
+    generateEventDescription(eventName, event, codebaseDir)
+  );
+
+  console.log(`Running ${eventPromises.length} prompts in parallel...`);
+
+  const results = await Promise.all(eventPromises);
+
+  let promptTokens = 0;
+  let completionTokens = 0;
+
+  // Process results and update the events object
+  results.forEach(({ eventName, descriptions, usage }) => {
+    if (descriptions) {
+      promptTokens += usage.prompt_tokens;
+      completionTokens += usage.completion_tokens;
+
+      const event = events[eventName];
+      event.description = descriptions.eventDescription;
+
+      // Update property descriptions recursively
+      function updatePropertyDescriptions(eventProperties, descriptionProperties) {
+        for (const propName in descriptionProperties) {
+          if (eventProperties[propName]) {
+            eventProperties[propName].description = descriptionProperties[propName].description;
+            if (eventProperties[propName].properties && descriptionProperties[propName].properties) {
+              updatePropertyDescriptions(
+                eventProperties[propName].properties,
+                descriptionProperties[propName].properties
+              );
+            }
+          }
+        }
+      }
+
+      updatePropertyDescriptions(event.properties, descriptions.properties);
+
+      // 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}`);
+    }
+  });
+
+  console.log(`Prompt tokens used: ${promptTokens}`);
+  console.log(`Completion tokens used: ${completionTokens}`);
+  console.log(`Total tokens used: ${promptTokens + completionTokens}`);
+
+  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);
 }