javascript.yaml

# JavaScript Code Review Guidelines
# Comprehensive rules for JavaScript code quality, security, and best practices

name: JavaScript Code Review Guidelines
description: Guidelines for reviewing JavaScript code covering security, performance, best practices, and common pitfalls
globs:
  - "**/*.js"
  - "**/*.jsx"
  - "**/*.mjs"
  - "**/*.cjs"

areas:
  - name: security
    description: Security-related rules to prevent vulnerabilities
    rules:
      - name: avoid-eval
        description: Never use eval(), new Function(), or setTimeout/setInterval with string arguments. These execute arbitrary code and are major security risks. Use JSON.parse() for JSON, and proper parsers for other formats.
        severity: high
        
      - name: avoid-innerhtml
        description: Never use innerHTML, outerHTML, or document.write() with user input. Use textContent for plain text, or sanitize with DOMPurify. Prefer DOM manipulation methods or framework-safe methods.
        severity: high
        
      - name: prevent-prototype-pollution
        description: Validate object keys before bracket notation with user input. Use Object.create(null) for lookup objects. Check for __proto__, constructor, and prototype keys. Consider using Map instead.
        severity: high
        
      - name: prevent-regex-dos
        description: Avoid regex patterns with nested quantifiers or overlapping alternations that can cause catastrophic backtracking. Limit input length before regex matching. Test patterns with safe-regex.
        severity: high
        
      - name: validate-urls
        description: Always validate URLs before use in fetch, redirects, or links. Check for javascript colon, data URIs, and file protocols. Use URL constructor for parsing. Whitelist allowed protocols.
        severity: high
        
      - name: secure-cookies
        description: Set Secure, HttpOnly, and SameSite attributes on cookies. Never store sensitive data in cookies without encryption. Use short expiration times for session cookies.
        severity: high
        
      - name: avoid-document-domain
        description: Never set document.domain as it weakens same-origin policy. Use postMessage for cross-origin communication. This property is deprecated and will be removed from browsers.
        severity: high

  - name: performance
    description: Performance optimization rules
    rules:
      - name: prevent-memory-leaks
        description: Remove event listeners when components unmount. Clear intervals and timeouts. Nullify references to large objects. Use WeakMap/WeakSet for object metadata. Watch for detached DOM nodes.
        severity: high
        
      - name: cleanup-event-listeners
        description: Always remove event listeners when they're no longer needed. Use AbortController for multiple listeners. Store listener references for removal. Consider using event delegation.
        severity: high
        
      - name: batch-dom-operations
        description: Minimize DOM access and manipulation. Batch DOM reads and writes separately to avoid layout thrashing. Use DocumentFragment for multiple insertions. Consider virtual DOM libraries.
        severity: medium
        
      - name: use-requestanimationframe
        description: Use requestAnimationFrame for visual animations instead of setTimeout/setInterval. Cancel animations with cancelAnimationFrame. Use requestIdleCallback for non-urgent work.
        severity: medium
        
      - name: debounce-throttle
        description: Debounce or throttle high-frequency events like scroll, resize, and input. Prevents performance issues from excessive event handler calls. Use appropriate delay values.
        severity: medium
        
      - name: avoid-synchronous-operations
        description: Avoid synchronous XMLHttpRequest, localStorage in hot paths, and other blocking operations. Use async alternatives. Consider Web Workers for CPU-intensive tasks.
        severity: medium
        
      - name: efficient-loops
        description: Cache array length in for loops for large arrays. Use for-of for iterables. Prefer array methods for clarity but be aware of callback overhead. Avoid forEach for early termination needs.
        severity: low

  - name: best_practices
    description: JavaScript best practices and idioms
    rules:
      - name: use-strict-equality
        description: Always use === and !== instead of == and !=. Loose equality has confusing coercion rules. The only exception is checking null == undefined as a shorthand.
        severity: high
        
      - name: use-const-let
        description: Prefer const by default, use let only when reassignment is needed. Never use var. const prevents accidental reassignment and signals intent. let has proper block scoping.
        severity: medium
        
      - name: proper-promise-handling
        description: Always handle Promise rejections with .catch() or try/catch with async/await. Never ignore Promise results. Use Promise.allSettled() when you need all results regardless of failures.
        severity: high
        
      - name: structured-error-handling
        description: Throw Error objects, not strings or other types. Include meaningful error messages. Use error.cause for error chaining. Log errors with full context. Don't swallow errors silently.
        severity: medium
        
      - name: use-optional-chaining
        description: Use optional chaining (?.) instead of && chains for property access. Use nullish coalescing (??) instead of || for default values to properly handle 0 and empty strings.
        severity: low
        
      - name: use-template-literals
        description: Use template literals for string interpolation instead of concatenation. They're more readable and support multi-line strings. Use tagged templates for safe HTML generation.
        severity: low

  - name: common_pitfalls
    description: Common JavaScript pitfalls to avoid
    rules:
      - name: understand-hoisting
        description: Be aware that var and function declarations are hoisted. let and const are in the temporal dead zone until declared. Declare variables at the top of their scope for clarity.
        severity: medium

      - name: closure-issues
        description: Be careful with closures in loops - use let instead of var, or create new scopes. Closures capture variables by reference, not value. This is a common source of bugs with async callbacks.
        severity: high

      - name: this-binding
        description: Understand this binding rules - it depends on how the function is called. Use arrow functions to preserve lexical this. Use bind(), call(), or apply() when needed. Avoid this in callbacks.
        severity: medium

      - name: floating-point-precision
        description: Be aware of floating-point precision issues. Never use === for comparing decimal numbers. Use Number.EPSILON or multiply to integers for comparisons. Consider decimal.js for financial calculations.
        severity: medium

      - name: array-reference-equality
        description: Arrays and objects are compared by reference, not value. Use deep equality functions for comparison. Be careful with indexOf/includes for object arrays. Consider using JSON.stringify for simple cases.
        severity: medium

      - name: implicit-globals
        description: Accidentally creating global variables is a common bug. Always declare variables with const/let. Use strict mode to catch this. Avoid relying on global state.
        severity: high

      - name: async-iteration
        description: forEach doesn't await async callbacks. Use for...of with await for sequential async operations. Use Promise.all with map for parallel operations. Never ignore async errors in loops.
        severity: high

      - name: typeof-null
        description: Remember that typeof null returns 'object' due to a historical bug. Use === null for null checks. Use Object.prototype.toString for accurate type detection of built-ins.
        severity: low

      - name: parseint-radix
        description: Always provide the radix parameter to parseInt() to avoid unexpected octal parsing. Use Number() for simple conversions. Consider using unary + for brief number conversion.
        severity: medium

      - name: automatic-semicolon-insertion
        description: Be aware of ASI rules to avoid bugs. Always use semicolons or configure a linter to enforce consistency. Be careful with return statements and object literals on new lines.
        severity: medium