add cli usage help

fliskdata · Sep 11, 2024 · cf14cbc · cf14cbc
1 parent 2fce308
commit cf14cbc
Show file tree

Hide file tree

Showing 5 changed files with 677 additions and 129 deletions.
diff --git a/README.md b/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!
diff --git a/bin/cli.js b/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,14 +31,19 @@ const optionDefinitions = [
   },
   {
     name: 'commitHash',
-    alias: 'h',
+    alias: 's',
     type: String,
   },
   {
     name: 'commitTimestamp',
     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);
 }