@flisk/analyze-tracking 0.2.6 → 0.2.8

package/README.md

@@ -1,32 +1,49 @@
 # @flisk/analyze-tracking
 
-Analyzes tracking code in a project and generates data schemas
+Automatically document your analytics setup by analyzing tracking code and generating data schemas from tools like Segment, Amplitude, Mixpanel, and more 🚀.
 
 [![NPM version](https://img.shields.io/npm/v/@flisk/analyze-tracking.svg)](https://www.npmjs.com/package/@flisk/analyze-tracking)
 
 
-## Usage
+## Why Use @flisk/analyze-tracking?
+📊 **Understand Your Tracking** – Effortlessly analyze your codebase for `track` calls so you can see all your analytics events, properties, and triggers in one place. No more guessing what’s being tracked!
+
+🔍 **Auto-Document Events** – Generates a complete YAML schema that captures all events and properties, including where they’re implemented in your codebase.
+
+🕵️‍♂️ **Track Changes Over Time** – Easily spot unintended changes or ensure your analytics setup remains consistent across updates.
+
+📚 **Populate Data Catalogs** – Automatically generate structured documentation that can help feed into your data catalog, making it easier for everyone to understand your events.
+
+
+## Quick Start
+
+Run without installation! Just use:
+
 ```sh
 npx @flisk/analyze-tracking /path/to/project [options]
 ```
 
-Optional arguments:
+### Key Options:
 - `-o, --output <output_file>`: Name of the output file (default: `tracking-schema.yaml`)
-- `-c, --customFunction <function_name>`: Name of your custom tracking function
-- `-u, --repositoryUrl <git_url>`: URL to your repository
-- `-h, --commitHash <commit_sha>`: Latest commit hash
-- `-t, --commitTimestamp <iso_timestamp>`: Timestamp of latest commit
-
-Note: Custom Functions only support the following format:
-```js
-yourCustomTrackFunctionName('<event_name>', {
-  <event_parameters>
-});
-```
+- `-c, --customFunction <function_name>`: Specify a custom tracking function
+
+<details>
+  <summary>Note on Custom Functions 💡</summary>
 
+  Use this if you have your own in-house tracker or a wrapper function that calls other tracking libraries.
 
-## Output Schema
-A YAML file with the following structure is generated:
+  We currently only support functions that follow the following format:
+  ```js
+  yourCustomTrackFunctionName('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+
+## What’s Generated?
+A clear YAML schema that shows where your events are tracked, their properties, and more.
+Here’s an example:
 
 ```yaml
 version: 1
@@ -44,116 +61,141 @@ events:
     properties:
       <property_name>:
         type: <property_type>
-        required: <property_required>
-        description: <property_description>
 ```
 
-See [schema.json](schema.json) for the output schema.
+Use this to understand where your events live in the code and how they’re being tracked.
 
+See [schema.json](schema.json) for a JSON Schema of the output.
 
-## Supported tracking libraries
-
-#### Google Analytics
-```js
-gtag('event', '<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Segment
-```js
-analytics.track('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Mixpanel
-```js
-mixpanel.track('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Amplitude
-```js
-amplitude.logEvent('<event_name>', {
-  <event_parameters>
-});
-```
 
+## Supported tracking libraries
 
-#### Rudderstack
-```js
-rudderanalytics.track('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### mParticle
-```js
-mParticle.logEvent('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### PostHog
-```js
-posthog.capture('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Pendo
-```js
-pendo.track('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Heap
-```js
-heap.track('<event_name>', {
-  <event_parameters>
-});
-```
-
-
-#### Snowplow
-```js
-snowplow('trackStructEvent', {
-  category: '<category>',
-  action: '<action>',
-  label: '<label>',
-  property: '<property>',
-  value: '<value> '
-});
-```
-
-```js
-trackStructEvent({
-  category: '<category>',
-  action: '<action>',
-  label: '<label>',
-  property: '<property>',
-  value: '<value>'
-});
-```
-
-```js
-buildStructEvent({
-  category: '<category>',
-  action: '<action>',
-  label: '<label>',
-  property: '<property>',
-  value: '<value>'
-});
-```
-
-_Note: Snowplow Self Describing Events are not supported yet._
+<details>
+  <summary>Google Analytics</summary>
+
+  ```js
+  gtag('event', '<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Segment</summary>
+
+  ```js
+  analytics.track('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Mixpanel</summary>
+
+  ```js
+  mixpanel.track('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Amplitude</summary>
+
+  ```js
+  amplitude.logEvent('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Rudderstack</summary>
+
+  ```js
+  rudderanalytics.track('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>mParticle</summary>
+
+  ```js
+  mParticle.logEvent('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>PostHog</summary>
+
+  ```js
+  posthog.capture('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Pendo</summary>
+
+  ```js
+  pendo.track('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Heap</summary>
+
+  ```js
+  heap.track('<event_name>', {
+    <event_parameters>
+  });
+  ```
+</details>
+
+<details>
+  <summary>Snowplow (struct events)</summary>
+
+  ```js
+  snowplow('trackStructEvent', {
+    category: '<category>',
+    action: '<action>',
+    label: '<label>',
+    property: '<property>',
+    value: '<value> '
+  });
+  ```
+
+  ```js
+  trackStructEvent({
+    category: '<category>',
+    action: '<action>',
+    label: '<label>',
+    property: '<property>',
+    value: '<value>'
+  });
+  ```
+
+  ```js
+  buildStructEvent({
+    category: '<category>',
+    action: '<action>',
+    label: '<label>',
+    property: '<property>',
+    value: '<value>'
+  });
+  ```
+
+  _Note: Snowplow Self Describing Events are coming soon!_
+</details>
+
+
+## Contribute
+We’re actively improving this package. Found a bug? Want to request a feature? Open an issue or contribute directly!

package/bin/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 const path = require('path');
-const commandLineArgs = require('command-line-args')
+const commandLineArgs = require('command-line-args');
+const commandLineUsage = require('command-line-usage');
 const { run } = require('../src/index');
+const { helpContent } = require('./help');
 
 // Parse command-line arguments
 const optionDefinitions = [
@@ -29,7 +31,7 @@ const optionDefinitions = [
   },
   {
     name: 'commitHash',
-    alias: 'h',
+    alias: 's',
     type: String,
   },
   {
@@ -37,6 +39,11 @@ const optionDefinitions = [
     alias: 't',
     type: String,
   },
+  {
+    name: 'help',
+    alias: 'h',
+    type: Boolean,
+  },
 ]
 const options = commandLineArgs(optionDefinitions);
 const {
@@ -46,8 +53,14 @@ const {
   repositoryUrl,
   commitHash,
   commitTimestamp,
+  help,
 } = options;
 
+if (help) {
+  console.log(commandLineUsage(helpContent));
+  process.exit(0);
+}
+
 const customSourceDetails = {
   repositoryUrl,
   commitHash,
@@ -56,6 +69,7 @@ const customSourceDetails = {
 
 if (!targetDir) {
   console.error('Please provide the path to the repository.');
+  console.log(commandLineUsage(helpContent));
   process.exit(1);
 }
 

package/bin/help.js

@@ -0,0 +1,64 @@
+const header =
+`                                                                                                                                                                                                                            
+\u001b[38;5;2m                  ▒▒                   \u001b[39m                                                                       
+\u001b[38;5;2m                 ▒▒▒▒                  \u001b[39m                                                                       
+\u001b[38;5;2m                 ▒▒▒▒                  \u001b[39m       ████████  ██████    ██████                   ██████             
+\u001b[38;5;2m                 ▒▒▒▒                  \u001b[39m     ██████████  ██████    ██████                   ██████             
+\u001b[38;5;2m                ▒▒▒▒▒▒                 \u001b[39m    ███████████  ██████    ██████                   ██████             
+\u001b[38;5;2m                ▒▒▒▒▒▒                 \u001b[39m    ██████       ██████                             ██████             
+\u001b[38;5;2m               ▒▒▒▒▒▒▒▒                \u001b[39m ██████████████  ██████    ██████     █████████     ██████     ██████  
+\u001b[38;5;2m              ▒▒▒▒▒▒▒▒▒▒               \u001b[39m ██████████████  ██████    ██████   █████████████   ██████   ███████   
+\u001b[38;5;2m             ▒▒▒▒▒▒▒▒▒▒▒▒              \u001b[39m ██████████████  ██████    ██████  ███████  ████    ██████ ████████    
+\u001b[38;5;2m         ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒           \u001b[39m    ██████       ██████    ██████  ████████         █████████████      
+\u001b[38;5;2m  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    \u001b[39m    ██████       ██████    ██████   ███████████     ████████████       
+\u001b[38;5;2m ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓   \u001b[39m    ██████       ██████    ██████     ███████████   █████████████      
+\u001b[38;5;2m     ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓         \u001b[39m    ██████       ██████    ██████          ██████   ███████ ██████     
+\u001b[38;5;2m          ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓             \u001b[39m    ██████       ██████    ██████   ████   ██████   ██████   ██████    
+\u001b[38;5;2m             ▓▓▓▓▓▓▓▓▓▓▓▓              \u001b[39m    ██████       ██████    ██████  ██████████████   ██████    ███████  
+\u001b[38;5;2m              ▓▓▓▓▓▓▓▓▓▓               \u001b[39m    ██████       ██████    ██████    ██████████     ██████     ███████ 
+\u001b[38;5;2m               ▓▓▓▓▓▓▓▓                \u001b[39m                                                                       
+\u001b[38;5;2m                ▓▓▓▓▓▓                 \u001b[39m                                                                       
+`;
+
+const helpContent = [
+  {
+    content: header,
+    raw: true
+  },
+  {
+    header: '@flisk/analyze-tracking',
+    content: 'Automatically document your analytics setup by analyzing tracking code and generating data schemas from tools like Segment, Amplitude, Mixpanel, and more 🚀'
+  },
+  {
+    header: 'Options',
+    optionList: [
+      {
+        name: 'help',
+        alias: 'h',
+        description: 'Display this usage guide.',
+        type: Boolean
+      },
+      {
+        name: 'output',
+        alias: 'o',
+        description: 'Name of the output file.',
+        type: String,
+        defaultOption: true,
+        typeLabel: '{underline tracking-schema.yaml}'
+      },
+      {
+        name: 'customFunction',
+        alias: 'c',
+        description: 'Specify a custom tracking function.',
+        type: String,
+        typeLabel: '{underline yourCustomFunctionName}'
+      }
+    ]
+  },
+  {
+    header: 'Project Home',
+    content: '{underline https://github.com/fliskdata/analyze-tracking}'
+  }
+];
+
+module.exports = { helpContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk/analyze-tracking",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Analyzes tracking code in a project and generates data schemas",
   "main": "src/index.js",
   "bin": {
@@ -26,6 +26,7 @@
     "acorn-jsx-walk": "^2.0.0",
     "acorn-walk": "^8.3.3",
     "command-line-args": "^6.0.0",
+    "command-line-usage": "^7.0.3",
     "isomorphic-git": "^1.27.1",
     "js-yaml": "^4.1.0",
     "typescript": "^5.5.4"

package/src/analyze/helpers.js

@@ -139,8 +139,9 @@ function extractJsProperties(node) {
 function extractTsProperties(checker, node) {
   const properties = {};
 
-  node.properties.forEach((prop) => {
-    const key = prop.name ? prop.name.text : prop.key.text || prop.key.value;
+  for (const prop of node.properties) {
+    const key = !!prop.name ? prop.name.text : (!!prop.key ? (prop.key.text || prop.key.value) : undefined);
+    if (!key) continue;
     let valueType = 'any';
 
     if (ts.isShorthandPropertyAssignment(prop)) {
@@ -195,7 +196,7 @@ function extractTsProperties(checker, node) {
       valueType = checker.typeToString(checker.getTypeFromTypeNode(prop.type)) || 'any';
       properties[key] = { type: valueType };
     }
-  });
+  }
 
   return properties;
 }