docs: Add MDC guidelines and rules for Cursor

.cursor/rules/_navigation.mdc

@@ -0,0 +1,30 @@
+---
+description: Codebase Navigation Rules
+globs: 
+alwaysApply: false
+---
+# Cursor Rules Navigation Configuration
+
+## Global base rules (applied to all files unless overridden)
+[/**/*]
+.cursor/rules/base.mdc
+
+## Testing rules
+[/test/**/tests-**.ts, /test/src/tests-**.js, /test/src/jest/**.spec.ts]
+.cursor/rules/test.mdc
+
+### Testing subcategories
+
+#### Unit Testing Rules
+[/test/jest/*.spec.ts]
+.cursor/rules/unit-testing.mdc
+
+#### Integration Testing Rules
+[/test/src/tests-**.ts, /test/src/tests-**.js]
+.cursor/rules/integration-testing.mdc
+
+#### Cross Browser Testing Rules
+
+## Personal rules
+[/**/*]
+.cursor/rules/_personal_.mdc 

.cursor/rules/code-quality.mdc

@@ -0,0 +1,54 @@
+---
+description: Coding Guidelines specific for JavaScript and TypeScript
+globs: src/**.js, src/**.ts
+---
+# Persona
+
+You are a senior javascript and typescript developer. One of those rare 10x developers that has incredible knowledge.
+
+# Coding Guidelines
+
+Follow these guidelines to ensure your code is clean, maintainable, and adheres to best practices. Remember, less code is better. Lines of code = Debt.
+
+# Key Mindsets
+
+**1** **Simplicity**: Write simple and straightforward code.
+**2** **Readability**: Ensure your code is easy to read and understand.
+**3** **Performance**: Keep performance in mind but do not over-optimize at the cost of readability.
+**4** **Maintainability**: Write code that is easy to maintain and update.
+**5** **Testability**: Ensure your code is easy to test.
+**6** **Reusability**: Write reusable components and functions.
+
+Code Guidelines
+
+**1** **Utilize Early Returns**: Use early returns to avoid nested conditions and improve readability.
+**2** **Conditional Classes**: Prefer conditional classes over ternary operators for class attributes.
+**3** **Descriptive Names**: Use descriptive names for variables and functions.
+**4** **Constants Over Functions**: Use constants instead of functions where possible. Define types if applicable.
+**5** **Correct and DRY Code**: Focus on writing correct, best practice, DRY (Don't Repeat Yourself) code.
+**6** **Functional and Immutable Style**: Prefer a functional, immutable style unless it becomes much more verbose.
+**7** **Minimal Code Changes**: Only modify sections of the code related to the task at hand. Avoid modifying unrelated pieces of code. Accomplish goals with minimal code changes.
+
+Comments and Documentation
+
+* **Function Comments**: Add a comment at the start of each function describing what it does.
+* **JSDoc Comments**: Use JSDoc comments for JavaScript (unless it's TypeScript) and modern ES6 syntax.
+
+Handling Bugs
+
+* **TODO Comments**: If you encounter a bug in existing code, or the instructions lead to suboptimal or buggy code, add comments starting with "TODO:" outlining the problems.
+
+Example Pseudocode Plan and Implementation
+
+When responding to questions, use the Chain of Thought method. Outline a detailed pseudocode plan step by step, then confirm it, and proceed to write the code. Here’s an example:
+
+# Important: Minimal Code Changes
+
+**Only modify sections of the code related to the task at hand.**
+**Avoid modifying unrelated pieces of code.**
+**Avoid changing existing comments.**
+**Avoid any kind of cleanup unless specifically instructed to.**
+**Accomplish the goal with the minimum amount of code changes.**
+**Code change = potential for bugs and technical debt.**
+
+Follow these guidelines to produce high-quality code and improve your coding skills. If you have any questions or need clarification, don’t hesitate to ask!

.cursor/rules/coding-best-practices.mdc

@@ -0,0 +1,89 @@
+---
+description: 
+globs: *.js, *.ts
+---
+ # JavaScript and TypeScript Coding Best Practices
+
+ Coding best practices for the mParticle project including code style, structure, and maintenance guidelines for .js and .ts files
+
+ ## General Guidelines
+
+ This document outlines the coding best practices to be followed in the mParticle project.
+
+ ## Code Organization
+
+ ## Updating Cursor Rules
+
+ <rule>
+ name: update_cursor_rules_when_corrected
+ description: Always update rules when a correction is made
+ filters:
+   - type: event
+     pattern: "conversation"
+
+ actions:
+   - type: suggest
+     message: |
+       When corrections are made to your code or approach:
+
+       1. Always update existing Cursor rules or create new ones to reflect the correction
+       2. Document the reasoning behind the correction
+       3. Include examples of both incorrect and correct approaches
+       4. Make sure rule updates are committed along with code changes
+
+       This ensures that future work will benefit from the lessons learned and helps maintain consistent coding practices.
+
+ examples:
+   - input: |
+       // Correction made about unnecessary usings but rules not updated
+       // Future similar mistakes likely to occur
+     output: |
+       // Correction made about unnecessary usings
+       // Rules updated to prevent similar issues:
+       // .cursor/rules/coding-best-practices.mdc updated with using directive guidelines
+       // Future work will avoid the same mistake
+
+ metadata:
+   priority: high
+   version: 1.0
+ </rule>
+
+ ## Code Style
+
+ ### Naming Conventions
+
+ - Use PascalCase for class names
+ - Use camelCase for method parameters and local variables
+ - Use camelCase for method names, and property names
+ - Prefix interfaces with 'I'
+ - Use meaningful, descriptive names that communicate intent
+
+ ### Formatting
+
+ - Use consistent indentation (4 spaces recommended)
+ - Limit line length to improve readability
+ - Use blank lines to separate logical blocks of code
+
+ ## Documentation
+
+ - Document public APIs with comments (use JSDocs format for .js files or TSDocs format for .ts files)
+ - Include a summary for each class and method
+ - Document parameters, return values, and exceptions
+ - Provide examples for complex APIs
+
+ ## Error Handling
+
+ - Be specific about the exceptions you catch
+ - Avoid empty catch blocks
+ - Log exceptions with relevant context
+ - Consider using exception filters
+
+ ## Testing
+
+ - Write unit tests for all public APIs
+ - Focus on testing behavior, not implementation details
+ - Use meaningful assertion strings that describe the scenario being tested
+ - Follow the Rspec pattern for organizing tests into `describe` and `it` blocks
+
+ @version "1.0.0"
+ @last_updated "2025-03-10"

.cursor/rules/commit-messages.mdc

@@ -0,0 +1,62 @@
+# Commit Message Conventions
+
+<rule>
+name: commit_message_conventions
+description: Standards for writing commit messages following conventional commit standards
+
+format: |
+  The commit message should follow this format:
+  ```
+  <type>[optional scope]: <description>
+
+  [optional body]
+
+  [optional footer]
+  ```
+
+  Breaking changes must be indicated by "BREAKING CHANGE:" in the footer
+
+types: |
+  - feat: A new feature (automatic minor release)
+  - fix: A bug fix (automatic patch release)
+  - docs: Documentation only changes
+  - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+  - refactor: A code change that neither fixes a bug nor adds a feature
+  - perf: A code change that improves performance
+  - test: Adding missing or correcting existing tests
+  - chore: Changes that don't modify src or test files, such as automatic documentation generation
+  - ci: Changes to CI configuration files/scripts
+  - revert: Revert commit
+  - build: Changes that affect the build system or other dependencies
+
+guidelines: |
+  1. First line must follow the type format
+  2. Description should be clear and concise
+  3. Breaking changes must be noted in footer
+  4. Follow conventional commit standards
+
+examples:
+  good:
+  - "feat: Add HashedAttributes method to RoktManager"
+  - "fix: Correct attribute mapping in RoktManager"
+  - "docs: Update README with new API methods"
+  - "refactor: Simplify attribute handling logic"
+  - "test: Add test coverage for hashedAttributes"
+  - |
+    feat: Add new authentication method
+
+    BREAKING CHANGE: Old auth tokens are no longer supported
+
+  bad:
+  - "feat(rokt): Added hashed attributes feature to roktmanager."
+  - "fixed bug in attributes"
+  - "updates"
+  - "New feature: hashed attributes"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>
+
+@version "1.0.0"
+@last_updated "2024-03-05" 

.cursor/rules/cursor-rules-location.mdc

@@ -0,0 +1,78 @@
+---
+description: Rules for placing and organizing Cursor rule files in the repository
+globs: 
+---
+# Cursor Rules Location
+
+Rules for placing and organizing Cursor rule files in the repository.
+
+<rule>
+name: cursor_rules_location
+description: Standards for placing Cursor rule files in the correct directory
+filters:
+  # Match any .mdc files
+  - type: file_extension
+    pattern: "\\.mdc$"
+  # Match files that look like Cursor rules
+  - type: content
+    pattern: "(?s)<rule>.*?</rule>"
+  # Match file creation events
+  - type: event
+    pattern: "file_create"
+
+actions:
+  - type: reject
+    conditions:
+      - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
+        message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
+
+  - type: suggest
+    message: |
+      When creating Cursor rules:
+
+      1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
+         ```
+         .cursor/rules/
+         ├── your-rule-name.mdc
+         ├── another-rule.mdc
+         └── ...
+         ```
+
+      2. Follow the naming convention:
+         - Use kebab-case for filenames
+         - Always use .mdc extension
+         - Make names descriptive of the rule's purpose
+
+      3. Directory structure:
+         ```
+         PROJECT_ROOT/
+         ├── .cursor/
+         │   └── rules/
+         │       ├── your-rule-name.mdc
+         │       └── ...
+         └── ...
+         ```
+
+      4. Never place rule files:
+         - In the project root
+         - In subdirectories outside .cursor/rules
+         - In any other location
+
+examples:
+  - input: |
+      # Bad: Rule file in wrong location
+      rules/my-rule.mdc
+      my-rule.mdc
+      .rules/my-rule.mdc
+
+      # Good: Rule file in correct location
+      .cursor/rules/my-rule.mdc
+    output: "Correctly placed Cursor rule file"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>
+
+@version "1.0.0"
+@last_updated "2025-03-05"

.cursor/rules/global-rule.mdc

@@ -0,0 +1,53 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Developer Guidelines
+
+## Core Principles
+
+1. **Examine Codebase First**
+   - Understand architecture before making changes
+   - Identify dependencies and component relationships
+   - Review documentation and existing tests
+   - Observe established patterns
+
+2. **Understand Requirements**
+   - Identify both explicit and implicit requirements
+   - Consider broader goals behind specific requests
+   - Interpret requests within project context
+   - Recognize unstated assumptions
+
+3. **Seek Clarity**
+   - Ask questions when requirements are ambiguous
+   - Validate assumptions before implementation
+   - Request additional context when needed
+
+4. **Assess Impact**
+   - Consider effects on related components
+   - Evaluate performance and security implications
+   - Ensure changes align with existing patterns
+   - Identify potential regression points
+
+5. **Provide Complete Solutions**
+   - Address full scope including edge cases
+   - Include necessary dependencies
+   - Explain implementation choices
+   - Consider testing approaches
+
+## Implementation Process
+
+1. Analyze relevant code through searching and reading
+2. Understand component structure
+3. Identify affected files
+4. Consider integration points
+5. Make changes while preserving existing functionality
+6. Explain integration with existing system
+
+## Documentation
+
+1. Reference existing documentation when available
+2. Explain technical decisions clearly
+3. Justify any deviations from established patterns
+4. Note areas for potential improvement