@jtl-software/eslint-plugin-posthog 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Read .tool-versions
+        id: tool-versions
+        run: |
+          NODE_VERSION=$(grep nodejs .tool-versions | awk '{print $2}')
+          PNPM_VERSION=$(grep pnpm .tool-versions | awk '{print $2}')
+          echo "node-version=$NODE_VERSION" >> $GITHUB_OUTPUT
+          echo "pnpm-version=$PNPM_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.tool-versions.outputs.node-version }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ steps.tool-versions.outputs.pnpm-version }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+  publish:
+    name: Publish to npm
+    needs: test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Read .tool-versions
+        id: tool-versions
+        run: |
+          NODE_VERSION=$(grep nodejs .tool-versions | awk '{print $2}')
+          PNPM_VERSION=$(grep pnpm .tool-versions | awk '{print $2}')
+          echo "node-version=$NODE_VERSION" >> $GITHUB_OUTPUT
+          echo "pnpm-version=$PNPM_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.tool-versions.outputs.node-version }}
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ steps.tool-versions.outputs.pnpm-version }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check if version exists on npm
+        id: version-check
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          echo "package-version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
+
+          if npm view @jtl-software/eslint-plugin-posthog@$PACKAGE_VERSION version 2>/dev/null; then
+            echo "should-publish=false" >> $GITHUB_OUTPUT
+            echo "Version $PACKAGE_VERSION already exists on npm, skipping publish"
+          else
+            echo "should-publish=true" >> $GITHUB_OUTPUT
+            echo "Version $PACKAGE_VERSION not found on npm, will publish"
+          fi
+
+      - name: Publish to npm
+        if: steps.version-check.outputs.should-publish == 'true'
+        run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+*.log
+pnpm-lock.yaml

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
+  "printWidth": 90,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid",
+  "useTabs": false,
+  "tabWidth": 2
+}

package/.tool-versions

@@ -0,0 +1,2 @@
+nodejs 22.21.1
+pnpm 10.20.0

package/README.md

@@ -0,0 +1,134 @@
+# @jtl-software/eslint-plugin-posthog
+
+ESLint plugin for enforcing PostHog event tracking best practices.
+
+## Installation
+
+```bash
+npm install --save-dev @jtl-software/eslint-plugin-posthog
+```
+
+```bash
+yarn add -D @jtl-software/eslint-plugin-posthog
+```
+
+```bash
+pnpm add -D @jtl-software/eslint-plugin-posthog
+```
+
+## Usage
+
+### Flat Config (ESLint 9+)
+
+```js
+// eslint.config.js
+import posthog from '@jtl-software/eslint-plugin-posthog';
+
+export default [
+  posthog.configs.recommended,
+  {
+    // Your other config here
+  },
+];
+```
+
+### Legacy Config (.eslintrc)
+
+For ESLint 8 and below, add to your `.eslintrc.js` or `.eslintrc.json`:
+
+```js
+module.exports = {
+  plugins: ['@jtl-software/eslint-plugin-posthog'],
+  rules: {
+    '@jtl-software/posthog/consistent-property-naming': 'error',
+    '@jtl-software/posthog/valid-event-names': 'error',
+  },
+};
+```
+
+## Rules
+
+| Rule                                                                     | Description                            | Severity |
+| ------------------------------------------------------------------------ | -------------------------------------- | -------- |
+| [consistent-property-naming](./docs/rules/consistent-property-naming.md) | Enforce camelCase for property names   | error    |
+| [valid-event-names](./docs/rules/valid-event-names.md)                   | Enforce valid event naming conventions | error    |
+
+
+## Examples
+
+### Before
+
+```js
+// ❌ Multiple issues
+postHog.capture('user clicked button', {
+  user_id: '123', // snake_case instead of camelCase
+  ButtonName: 'Submit', // PascalCase
+});
+```
+
+### After
+
+```js
+// ✅ Following best practices
+const EVENTS = {
+  BUTTON_CLICKED: 'button_clicked',
+  PAGE_VIEWED: 'page_viewed',
+};
+
+postHog.capture(EVENTS.BUTTON_CLICKED, {
+  userId: '123',
+  buttonName: 'Submit',
+  page: 'checkout',
+});
+
+postHog.capture(EVENTS.PAGE_VIEWED, {
+  pagePath: '/checkout',
+  referrer: document.referrer,
+});
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test
+# or
+pnpm test:watch
+```
+
+### Testing Locally
+
+To test the plugin in your project before publishing:
+
+1. In this directory, run:
+
+   ```bash
+   npm link
+   ```
+
+2. In your project directory:
+
+   ```bash
+   npm link @jtl-software/eslint-plugin-posthog
+   ```
+
+3. Add the plugin to your ESLint config as shown above
+
+### CI/CD
+
+This project uses GitHub Actions for continuous integration and deployment:
+
+- **Tests** run automatically on every push and pull request
+- **Publishing to npm** happens automatically when pushing to the `main` branch
+
+To set up automatic publishing, add an `NPM_TOKEN` secret to your GitHub repository:
+
+1. Generate an npm access token at https://www.npmjs.com/settings/tokens
+2. Go to your repository settings on GitHub
+3. Navigate to Settings → Secrets and variables → Actions
+4. Add a new repository secret named `NPM_TOKEN` with your npm token
+
+## License
+
+MIT

package/docs/rules/consistent-property-naming.md

@@ -0,0 +1,44 @@
+# consistent-property-naming
+
+Enforce consistent property naming convention (camelCase) in PostHog capture calls.
+
+## Rule Details
+
+This rule enforces camelCase naming for all properties passed to `postHog.capture()` calls. Consistent naming conventions make it easier to query and analyze events in PostHog.
+
+## Examples
+
+### ❌ Incorrect
+
+```js
+postHog.capture('user_action', {
+  user_id: '123', // snake_case
+  ProductName: 'Test', // PascalCase
+  'user-email': 'test@example.com', // kebab-case
+});
+```
+
+### ✅ Correct
+
+```js
+postHog.capture('user_action', {
+  userId: '123',
+  productName: 'Test',
+  userEmail: 'test@example.com',
+});
+```
+
+## Why?
+
+- **Consistency**: Makes queries and analysis easier
+- **Schema validation**: Aligns with code property naming conventions
+- **Discoverability**: Properties with consistent naming are easier to find
+
+## When Not To Use It
+
+If your team has established a different naming convention (e.g., snake_case) across all tracking implementations, you may want to disable this rule.
+
+## Related Rules
+
+- [require-event-schema](./require-event-schema.md)
+- [no-literal-event-names](./no-literal-event-names.md)

package/docs/rules/valid-event-names.md

@@ -0,0 +1,104 @@
+# valid-event-names
+
+Enforce valid event naming conventions for PostHog events.
+
+## Rule Details
+
+This rule enforces that event names follow PostHog's recommended naming conventions:
+
+1. **snake_case**: Event names must use lowercase with underscores
+2. **Object-verb pattern**: Events should follow the `[object]_[verb]` format (e.g., `button_clicked`, `user_created`)
+3. **Verb ending**: Events must end with a verb to describe the action
+
+## Examples
+
+### ❌ Incorrect
+
+```js
+// Not snake_case (camelCase)
+postHog.capture('buttonClicked', { userId: '123' });
+
+// Not snake_case (PascalCase)
+postHog.capture('ButtonClicked', { userId: '123' });
+
+// Not snake_case (kebab-case)
+postHog.capture('button-clicked', { userId: '123' });
+
+// Too short (missing object or verb)
+postHog.capture('clicked', { userId: '123' });
+postHog.capture('button', { userId: '123' });
+
+// Doesn't end with verb
+postHog.capture('button_color', { color: 'red' });
+postHog.capture('user_profile', { userId: '123' });
+```
+
+### ✅ Correct
+
+```js
+// Past tense verbs
+postHog.capture('button_clicked', { userId: '123' });
+postHog.capture('user_created', { userId: '123' });
+postHog.capture('page_viewed', { path: '/home' });
+
+// Present participle
+postHog.capture('video_playing', { videoId: '456' });
+postHog.capture('data_loading', { count: 10 });
+
+// Present tense
+postHog.capture('button_click', { buttonId: 'submit' });
+postHog.capture('page_view', { path: '/about' });
+postHog.capture('user_login', { method: 'oauth' });
+postHog.capture('form_submit', { formId: 'contact' });
+
+// With category prefix (optional)
+postHog.capture('account:settings_updated', { field: 'email' });
+postHog.capture('signup:button_clicked', { step: 1 });
+```
+
+## Verb Patterns
+
+The rule recognizes several verb patterns:
+
+### Endings
+
+- **-ed**: Past tense (clicked, created, viewed, updated)
+- **-ing**: Present participle (clicking, creating, viewing)
+- **-e**: Present tense ending in 'e' (create, delete, update)
+- **-ize/-ise**: Verbs (initialize, customize)
+- **-ate**: Verbs (validate, activate)
+- **-ify**: Verbs (notify, verify)
+
+### Common Verbs
+
+The rule includes a list of common present-tense verbs like: click, view, submit, open, close, add, remove, start, stop, play, pause, load, save, send, login, logout, etc.
+
+## Category Prefix (Optional)
+
+The rule supports PostHog's enhanced framework with optional category prefixes:
+
+```js
+postHog.capture('category:object_action', { ... });
+```
+
+Examples:
+
+- `account_settings:password_changed`
+- `signup_flow:form_submitted`
+- `checkout:payment_completed`
+
+## Why?
+
+- **Consistency**: Makes events easier to find and filter in PostHog
+- **Best practice**: Follows PostHog's official recommendations
+- **Clarity**: Object-verb pattern clearly describes what happened
+- **Analysis**: Consistent naming enables better querying and grouping
+
+## When Not To Use It
+
+If your team has established a different event naming convention and can't migrate, you may want to disable this rule. However, following PostHog's recommendations will make your analytics more maintainable.
+
+## Related Rules
+
+- [no-literal-event-names](./no-literal-event-names.md)
+- [consistent-property-naming](./consistent-property-naming.md)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jtl-software/eslint-plugin-posthog",
+  "version": "0.1.0",
+  "description": "ESLint rules for PostHog event tracking best practices",
+  "main": "src/index.js",
+  "type": "module",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "posthog",
+    "analytics",
+    "event-tracking"
+  ],
+  "author": "JTL Platform Team",
+  "license": "MIT",
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.7.4",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}

package/src/index.js

@@ -0,0 +1,24 @@
+import consistentPropertyNaming from './rules/consistent-property-naming.js';
+import validEventNames from './rules/valid-event-names.js';
+
+const plugin = {
+  meta: {
+    name: '@jtl-software/eslint-plugin-posthog',
+    version: '0.1.0',
+  },
+  rules: {
+    'consistent-property-naming': consistentPropertyNaming,
+    'valid-event-names': validEventNames,
+  },
+  configs: {
+    recommended: {
+      plugins: ['posthog'],
+      rules: {
+        'posthog/consistent-property-naming': 'error',
+        'posthog/valid-event-names': 'error',
+      },
+    },
+  },
+};
+
+export default plugin;

package/src/rules/consistent-property-naming.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Enforce consistent property naming convention (camelCase) in PostHog events
+ * @author JTL Platform Team
+ */
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Enforce consistent property naming convention (camelCase) in PostHog capture calls',
+      recommended: true,
+    },
+    messages: {
+      notCamelCase: 'Property "{{property}}" should use camelCase naming convention',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    /**
+     * Check if a string is in camelCase
+     * @param {string} str - The string to check
+     * @returns {boolean}
+     */
+    function isCamelCase(str) {
+      // Allow camelCase: starts with lowercase, can contain uppercase letters and numbers
+      // No underscores or hyphens allowed
+      return /^[a-z][a-zA-Z0-9]*$/.test(str);
+    }
+
+    /**
+     * Check if node is a PostHog capture call
+     * @param {Object} node - AST node
+     * @returns {boolean}
+     */
+    function isPostHogCapture(node) {
+      return (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property.name === 'capture' &&
+        node.callee.object.name === 'postHog'
+      );
+    }
+
+    return {
+      CallExpression(node) {
+        if (!isPostHogCapture(node)) {
+          return;
+        }
+
+        // Second argument should be the properties object
+        const propertiesArg = node.arguments[1];
+        if (!propertiesArg || propertiesArg.type !== 'ObjectExpression') {
+          return;
+        }
+
+        // Check each property in the object
+        propertiesArg.properties.forEach((prop) => {
+          if (prop.type === 'Property' && prop.key.type === 'Identifier') {
+            const propertyName = prop.key.name;
+            if (!isCamelCase(propertyName)) {
+              context.report({
+                node: prop.key,
+                messageId: 'notCamelCase',
+                data: {
+                  property: propertyName,
+                },
+              });
+            }
+          }
+        });
+      },
+    };
+  },
+};

package/src/rules/valid-event-names.js

@@ -0,0 +1,318 @@
+/**
+ * @fileoverview Enforce valid event naming conventions for PostHog events
+ * @author JTL Platform Team
+ */
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Enforce snake_case and object-verb pattern for PostHog event names',
+      recommended: true,
+    },
+    messages: {
+      notSnakeCase: 'Event name "{{eventName}}" should use snake_case naming convention',
+      missingVerb:
+        'Event name "{{eventName}}" should end with a verb (e.g., "object_clicked", "user_created", "page_view")',
+      tooShort:
+        'Event name "{{eventName}}" should follow the [object][verb] pattern with at least two parts',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    /**
+     * Check if a string is in snake_case
+     * @param {string} str - The string to check
+     * @returns {boolean}
+     */
+    function isSnakeCase(str) {
+      // Allow snake_case: lowercase letters, numbers, and underscores
+      // Can also start with a category prefix like "category:object_action"
+      return /^[a-z][a-z0-9_:]*$/.test(str);
+    }
+
+    /**
+     * Check if the last word in an event name looks like a verb
+     * @param {string} eventName - The event name to check
+     * @returns {boolean}
+     */
+    function endsWithVerb(eventName) {
+      // Remove category prefix if present (e.g., "account:button_clicked" -> "button_clicked")
+      const nameWithoutCategory = eventName.includes(':') ? eventName.split(':')[1] : eventName;
+
+      // Split by underscore and get the last word
+      const words = nameWithoutCategory.split('_');
+      const lastWord = words[words.length - 1];
+
+      // Check for common verb patterns
+      const verbPatterns = [/ed$/, /ing$/, /ize$/, /ise$/, /ate$/, /ify$/];
+
+      // Common present tense verbs without specific patterns
+      const commonVerbs = [
+        'click',
+        'view',
+        'submit',
+        'open',
+        'close',
+        'add',
+        'remove',
+        'start',
+        'stop',
+        'play',
+        'pause',
+        'load',
+        'save',
+        'send',
+        'get',
+        'post',
+        'put',
+        'patch',
+        'delete',
+        'fetch',
+        'push',
+        'pull',
+        'set',
+        'reset',
+        'clear',
+        'show',
+        'hide',
+        'toggle',
+        'select',
+        'deselect',
+        'check',
+        'uncheck',
+        'enable',
+        'disable',
+        'expand',
+        'collapse',
+        'scroll',
+        'hover',
+        'focus',
+        'blur',
+        'drag',
+        'drop',
+        'upload',
+        'download',
+        'export',
+        'import',
+        'print',
+        'copy',
+        'paste',
+        'cut',
+        'undo',
+        'redo',
+        'refresh',
+        'reload',
+        'login',
+        'logout',
+        'signup',
+        'signin',
+        'signout',
+        'create',
+        'update',
+        'archive',
+        'unarchive',
+        'like',
+        'share',
+        'subscribe',
+        'unsubscribe',
+        'favorite',
+        'unfavorite',
+        'mute',
+        'unmute',
+        'change',
+        'complete',
+        'execute',
+        'terminate',
+      ];
+
+      return (
+        verbPatterns.some((pattern) => pattern.test(lastWord)) || commonVerbs.includes(lastWord)
+      );
+    }
+
+    /**
+     * Check if event name follows [object][verb] pattern
+     * @param {string} eventName - The event name to check
+     * @returns {boolean}
+     */
+    function hasObjectVerbPattern(eventName) {
+      // Remove category prefix if present
+      const nameWithoutCategory = eventName.includes(':') ? eventName.split(':')[1] : eventName;
+
+      // Should have at least 2 parts (object + verb)
+      const parts = nameWithoutCategory.split('_');
+      return parts.length >= 2;
+    }
+
+    /**
+     * Check if node is a PostHog capture call
+     * @param {Object} node - AST node
+     * @returns {boolean}
+     */
+    function isPostHogCapture(node) {
+      return (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property.name === 'capture' &&
+        node.callee.object.name === 'postHog'
+      );
+    }
+
+    // Track identifiers that refer to postHog.capture
+    const captureAliases = new Set();
+
+    /**
+     * Check if a CallExpression node is a capture call (direct or aliased)
+     * @param {Object} node - AST node
+     * @returns {boolean}
+     */
+    function isCaptureCall(node) {
+      if (node.type !== 'CallExpression') {
+        return false;
+      }
+
+      // Direct postHog.capture()
+      if (isPostHogCapture(node)) {
+        return true;
+      }
+
+      // Aliased or imported capture()
+      if (node.callee.type === 'Identifier' && captureAliases.has(node.callee.name)) {
+        return true;
+      }
+
+      return false;
+    }
+
+    /**
+     * Validate an event name argument
+     * @param {Object} eventNameArg - The event name argument node
+     */
+    function validateEventName(eventNameArg) {
+      // Only check literal strings (constants will be checked at their definition)
+      if (eventNameArg.type === 'Literal' && typeof eventNameArg.value === 'string') {
+        const eventName = eventNameArg.value;
+
+        // Check snake_case
+        if (!isSnakeCase(eventName)) {
+          context.report({
+            node: eventNameArg,
+            messageId: 'notSnakeCase',
+            data: { eventName },
+          });
+          return;
+        }
+
+        // Check object-verb pattern (at least 2 parts)
+        if (!hasObjectVerbPattern(eventName)) {
+          context.report({
+            node: eventNameArg,
+            messageId: 'tooShort',
+            data: { eventName },
+          });
+          return;
+        }
+
+        // Check that it ends with a verb
+        if (!endsWithVerb(eventName)) {
+          context.report({
+            node: eventNameArg,
+            messageId: 'missingVerb',
+            data: { eventName },
+          });
+        }
+      }
+
+      // Also check if it's an Identifier (constant reference)
+      if (eventNameArg.type === 'Identifier') {
+        // Find the constant definition
+        const scope = context.sourceCode.getScope(eventNameArg);
+        const variable = scope.variables.find((v) => v.name === eventNameArg.name);
+
+        if (variable && variable.defs.length > 0) {
+          const def = variable.defs[0];
+          if (def.node.init && def.node.init.type === 'Literal') {
+            const eventName = def.node.init.value;
+
+            if (typeof eventName === 'string') {
+              // Check snake_case
+              if (!isSnakeCase(eventName)) {
+                context.report({
+                  node: def.node.init,
+                  messageId: 'notSnakeCase',
+                  data: { eventName },
+                });
+                return;
+              }
+
+              // Check object-verb pattern
+              if (!hasObjectVerbPattern(eventName)) {
+                context.report({
+                  node: def.node.init,
+                  messageId: 'tooShort',
+                  data: { eventName },
+                });
+                return;
+              }
+
+              // Check that it ends with a verb
+              if (!endsWithVerb(eventName)) {
+                context.report({
+                  node: def.node.init,
+                  messageId: 'missingVerb',
+                  data: { eventName },
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      // Track imports of capture from posthog packages
+      ImportDeclaration(node) {
+        if (
+          node.source.value === 'posthog-js' ||
+          node.source.value === 'posthog' ||
+          node.source.value.startsWith('@posthog/')
+        ) {
+          node.specifiers.forEach((specifier) => {
+            if (specifier.type === 'ImportSpecifier' && specifier.imported.name === 'capture') {
+              captureAliases.add(specifier.local.name);
+            }
+          });
+        }
+      },
+
+      // Track variable assignments of postHog.capture
+      VariableDeclarator(node) {
+        if (
+          node.init &&
+          node.init.type === 'MemberExpression' &&
+          node.init.object.name === 'postHog' &&
+          node.init.property.name === 'capture' &&
+          node.id.type === 'Identifier'
+        ) {
+          captureAliases.add(node.id.name);
+        }
+      },
+
+      CallExpression(node) {
+        if (!isCaptureCall(node)) {
+          return;
+        }
+
+        // First argument should be the event name
+        const eventNameArg = node.arguments[0];
+        if (!eventNameArg) {
+          return;
+        }
+
+        validateEventName(eventNameArg);
+      },
+    };
+  },
+};

package/tests/rules/consistent-property-naming.test.js

@@ -0,0 +1,74 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/rules/consistent-property-naming.js';
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+});
+
+ruleTester.run('consistent-property-naming', rule, {
+  valid: [
+    {
+      code: `postHog.capture('event_name', { userId: '123', productName: 'Test' })`,
+    },
+    {
+      code: `postHog.capture('event_name', { count: 5, isActive: true })`,
+    },
+    {
+      code: `postHog.capture('event_name', { a: 1, bc: 2, def: 3 })`,
+    },
+    {
+      code: `// Not a PostHog call
+                 someOtherFunction({ user_id: '123' })`,
+    },
+  ],
+
+  invalid: [
+    {
+      code: `postHog.capture('event_name', { user_id: '123' })`,
+      errors: [
+        {
+          messageId: 'notCamelCase',
+          data: { property: 'user_id' },
+        },
+      ],
+    },
+    {
+      code: `postHog.capture('event_name', { product_name: 'Test', userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notCamelCase',
+          data: { property: 'product_name' },
+        },
+      ],
+    },
+    {
+      code: `postHog.capture('event_name', { UserID: '123', productName: 'Test' })`,
+      errors: [
+        {
+          messageId: 'notCamelCase',
+          data: { property: 'UserID' },
+        },
+      ],
+    },
+    {
+      code: `postHog.capture('event_name', {
+                   userId: '123',
+                   product_name: 'Test',
+                   is_active: true
+                 })`,
+      errors: [
+        {
+          messageId: 'notCamelCase',
+          data: { property: 'product_name' },
+        },
+        {
+          messageId: 'notCamelCase',
+          data: { property: 'is_active' },
+        },
+      ],
+    },
+  ],
+});

package/tests/rules/valid-event-names.test.js

@@ -0,0 +1,197 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/rules/valid-event-names.js';
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+});
+
+ruleTester.run('valid-event-names', rule, {
+  valid: [
+    // snake_case with object-verb pattern (past tense)
+    {
+      code: `postHog.capture('button_clicked', { userId: '123' })`,
+    },
+    {
+      code: `postHog.capture('user_created', { userId: '123' })`,
+    },
+    {
+      code: `postHog.capture('page_viewed', { path: '/home' })`,
+    },
+    // snake_case with object-verb pattern (present participle)
+    {
+      code: `postHog.capture('video_playing', { videoId: '456' })`,
+    },
+    {
+      code: `postHog.capture('data_loading', { count: 10 })`,
+    },
+    // snake_case with object-verb pattern (present tense)
+    {
+      code: `postHog.capture('button_click', { buttonId: 'submit' })`,
+    },
+    {
+      code: `postHog.capture('page_view', { path: '/about' })`,
+    },
+    {
+      code: `postHog.capture('user_login', { method: 'oauth' })`,
+    },
+    {
+      code: `postHog.capture('form_submit', { formId: 'contact' })`,
+    },
+    // snake_case with category prefix
+    {
+      code: `postHog.capture('account:settings_updated', { field: 'email' })`,
+    },
+    {
+      code: `postHog.capture('signup:button_clicked', { step: 1 })`,
+    },
+    // common verb endings
+    {
+      code: `postHog.capture('user_initialize', { userId: '123' })`,
+    },
+    {
+      code: `postHog.capture('form_validate', { formId: 'signup' })`,
+    },
+    {
+      code: `postHog.capture('account_activate', { accountId: '789' })`,
+    },
+    {
+      code: `postHog.capture('user_notify', { message: 'test' })`,
+    },
+    // using constants (won't be checked)
+    {
+      code: `const EVENT_NAME = 'button_clicked';
+                 postHog.capture(EVENT_NAME, { userId: '123' })`,
+    },
+    // not a PostHog call
+    {
+      code: `someOtherFunction('InvalidName', { data: 'test' })`,
+    },
+    // aliased postHog.capture
+    {
+      code: `const capture = postHog.capture;
+                 capture('button_clicked', { userId: '123' })`,
+    },
+    // imported capture from posthog-js
+    {
+      code: `import { capture } from 'posthog-js';
+                 capture('user_created', { userId: '456' })`,
+    },
+  ],
+
+  invalid: [
+    // not snake_case (camelCase)
+    {
+      code: `postHog.capture('buttonClicked', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'buttonClicked' },
+        },
+      ],
+    },
+    // not snake_case (PascalCase)
+    {
+      code: `postHog.capture('ButtonClicked', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'ButtonClicked' },
+        },
+      ],
+    },
+    // not snake_case (kebab-case)
+    {
+      code: `postHog.capture('button-clicked', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'button-clicked' },
+        },
+      ],
+    },
+    // too short (missing object or verb)
+    {
+      code: `postHog.capture('clicked', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'tooShort',
+          data: { eventName: 'clicked' },
+        },
+      ],
+    },
+    {
+      code: `postHog.capture('button', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'tooShort',
+          data: { eventName: 'button' },
+        },
+      ],
+    },
+    // doesn't end with verb
+    {
+      code: `postHog.capture('button_color', { color: 'red' })`,
+      errors: [
+        {
+          messageId: 'missingVerb',
+          data: { eventName: 'button_color' },
+        },
+      ],
+    },
+    {
+      code: `postHog.capture('user_profile', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'missingVerb',
+          data: { eventName: 'user_profile' },
+        },
+      ],
+    },
+    // constant with a bad name
+    {
+      code: `const EVENT_NAME = 'BadName';
+                 postHog.capture(EVENT_NAME, { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'BadName' },
+        },
+      ],
+    },
+    {
+      code: `const EVENT_NAME = 'button_color';
+                 postHog.capture(EVENT_NAME, { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'missingVerb',
+          data: { eventName: 'button_color' },
+        },
+      ],
+    },
+    // aliased postHog.capture with bad event name
+    {
+      code: `const capture = postHog.capture;
+                 capture('InvalidName', { data: 'test' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'InvalidName' },
+        },
+      ],
+    },
+    // imported capture with bad event name
+    {
+      code: `import { capture } from 'posthog-js';
+                 capture('userClicked', { userId: '123' })`,
+      errors: [
+        {
+          messageId: 'notSnakeCase',
+          data: { eventName: 'userClicked' },
+        },
+      ],
+    },
+  ],
+});

package/tests/setup.js

@@ -0,0 +1,13 @@
+/**
+ * Vitest test setup
+ * Configures ESLint's RuleTester to work with Vitest
+ */
+
+import { RuleTester } from 'eslint';
+import { describe, it, afterAll } from 'vitest';
+
+// Configure RuleTester to work with Vitest
+RuleTester.describe = describe;
+RuleTester.it = it;
+RuleTester.itOnly = it.only;
+RuleTester.afterAll = afterAll;

package/vitest.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./tests/setup.js'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'tests/', '*.config.js'],
+    },
+  },
+});