IMPORTANT

When working with PMD rules, XPath expressions, Apex AST structure, testing, or code analysis, always reference these documentation files:

Core PMD & Rule Development:

• @docs/PMD.md - PMD (source code analyzer) quick reference and essentials for Salesforce Code Analyzer integration (includes Apex AST reference)
• @docs/XPATH31.md - XPath 3.1 syntax, functions, and expressions reference
• @docs/CODEANALYZER.md - Quick reference for configuring code-analyzer.yml with all engines and properties (includes Regex engine configuration)

Documentation & Suppression:

• @docs/APEXDOC.md - ApexDoc syntax, tags, and documentation format for Apex code
• @docs/PMD.md - How to suppress PMD rule violations using annotations, comments, and rule properties (see Suppressing Warnings section)

Testing & Development:

• @docs/JEST.md - Jest 30.0 API reference for writing and running tests
• @docs/PNPM.md - pnpm package manager reference for dependency management and workspace configuration
• @docs/HUSKY.md - Husky reference for Git hooks management and configuration

Additional Code Analyzer Engines:

• @docs/PMD.md - Copy/Paste Detector (CPD) engine for duplicate code detection across multiple languages (see CPD section)
• @docs/ESLINT.md - ESLint engine configuration for JavaScript, TypeScript, and LWC static analysis

Graph Engine Documentation:

• @docs/GRAPHENGINE.md - Salesforce Graph Engine configuration and usage
• @docs/GREMLIN.md - Gremlin query language reference for graph traversal
• @docs/TINKERPOP.md - Apache TinkerPop framework reference for graph computing
• @docs/GRAPHML.md - GraphML format for graph serialization
• @docs/GRAPHSON.md - GraphSON format for graph serialization
• @docs/GRYO.md - Gryo binary format for graph serialization
• @docs/GRAPHBINARY.md - GraphBinary format for graph serialization

Use these documents to:

• Understand PMD fundamentals and how it integrates with Salesforce Code Analyzer
• Understand how Apex code is represented in the PMD AST (see PMD.md Apex AST Reference section)
• Write correct XPath expressions that match AST nodes
• Reference XPath 3.1 syntax and functions when writing rule queries
• Ensure XPath expressions correctly traverse the AST structure
• Access rule examples, violations, valid code patterns, and configuration properties
• Configure code-analyzer.yml with proper engines and properties
• Write and maintain Jest tests using the Jest 30.0 API
• Manage dependencies and workspaces using pnpm
• Configure Git hooks using Husky
• Understand ApexDoc syntax and documentation requirements
• Suppress rule violations when necessary (see PMD.md Suppressing Warnings section)
• Configure additional Code Analyzer engines (CPD, ESLint, Regex)
• Understand graph engine configuration and usage (Graph Engine, Gremlin, TinkerPop)
• Reference graph serialization formats (GraphML, GraphSON, Gryo, GraphBinary)

When creating or modifying PMD rules:

1. Reference @docs/PMD.md for PMD fundamentals and integration details
2. Check @docs/PMD.md Apex AST Reference section for the correct AST node types and patterns
3. Use @docs/XPATH31.md for XPath 3.1 syntax and function reference
4. Use @docs/CODEANALYZER.md for configuring code-analyzer.yml with engines and properties
5. Use @docs/CODEANALYZER.md Regex Engine section for creating pattern-based Regex rules
6. Reference @docs/PMD.md Suppressing Warnings section when implementing suppression mechanisms
7. When fixing rules to comply with unit tests, always start by dumping the AST - Use pnpm ast-dump <apex-file> to inspect the actual AST structure of test fixtures before modifying XPath expressions. This ensures you understand the exact node structure and relationships before making changes.
8. XML Schema Location: The xsi:schemaLocation attribute in ruleset XML files must use http://pmd.sourceforge.net/ruleset/2.0.0 (with dots) for the namespace and https://pmd.sourceforge.io/ruleset_2_0_0.xsd (with underscores) for the schema URL. Do not use 2_0_0.xsd in the namespace.
9. Apex File Structure: Apex files can only contain one top-level class. Test fixtures must use a single class with multiple methods or fields to test different scenarios, not multiple top-level classes.
10. Single-Line Comments in AST: PMD's Apex parser does not include single-line comments (//) in the AST. Only block comments (/* */) and ApexDoc comments (/** */) are included as FormalComment nodes. For rules that need to detect single-line comments (e.g., // prettier-ignore, // NOPMD), use regex-based rules instead of PMD XPath rules. See @docs/CODEANALYZER.md Regex Engine section for creating regex-based rules.
11. Regex Rules Must Be Added to code-analyzer.yml: When creating regex rules, you must add them to code-analyzer.yml under engines.regex.custom_rules. Unlike PMD rules (which are XML files in rulesets/), regex rules are defined directly in code-analyzer.yml. Always add new regex rules to the repository's code-analyzer.yml file, not just in test files. See CONTRIBUTING.md for complete instructions.
12. Every rule should use properties for things that should be configurable - Add configurable properties (thresholds, lists, etc.) instead of hardcoding values
13. New subfolders can be created under rulesets/ - Make sure they follow PMD's 8 standard categories (bestpractices, codestyle, design, documentation, errorprone, multithreading, performance, security)
14. Every rule must have both positive and negative test cases - Create test fixtures in tests/fixtures/positive/ and tests/fixtures/negative/ covering all parts of the XPath expression
15. XML element order must be correct - PMD ruleset XML files must follow the PMD Ruleset XML Schema. Elements within <rule> must appear in this order: description → priority → properties → exclude → example. Use pnpm check-xml-order to verify order, or pnpm fix-xml-order to automatically fix it. These scripts use XML libraries (xmldom) to properly parse and manipulate XML, ensuring all elements (including multiple examples) are preserved.
16. All code should be linted and formatted following any changes - Run pnpm format and pnpm lint (or pnpm lint:fix). CRITICAL: Always run lint commands with full permissions - Use required_permissions: ['all'] when running lint commands. ESLint will fail with EPERM: operation not permitted errors when run without full permissions due to pnpm's module resolution requiring full filesystem access to read files from node_modules/.pnpm/.
17. All tests should be run and regressions checked following any changes - Run pnpm test and verify no test regressions. CRITICAL: Always run pnpm test with full permissions the first time - Use required_permissions: ['all'] when running test commands. Jest will fail with module resolution errors (e.g., "Cannot find module '@jest/test-sequencer'") when run without full permissions due to pnpm's module resolution requiring full filesystem access. After the first successful run, subsequent runs may work without full permissions, but always use full permissions for initial test runs. Reference @docs/JEST.md for Jest API usage when writing or modifying tests.
18. README.md should be updated with any pertinent changes - Document new rules, rule changes, or significant updates in the README. When adding a new rule:
    • Add a short description in the rule categories section (e.g., under "Documentation Quality")
    • Add a comprehensive rule documentation section with priority, source link, description, violations, and valid code examples
    • Update the rule count in the "Rule Categories" section
    • Add the rule to the comprehensive code-analyzer.yml example in README.md
19. PLAN.md is a planning document - PLAN.md should be written as if the project has not yet been created. It details what needs to happen to create the project, not the current state of the project. PLAN.md should:
    • Use future tense ("will be", "should be", "needs to", "must be")
    • Describe implementation steps and phases
    • Include requirements and prerequisites
    • Focus on what needs to be done to create the project
    • NOT describe current project state, what already exists, or how things currently work
    • NOT include historical context or references to past states
    • The current state of the project is documented in README.md and other documentation files, not in PLAN.md
20. Test XPath expressions against both positive and negative test cases
21. Benchmark stress tests must be kept up to date - When adding or modifying rules, update the benchmark fixtures:
    • New rules: Add violations to benchmarks/fixtures/stress-test-all-rules.cls and the appropriate category-specific fixture (e.g., stress-code-style.cls, stress-design.cls, stress-best-practices.cls)
    • Rule modifications: Update existing violations in stress test fixtures to reflect rule changes
    • Target 10-20 violations per rule in stress tests to properly benchmark performance
    • Use realistic code patterns that developers might actually write
    • Update benchmarks/FIXTURES.md with new violation counts and rule coverage
    • Run benchmarks after updates: pnpm benchmark to verify performance
    • Regenerate baseline if needed: pnpm benchmark -- --baseline after significant changes
22. Stress test fixtures location: benchmarks/fixtures/ contains comprehensive stress-test files:
    • stress-test-all-rules.cls - Comprehensive fixture with violations across all 43 PMD rules
    • stress-code-style.cls - Code style rules (21 rules, 300+ violations, includes naming)
    • stress-design.cls - Design rules (15 rules, 130+ violations, includes structure and method signatures)
    • stress-best-practices.cls - Best practices rules (5 rules, 100+ violations, includes modifiers)
    • stress-documentation.cls - Documentation rules (2 rules, 30+ violations)
    • Note: Regex rules (NoConsecutiveBlankLines, ProhibitPrettierIgnore, ProhibitSuppressWarnings, NoLongLines) are not included in PMD benchmark fixtures as they use a different engine.
23. Running specific tests: When debugging or working on a specific rule, use Jest's --testNamePattern flag to run only matching tests instead of the full test suite. This saves time and focuses output. Reference @docs/JEST.md for Jest CLI options and API. The pattern matches test names using regex:
    • Run all tests for a specific rule: pnpm test -- --testNamePattern="RuleName" (matches any test containing "RuleName")
    • Run only detection tests: pnpm test -- --testNamePattern="should detect" (matches tests with "should detect" in the name)
    • Run a specific test for a rule: pnpm test -- --testNamePattern="RuleName.*should detect" (matches tests starting with "RuleName" and containing "should detect")
    • Concrete examples:
      • pnpm test -- --testNamePattern="AnnotationBeforeComment" - Runs all AnnotationBeforeComment tests (both positive and negative cases)
      • pnpm test -- --testNamePattern="ProhibitSuppressWarnings.*should detect" - Runs only the "should detect" test for ProhibitSuppressWarnings rule
      • pnpm test -- --testNamePattern="should not flag" - Runs all tests that verify rules don't produce false positives
24. Using PMD AST dump tool: Use the AST dump script to inspect the actual AST structure of Apex files:
    • pnpm ast-dump <apex-file> - Dump AST for a file (text format)
    • pmd ast-dump --file=<apex-file> -l apex -f xml - Dump AST in XML format
    • pmd ast-dump --file=<apex-file> -l apex -f xml > output.ast.xml - Save AST to file
    • Examples:
      • pnpm ast-dump tests/fixtures/negative/codestyle/ProhibitSuppressWarnings.cls
      • pmd ast-dump --file=tests/fixtures/positive/documentation/AnnotationBeforeComment.cls -l apex -f xml | grep -E "Method|FormalComment|Annotation"
    • Note: Files with syntax errors cannot be parsed. Fix syntax errors first or use valid test files for AST inspection.
    • Tip: Use AST dump to understand node relationships, attributes, and structure before writing XPath expressions.
25. PMD command execution: Always use the -r <file> flag when running PMD commands to avoid progressbar rendering conflicts with STDOUT. PMD will show a warning: [WARN] Progressbar rendering conflicts with reporting to STDOUT. No progressbar will be shown. Try running with argument -r <file> to output the report to a file instead. To prevent this warning, always redirect PMD output to a file using the -r flag:
    • Correct: pmd check --no-cache -d "${file}" -R "${ruleset}" -f xml -r "${outputFile}"
    • Incorrect: pmd check --no-cache -d "${file}" -R "${ruleset}" -f xml (outputs to STDOUT, causes warning)
    • The tests/helpers/pmd-helper.js file already implements this correctly - any new PMD invocations should follow the same pattern
    • When running PMD manually or in scripts, always use -r <file> to write output to a file, then read the file contents
26. Version bumping: Always run pnpm bump-rule-versions after making rule changes - This script automatically bumps rule versions based on changes:
    • Major bump (X.0.0): Rules with failing existing tests (tests that existed at HEAD) - indicates breaking changes
    • Minor bump (0.X.0): Rules with new tests - indicates new features
    • Patch bump (0.0.X): Other changed rules - indicates bug fixes/improvements
    • The script runs tests, detects failures, checks git history, and bumps versions accordingly
    • Run this before committing rule changes to ensure proper versioning
27. Script security: Scripts must implement security best practices - When creating or modifying scripts in scripts/, follow these security guidelines:
    • File System Operations: Use file descriptors instead of file paths to prevent time-of-check to time-of-use (TOCTOU) race conditions:
      • Never use fs.existsSync() before opening files - This creates a race condition. Instead, open files directly and handle errors if they don't exist
      • Use fs.openSync() with appropriate flags (O_RDWR for read-write, O_CREAT | O_WRONLY | O_TRUNC for write-only, O_RDONLY for read-only)
      • Wrap file open operations in try-catch to handle cases where files don't exist
      • Use the same file descriptor for both read and write operations when possible
      • Always close file descriptors in finally blocks to ensure cleanup
      • Use fs.readFileSync(fd, ...) and fs.writeFileSync(fd, ...) with file descriptors instead of paths
      • Use fs.ftruncateSync(fd, 0) before writing when overwriting files
      • Example pattern: Open file directly, catch errors if it doesn't exist, then read/write using the file descriptor
    • Shell Command Execution: Use execFileSync instead of execSync when passing dynamic paths or arguments:
      • Pass command and arguments separately: execFileSync('git', ['show', path], {...})
      • Avoid constructing shell commands with string interpolation
      • This prevents shell command injection vulnerabilities
    • Path Validation (for user input): Scripts accepting file paths from user input (e.g., from process.argv or command line arguments) must:
      • Use the sanitize-filename package to sanitize file paths, eliminating dangerous characters
      • Validate paths to prevent path traversal attacks (reject paths containing .. sequences)
      • Reject absolute paths when relative paths are expected (use path.isAbsolute())
      • Use fs.realpathSync() to resolve symbolic links and validate that resolved paths are within expected directories
      • Implement defense in depth with multiple validation layers
    • See scripts/benchmark.js, scripts/bump-rule-versions.js, scripts/check-performance-regressions.js, and scripts/ast-dump.sh for reference implementations
    • For more details, see SECURITY.md and CONTRIBUTING.md (Security Best Practices for Scripts section)