Merge branch 'master' into test

Author: Huliiiiii

.cursor/rules/architecture.mdc

@@ -0,0 +1,8 @@
+---
+alwaysApply: true
+description: Project Overview
+---
+
+# Project Overview
+
+This project is a Rust library for formatting SQL queries. It is intended to support all mainstream SQL dialects. The crate exposes one interface for consumers, which is the `format` function exported at the top level of the crate.

.cursor/rules/code-testing.mdc

@@ -0,0 +1,48 @@
+---
+description: Code Testing Best Practices
+alwaysApply: false
+---
+
+# Code Testing Best Practices
+
+## Test Structure & Organization
+
+- Write descriptive test names that clearly explain what is being tested
+- Follow the AAA pattern: Arrange, Act, Assert
+- Group related tests together in logical test suites
+- Keep tests independent - each test should be able to run in isolation
+
+## Test Coverage & Scope
+
+- Write tests for both happy path and edge cases
+- Include tests for error conditions and invalid inputs
+- Test boundary conditions (empty strings, null values, maximum/minimum values)
+- All tests should have at least one assertion. Always use assertions instead of console logging to validate test results.
+- Aim for meaningful coverage, not just high percentage coverage
+
+## Test Quality
+
+- Keep tests simple and focused - test one thing at a time
+- Make tests deterministic - avoid randomness or time-dependent behavior
+- Use clear, descriptive assertions with helpful error messages
+- Avoid testing implementation details; focus on behavior and outcomes
+
+## Test Data & Setup
+
+- Use minimal test data that clearly demonstrates the test case
+- Create reusable test fixtures and helper functions for common setup
+- Clean up resources after tests (database records, files, network connections)
+- Use test doubles (mocks, stubs, fakes) to isolate units under test
+
+## Performance & Maintenance
+
+- Keep tests fast - slow tests discourage frequent running
+- Make tests easy to read and maintain
+- Remove or update obsolete tests when code changes
+- Run tests frequently during development
+
+## Documentation & Communication
+
+- Write tests that serve as documentation for expected behavior
+- Include comments for complex test logic or non-obvious test scenarios
+- Ensure test failures provide clear information about what went wrong

.cursor/rules/effective-comments.mdc

@@ -0,0 +1,127 @@
+---
+alwaysApply: true
+description: Guidelines for writing meaningful and maintainable code comments
+---
+
+# Guidelines for writing meaningful and maintainable code comments
+
+You are an expert in clean code practices, documentation, and code readability.
+
+## When to Comment
+
+- Explain WHY, not WHAT the code does
+- Document complex business logic or algorithms
+- Clarify non-obvious implementations
+- Warn about potential gotchas or side effects
+- Provide context for future maintainers
+
+## Comment Types and Usage
+
+### Good Comments
+
+```javascript
+// Using exponential backoff to avoid overwhelming the API
+// during high traffic periods (see incident report #1234)
+const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
+
+// WORKAROUND: Chrome bug #123456 requires explicit height
+// Remove when Chrome 120+ adoption reaches 95%
+element.style.height = "auto";
+
+// Performance: Caching results reduces API calls by ~70%
+// based on production metrics from 2023-Q4
+const cachedResult = cache.get(key);
+```
+
+### Bad Comments
+
+```javascript
+// BAD: Obvious comment
+// Increment counter by 1
+counter++;
+
+// BAD: Outdated comment
+// Send email to user (actually sends SMS now)
+await notificationService.send(user);
+
+// BAD: Commented-out code without context
+// user.setStatus('active');
+// user.save();
+```
+
+## Documentation Comments
+
+### JavaScript/TypeScript
+
+```typescript
+/**
+ * Calculates compound interest with monthly contributions.
+ * Uses the formula: A = P(1 + r/n)^(nt) + PMT × (((1 + r/n)^(nt) - 1) / (r/n))
+ *
+ * @param principal - Initial investment amount
+ * @param rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param time - Investment period in years
+ * @param contribution - Monthly contribution amount
+ * @returns Total value after the investment period
+ *
+ * @example
+ * // Calculate 10-year investment with 5% annual return
+ * const total = calculateCompoundInterest(10000, 0.05, 10, 500);
+ * console.log(total); // 96,859.57
+ */
+function calculateCompoundInterest(
+  principal: number,
+  rate: number,
+  time: number,
+  contribution: number
+): number {
+  // Implementation
+}
+```
+
+### Python
+
+```python
+def process_transaction(transaction: Transaction) -> ProcessResult:
+    """
+    Process a financial transaction with fraud detection and validation.
+
+    This method performs multiple checks before processing:
+    1. Validates transaction format and required fields
+    2. Checks against fraud detection rules
+    3. Verifies account balance and limits
+    4. Processes through payment gateway
+
+    Args:
+        transaction: Transaction object containing payment details
+
+    Returns:
+        ProcessResult with status and any error messages
+
+    Raises:
+        ValidationError: If transaction format is invalid
+        FraudException: If transaction triggers fraud rules
+        InsufficientFundsError: If account balance is too low
+
+    Note:
+        Transactions over $10,000 require additional verification
+        per compliance policy FIN-2023-001.
+    """
+```
+
+## TODO Comments
+
+```python
+# TODO(john): Implement retry logic for network failures
+# TODO(security): Add rate limiting before v2.0 release
+# FIXME: Handle edge case when user has multiple accounts
+# HACK: Temporary fix until database migration completes
+```
+
+## Best Practices
+
+- Keep comments concise and relevant
+- Update comments when code changes
+- Use consistent comment style across the codebase
+- Avoid humor or cultural references that may not translate
+- Review comments during code reviews

.cursor/rules/github-actions.mdc

@@ -0,0 +1,49 @@
+---
+alwaysApply: false
+description: Best practices for GitHub Actions workflows
+globs: .github/workflows/*.yml, .github/workflows/*.yaml
+---
+
+# Best practices for GitHub Actions workflows
+
+You are an expert in CI/CD, GitHub Actions, and DevOps automation.
+
+## Workflow Structure
+
+- Use descriptive workflow and job names
+- Organize workflows by purpose (ci.yml, deploy.yml, release.yml)
+- Implement proper job dependencies with needs
+- Use matrix builds for testing multiple versions
+- Keep workflows DRY using reusable workflows
+
+## Security Best Practices
+
+- Use GitHub Secrets for sensitive data
+- Implement least privilege for GITHUB_TOKEN permissions
+- Pin action versions to specific commits or tags
+- Use OIDC for cloud provider authentication
+- Scan for vulnerabilities in dependencies
+
+## Performance Optimization
+
+- Cache dependencies appropriately (npm, pip, etc.)
+- Use artifacts efficiently between jobs
+- Parallelize independent jobs
+- Implement conditional workflows to avoid unnecessary runs
+- Use concurrency groups to cancel outdated runs
+
+## Error Handling
+
+- Implement proper timeout values
+- Add retry logic for flaky steps
+- Use continue-on-error strategically
+- Create informative failure messages
+- Set up notifications for critical failures
+
+## Best Practices
+
+- Use composite actions for repeated tasks
+- Document workflows with comments
+- Implement branch protection rules
+- Use environments for deployment stages
+- Monitor workflow metrics and costs

.cursor/rules/project-readme.mdc

@@ -0,0 +1,149 @@
+---
+alwaysApply: false
+description: Guidelines for creating comprehensive project README files
+globs: README.md
+---
+
+# Guidelines for creating comprehensive project README files
+
+You are an expert in technical documentation, open source best practices, and developer experience.
+
+## README Structure
+
+A well-structured README should include these sections in order:
+
+1. Project Title and Description
+2. Badges (build status, version, license)
+3. Key Features
+4. Screenshots/Demo (if applicable)
+5. Quick Start
+6. Installation
+7. Usage Examples
+8. API Reference (or link to docs)
+9. Configuration
+10. Contributing
+11. License
+
+## Essential Sections
+
+### Project Header
+
+```markdown
+# Project Name
+
+> One-line description of what this project does
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](https://github.com/user/repo/actions)
+[![npm version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name)
+[![License](https://img.shields.io/github/license/user/repo)](LICENSE)
+
+Brief paragraph explaining the project's purpose, main features, and why someone would want to use it.
+```
+
+### Quick Start
+
+```markdown
+## Quick Start
+
+Get up and running in less than 5 minutes:
+
+\`\`\`bash
+npm install package-name
+npm run dev
+\`\`\`
+
+Visit http://localhost:3000 to see the application.
+```
+
+### Installation
+
+```markdown
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- PostgreSQL 14+
+- Redis 6.2+
+
+### Install from npm
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+### Install from source
+
+\`\`\`bash
+git clone https://github.com/user/repo.git
+cd repo
+npm install
+npm run build
+\`\`\`
+```
+
+### Usage Examples
+
+```markdown
+## Usage
+
+### Basic Example
+
+\`\`\`javascript
+import { Widget } from 'package-name';
+
+const widget = new Widget({
+apiKey: 'your-api-key',
+theme: 'dark'
+});
+
+widget.render('#app');
+\`\`\`
+
+### Advanced Example
+
+\`\`\`javascript
+// Custom configuration with error handling
+const widget = new Widget({
+apiKey: process.env.API_KEY,
+theme: 'dark',
+onError: (error) => {
+console.error('Widget error:', error);
+}
+});
+
+// Add custom event handlers
+widget.on('ready', () => {
+console.log('Widget is ready');
+});
+
+widget.render('#app');
+\`\`\`
+```
+
+## Best Practices
+
+- Keep the README focused and concise
+- Use clear, simple language
+- Include code examples that actually work
+- Add visuals when they help understanding
+- Link to more detailed documentation
+- Keep examples up-to-date with the code
+- Test your installation instructions regularly
+
+## Common Mistakes to Avoid
+
+- Don't assume reader knowledge
+- Don't skip the Quick Start section
+- Don't use jargon without explanation
+- Don't forget to update version numbers
+- Don't include sensitive information
+
+## Formatting Tips
+
+- Use consistent heading levels
+- Include a table of contents for long READMEs
+- Use code blocks with language highlighting
+- Add alt text to images
+- Use tables for comparing options
+- Include emoji sparingly and purposefully