claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-languages/rules/code-quality-standards.md

@@ -0,0 +1,496 @@
+---
+name: code-quality-standards
+priority: high
+tags:
+  - code-quality
+  - linting
+  - formatting
+  - best-practices
+appliesTo:
+  - commands
+  - agents
+enforcesOn:
+  - python-backend-engineer
+  - python-backend-expert
+  - nodejs-backend-engineer
+  - javascript-frontend-engineer
+  - bash-scripting-expert
+---
+
+# Code Quality Standards Rule
+
+**MANDATORY**: All code must adhere to language-specific quality standards verified through Context7 best practices.
+
+## Purpose
+
+Ensure consistent, maintainable, and high-quality code across all programming languages by enforcing:
+- Language-specific style guides
+- Linting and formatting tools
+- Type safety requirements
+- Code complexity limits
+- Documentation standards
+
+## Context7-Verified Standards by Language
+
+### Python (from /python/cpython, /websites/fastapi_tiangolo)
+
+**Type Hints (MANDATORY):**
+```python
+# ✅ CORRECT - Use latest type hints
+from typing import AsyncIterator, ParamSpec, TypeIs, TYPE_CHECKING
+from collections.abc import Sequence
+
+# AsyncIterator for async generators
+async def infinite_stream(start: int) -> AsyncIterator[int]:
+    while True:
+        yield start
+        start = await increment(start)
+
+# ParamSpec for type-safe decorators
+P = ParamSpec('P')
+R = TypeVar('R')
+
+def decorator(f: Callable[P, R]) -> Callable[P, R]:
+    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+        return f(*args, **kwargs)
+    return inner
+
+# TypeIs for type narrowing
+def is_str_list(val: list[object]) -> TypeIs[list[str]]:
+    return all(isinstance(x, str) for x in val)
+
+# TYPE_CHECKING for conditional imports
+if TYPE_CHECKING:
+    import expensive_mod
+
+# ❌ INCORRECT - Old-style or missing type hints
+def process(data):  # Missing return type
+    pass
+
+def old_style(items: List[str]):  # Use list[str] instead
+    pass
+```
+
+**Linting Tools:**
+- **ruff**: Fast Python linter and formatter
+- **mypy**: Static type checker
+- **black**: Code formatter
+- **isort**: Import sorting
+
+**Configuration:**
+```toml
+# pyproject.toml
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+select = ["E", "F", "I", "N", "W", "UP", "B", "A", "C4", "DTZ", "T10", "EM", "ISC", "ICN", "PIE", "PYI", "PT", "Q", "RET", "SIM", "TID", "ARG", "PTH", "PD", "PGH", "PL", "TRY", "NPY", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.black]
+line-length = 100
+target-version = ['py311']
+```
+
+**Code Complexity:**
+- Maximum function length: 50 lines
+- Maximum cyclomatic complexity: 10
+- Maximum function arguments: 5
+
+### JavaScript/TypeScript (from /airbnb/javascript)
+
+**ES6 Standards (MANDATORY):**
+```javascript
+// ✅ CORRECT - ES6 best practices
+
+// Default parameters
+function handleThings(opts = {}) {
+  // ...
+}
+
+// Object property shorthand
+const lukeSkywalker = 'Luke Skywalker';
+const obj = { lukeSkywalker };
+
+// Object method shorthand
+const atom = {
+  value: 1,
+  addValue(value) {
+    return atom.value + value;
+  },
+};
+
+// Spread operator
+const original = { a: 1, b: 2 };
+const copy = { ...original, c: 3 };
+
+// Destructuring
+const { firstName, lastName } = user;
+const [first, ...rest] = array;
+
+// Arrow functions
+const items = [1, 2, 3].map(x => x * 2);
+
+// ❌ INCORRECT - Old patterns
+
+// No default parameters
+function handleThings(opts) {
+  opts = opts || {};
+}
+
+// Long form object
+const obj = { lukeSkywalker: lukeSkywalker };
+
+// Function expression instead of arrow
+const items = [1, 2, 3].map(function(x) {
+  return x * 2;
+});
+```
+
+**Linting Tools:**
+- **ESLint**: JavaScript linter with Airbnb config
+- **Prettier**: Code formatter
+- **TypeScript**: Static type checking
+
+**Configuration:**
+```json
+// .eslintrc.json
+{
+  "extends": ["airbnb-base", "prettier"],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-console": "warn",
+    "prefer-const": "error",
+    "prefer-arrow-callback": "error",
+    "prefer-template": "error",
+    "prefer-destructuring": "error",
+    "object-shorthand": "error"
+  }
+}
+
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+```
+
+### Node.js (from /nodejs/node)
+
+**Async Patterns (MANDATORY):**
+```javascript
+// ✅ CORRECT - Modern async patterns
+
+// Async iteration with for await...of
+import * as readline from 'node:readline';
+
+async function processLineByLine() {
+  const rl = readline.createInterface({
+    input: fs.createReadStream('file.txt'),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    // Process line
+  }
+}
+
+// AbortSignal for cancellation
+const ac = new AbortController();
+const { signal } = ac;
+
+setTimeout(() => ac.abort(), 5000);
+
+for await (const event of on(ee, 'foo', { signal })) {
+  console.log(event);
+}
+
+// Symbol.asyncIterator for custom iterators
+const asyncIterable = {
+  async *[Symbol.asyncIterator]() {
+    yield 1;
+    yield 2;
+    yield 3;
+  },
+};
+
+// ❌ INCORRECT - Old patterns
+
+// Using callbacks instead of async/await
+fs.readFile('file.txt', (err, data) => {
+  if (err) throw err;
+  console.log(data);
+});
+
+// No AbortSignal for cancellation
+// No Symbol.asyncIterator for iterables
+```
+
+**Event Loop Optimization:**
+- Use `setImmediate()` for I/O callbacks
+- Avoid blocking the event loop
+- Use worker threads for CPU-intensive tasks
+- Stream large datasets instead of loading into memory
+
+### Bash (from /bobbyiliev/introduction-to-bash-scripting)
+
+**Error Handling (MANDATORY):**
+```bash
+#!/usr/bin/env bash
+
+# ✅ CORRECT - Proper error handling
+
+# Exit on error, undefined variable, pipe failure
+set -euo pipefail
+
+# Logging function
+log() {
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*"
+}
+
+# Error handling function
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit 1
+}
+
+# Cleanup function
+cleanup() {
+    log "Cleaning up..."
+    # Cleanup code
+}
+
+# Register cleanup on exit
+trap cleanup EXIT
+
+# Well-documented function
+#######################################
+# Description: Calculate sum
+# Globals: None
+# Arguments: $1 - First number, $2 - Second number
+# Outputs: Sum of the two numbers
+# Returns: 0 if successful
+#######################################
+sum() {
+    local result=$(( $1 + $2 ))
+    echo "$result"
+}
+
+# ❌ INCORRECT - No error handling
+#!/bin/bash
+# No set -e
+# No error handlers
+# No cleanup
+# No function documentation
+```
+
+**Linting Tools:**
+- **shellcheck**: Shell script linter
+- **shfmt**: Shell script formatter
+
+**Configuration:**
+```bash
+# .shellcheckrc
+enable=all
+shell=bash
+severity=style
+
+# shfmt options
+# -i 4    : indent with 4 spaces
+# -bn     : binary ops like && and | may start a line
+# -ci     : switch cases will be indented
+# -sr     : redirect operators followed by a space
+```
+
+## Universal Quality Standards
+
+### Documentation (ALL LANGUAGES)
+
+**Function/Method Documentation:**
+- Purpose and behavior
+- Parameters with types
+- Return value and type
+- Exceptions/errors raised
+- Usage examples
+
+**Code Comments:**
+- Explain "why" not "what"
+- Document complex algorithms
+- Note edge cases
+- Link to relevant issues/docs
+
+### Testing Requirements
+
+**Minimum Coverage:**
+- Unit tests: 80% coverage
+- Critical paths: 100% coverage
+- Integration tests for all APIs
+- E2E tests for critical workflows
+
+**Test Quality:**
+- Descriptive test names
+- Arrange-Act-Assert pattern
+- Independent tests (no interdependencies)
+- Fast execution (<5 minutes for full suite)
+
+### Security Standards
+
+**Input Validation:**
+- Validate all external inputs
+- Sanitize user data
+- Use parameterized queries
+- Escape output for XSS prevention
+
+**Secrets Management:**
+- No hardcoded credentials
+- Use environment variables
+- Leverage secret managers
+- Rotate credentials regularly
+
+### Performance Standards
+
+**Code Performance:**
+- O(n log n) or better algorithms
+- Avoid N+1 queries
+- Use connection pooling
+- Cache frequently accessed data
+
+**Memory Management:**
+- No memory leaks
+- Proper resource cleanup
+- Stream large datasets
+- Monitor memory usage
+
+## Enforcement Actions
+
+### Pre-commit Hooks
+
+```bash
+# Python
+ruff check .
+mypy .
+black --check .
+
+# JavaScript/TypeScript
+npm run lint
+npm run type-check
+npm run format:check
+
+# Bash
+shellcheck **/*.sh
+shfmt -d .
+```
+
+### CI/CD Pipeline
+
+```yaml
+# Quality gates
+- lint: MUST pass
+- type-check: MUST pass
+- format-check: MUST pass
+- tests: MUST pass with >80% coverage
+- security-scan: MUST have no high/critical vulnerabilities
+```
+
+### Code Review Checklist
+
+- [ ] Code follows language-specific style guide
+- [ ] All functions have type hints/annotations
+- [ ] Error handling is comprehensive
+- [ ] Tests cover new functionality
+- [ ] Documentation is updated
+- [ ] Security best practices followed
+- [ ] Performance considerations addressed
+- [ ] Complexity within limits
+
+## Tools Integration
+
+### IDE Configuration
+
+**VSCode:**
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true,
+    "source.organizeImports": true
+  },
+  "python.linting.ruffEnabled": true,
+  "python.linting.mypyEnabled": true,
+  "python.formatting.provider": "black",
+  "eslint.validate": ["javascript", "typescript"],
+  "prettier.enable": true
+}
+```
+
+### Git Hooks (Husky)
+
+```json
+{
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged",
+      "pre-push": "npm test"
+    }
+  },
+  "lint-staged": {
+    "*.py": ["ruff check", "black", "mypy"],
+    "*.{js,ts}": ["eslint --fix", "prettier --write"],
+    "*.sh": ["shellcheck", "shfmt -w"]
+  }
+}
+```
+
+## Exceptions
+
+Quality standards may be relaxed for:
+- Prototype/POC code (must be marked clearly)
+- Generated code (with clear attribution)
+- Third-party code (must be isolated)
+- Legacy code being deprecated
+
+All exceptions MUST:
+- Be documented
+- Have tracking issue
+- Include remediation plan
+- Get explicit approval
+
+## Monitoring
+
+**Quality Metrics:**
+- Linting violations: 0 target
+- Type coverage: 100% target
+- Test coverage: >80% target
+- Code complexity: <10 cyclomatic complexity
+- Documentation coverage: >90% target
+
+**Regular Audits:**
+- Weekly: Automated quality reports
+- Monthly: Manual code reviews
+- Quarterly: Dependency updates
+- Annually: Major version upgrades
+
+## References
+
+- Python: [PEP 8](https://peps.python.org/pep-0008/), [Type Hints](https://docs.python.org/3/library/typing.html)
+- JavaScript: [Airbnb Style Guide](https://github.com/airbnb/javascript)
+- Node.js: [Best Practices](https://github.com/goldbergyoni/nodebestpractices)
+- Bash: [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+- Context7: Query `mcp://context7/<language>/style-guide` for latest standards
+
+---
+
+**Enforcement Level**: MANDATORY
+**Review Frequency**: Every commit
+**Last Updated**: 2025-01-15
+**Context7 Verified**: ✅ All patterns verified against latest documentation