v2.0.x Chore - add custom ast-grep rules

[reactive-firewall]

project specific ast-grep rules

the powerful tool ast-grep could be better leveraged for the project, with targeted custom rules

Context and background information

Regarding a recent review of 'docs/FAQ.md' @coderabbitai observed

API examples are correct but could be improved

The Python API examples in the FAQ are accurate and match the implementation, as they use the correct class (McastDispatch) and method (doStep) with proper argument structure. However, the examples could be enhanced by:

• Adding error handling with try-except blocks (already present)
• Including comments about default values (port=59259, group='224.0.0.1')
• Mentioning that the message argument is required
• Documenting that the function returns a tuple of (success_bool, result)

The following scripts were executed for the analysis:

Script:

#! /bin/bash
# Description: Verify Python API examples match the implementation

# Test: Check if the API classes and methods exist
ast-grep --pattern $'class McastRECV {
  $$$
  doStep($$$) {
    $$$
  }
}'

ast-grep --pattern $'class McastHEAR {
  $$$
  doStep($$$) {
    $$$
  }
}'

Length of output: 153

---

Script:

#!/bin/bash
# Let's check for the actual McastDispatch class and its methods
ast-grep --pattern $'class McastDispatch {
  $$$
  doStep($$$) {
    $$$
  }
}'

# Search for any Python files that might contain the implementation
fd -e py --exec cat {}

# Look for specific imports and usage patterns
rg "class Mcast" -A 5

Length of output: 270032

---

Script:

#!/bin/bash
# Let's check for McastDispatch.doStep implementation
ast-grep --pattern $'class McastDispatch {
  $$$
  doStep($$$) {
    $$$
  }
}'

# Let's verify the example's SAY arguments match the implementation
rg "McastDispatch\(\)\.doStep\(\[\"SAY\"," -A 2

Length of output: 838

---

Script:

#!/bin/bash
# Let's check the actual implementation of McastSAY class
ast-grep --pattern $'class McastSAY {
  $$$
  doStep($$$) {
    $$$
  }
}'

# Let's also check for any port/group validation in the code
rg "port.*=.*kwargs\.get.*" -A 2
rg "group.*=.*kwargs\.get.*" -A 2

Length of output: 936

---

Originally posted by @coderabbitai[bot] in #184 (review)

[reactive-firewall]

also consider:

#! /bin/bash
# Description: Verify the method implementation and its usage across the codebase

# Check for the new method implementation
ast-grep --pattern $'def _should_get_package_version_WHEN_valid(self):
  $$$'

# Check for any remaining old method calls
rg '_get_package_version\(' --type py

[reactive-firewall]

also consider:

#! /bin/bash

# Check for other test files that might conflict or complement this test suite
printf "Checking for related test files...\n"
fd -t f -e py "test_.*server.*\.py$" tests/

# Look for McastServer usage across the codebase
printf "\nChecking McastServer usage...\n"
rg -l "class McastServer"

# Check for potential test gaps by looking for untested methods
printf "\nChecking for potentially untested server methods...\n"
ast-grep --pattern 'class McastServer {
  $$$
  def $METHOD($$$) {
    $$$
  }
  $$$
}'

[reactive-firewall]

also consider:

#!/bin/bash
# Search for property definitions and message/exit_code handling in CommandExecutionError
ast-grep --pattern 'class CommandExecutionError {
  $$$
  message = $$$
  $$$
}'

# Get the complete implementation of the class
rg -A 20 'class CommandExecutionError' multicast/exceptions.py

---

also consider:

#!/bin/bash
# Search for the complete implementation of CommandExecutionError class
ast-grep --pattern 'class CommandExecutionError {
  $$$
  __init__($$$) {
    $$$
  }
  $$$
}'

# Search for any properties or methods defined in CommandExecutionError
rg -A 2 'def ' multicast/exceptions.py

---

also consider:

#!/bin/bash
# Description: Check for any untested methods or properties in CommandExecutionError

# Search for CommandExecutionError implementation
ast-grep --pattern 'class CommandExecutionError {
  $$$
}'

# Search for any properties or methods that might need testing
rg -A 5 'CommandExecutionError' --type py

[reactive-firewall]

@coderabbitai, consider the discussions in this GHI ( #207 ) and walk me through implementing the specific ast-grep patterns as re-useable configurations/rules/templates (e.g. however ast-grep usually configures these kinds of things), including the specific suggested implementations. Consider the primary goal of this larger task is to configure ast-grep used in your reviews to include these kinds of checks.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

Let me analyze the output and refine my approach. I notice there are several Python files and test patterns that we can use to create more specific and relevant ast-grep rules.

@reactive-firewall Let me propose a more targeted set of ast-grep rules based on your actual codebase structure:

# .ast-grep/rules.yml
rules:
  # Rule for multicast server implementation patterns
  mcast-server-pattern:
    pattern: |
      class Mcast$TYPE:
        $$$
        def doStep(self, $ARGS):
          $$$
    language: python
    message: "Verify Mcast server implementation follows standard pattern"
    severity: error

  # Rule for exception handling pattern
  exception-pattern:
    pattern: |
      try:
        $$$
      except Exception as err:
        raise CommandExecutionError(str(err))
    language: python
    message: "Ensure proper exception handling with CommandExecutionError"
    severity: warning

  # Rule for test class patterns
  test-class-pattern:
    pattern: |
      class Test$NAME($$$):
        $$$
        def test_$METHOD_WHEN_$CONDITION(self):
          $$$
    language: python
    message: "Test classes should follow naming convention and include WHEN conditions"
    severity: warning

  # Rule for UDP client implementation
  udp-client-pattern:
    pattern: |
      class MulticastUDPClient($$$):
        $$$
        def __init__(self, $$$):
          $$$
        def $METHOD(self, $$$):
          $$$
    language: python
    message: "Verify UDP client implementation follows project standards"
    severity: error

  # Rule for module initialization
  module-init-pattern:
    pattern: |
      """$$$"""
      
      from $$$
      
      __version__ = $VERSION
    language: python
    message: "Module initialization should include docstring and version"
    severity: warning

These rules are specifically tailored to your codebase patterns, focusing on:

1. Multicast Server Components: Captures the pattern used in hear.py, recv.py, and send.py
2. Exception Handling: Based on patterns in exceptions.py
3. Test Structure: Derived from your extensive test suite in the tests/ directory
4. UDP Client Implementation: Based on MulticastUDPClient.py
5. Module Structure: Based on your module initialization patterns

To use these rules:

1. Create the configuration directory:

mkdir -p .ast-grep

2. Save the rules in .ast-grep/rules.yml

3. You can run specific rules using:

ast-grep --config .ast-grep/rules.yml --rule mcast-server-pattern

Would you like me to:

1. Add more specific patterns for any particular component?
2. Include additional validation rules for specific code patterns?
3. Add rules for documentation standards?
4. Create rules for specific error handling patterns?

Also, I notice your codebase has a strong focus on testing. Should we add more specific rules for test case patterns and assertions?

🐰 (thoughtfully considering the patterns)

🔗 Analysis chain

Let me gather information about the existing ast-grep patterns and configurations in the repository first.

Let me analyze the output and create a structured response with ast-grep rule configurations.

@reactive-firewall Based on the analysis of the codebase and the patterns used in previous reviews, I'll walk you through implementing reusable ast-grep rules. We'll create these rules in a YAML configuration file that ast-grep can use.

Let's create a new file called .ast-grep/rules.yml with the following structure:

# .ast-grep/rules.yml
rules:
  # Rule to check for proper class method implementations
  method-implementation:
    pattern: |
      class $CLASS_NAME {
        $$$
        def $METHOD($ARGS) {
          $$$
        }
        $$$
      }
    language: python
    message: "Check method implementation in class {CLASS_NAME}"

  # Rule to verify test method naming convention
  test-method-naming:
    pattern: |
      def test_$METHOD_NAME_WHEN_$CONDITION(self):
        $$$
    language: python
    message: "Test method follows naming convention: test_<method>_WHEN_<condition>"

  # Rule to check for proper exception class structure
  exception-class:
    pattern: |
      class $NAME(Exception):
        $$$
        def __init__($ARGS):
          $$$
        $$$
    language: python
    message: "Exception class should have proper initialization"

  # Rule to check for McastDispatch API usage
  mcast-dispatch-usage:
    pattern: |
      $VAR = McastDispatch()
      $$$
      $VAR.doStep(["$COMMAND", $$$])
    language: python
    message: "Check McastDispatch API usage pattern"

  # Rule to verify property definitions
  class-property:
    pattern: |
      class $CLASS_NAME:
        $$$
        @property
        def $PROP_NAME($$$):
          $$$
    language: python
    message: "Verify property implementation in class {CLASS_NAME}"

These rules cover several patterns we've used in reviews:

1. method-implementation: Checks for proper method implementations within classes
2. test-method-naming: Enforces the test method naming convention (test_WHEN)
3. exception-class: Ensures exception classes follow proper structure
4. mcast-dispatch-usage: Verifies correct usage of the McastDispatch API
5. class-property: Checks property implementations

To use these rules in your reviews, you can:

1. Create the .ast-grep directory:

mkdir -p .ast-grep

2. Save the rules configuration in .ast-grep/rules.yml

3. Run ast-grep with these rules:

ast-grep --config .ast-grep/rules.yml

You can also extend these rules by adding more patterns. For example, to add a new rule for checking docstring conventions:

  docstring-convention:
    pattern: |
      def $METHOD_NAME($$$):
        """
        $$$
        Args:
          $$$
        Returns:
          $$$
        """
        $$$
    language: python
    message: "Check docstring format for method {METHOD_NAME}"

Would you like me to:

1. Add more specific patterns based on your codebase?
2. Create additional rules for specific components?
3. Add severity levels and rule categories?

Let me know which aspects you'd like me to expand upon.

🐰 (thoughtfully taking notes)

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check for any existing ast-grep configuration files
printf "Checking for ast-grep config files...\n"
fd -t f "ast-grep.yml" -o -t f "ast-grep.yaml" -o -t f "ast-grep.json"

# Check for any existing custom rules
printf "\nChecking for custom rule files...\n"
fd -t f -e yml -e yaml -e json rules/

# Look for Python files to understand patterns we need
printf "\nListing Python source files...\n"
fd -e py

# Check for any existing test patterns
printf "\nChecking test patterns...\n"
rg -l "class.*Test" --type py

# Look for class definitions to create patterns for
printf "\nGathering class definitions...\n"
ast-grep --pattern 'class $CLASS_NAME {
  $$$
}'

Length of output: 1650

---

✏️ Learnings added

Learnt from: reactive-firewall
URL: https://github.com/reactive-firewall/multicast/issues/207

Timestamp: 2024-12-06T07:54:10.428Z
Learning: The multicast project's ast-grep rules should focus on server components (Mcast classes), exception handling patterns, test structures with WHEN conditions, UDP client implementations, and proper module initialization with docstrings and version information.

---

Learnt from: reactive-firewall
URL: https://github.com/reactive-firewall/multicast/issues/207

Timestamp: 2024-12-06T07:54:10.428Z
Learning: For ast-grep configurations in the multicast project, rules should be organized in .ast-grep/rules.yml with clear patterns, messages, and language specifications for Python code analysis.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-21T02:05:08.096Z
Learning: Reactive-firewall prefers scripts to include explicit data processing steps that produce the expected output, ensuring accurate and useful results.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:50.461Z
Learning: For future scripts, reactive-firewall prefers to use only POSIX built-ins (like `printf` instead of `echo`) to align with CEP-8 conventions.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-21T02:05:08.096Z
Learning: Reactive-firewall prefers to specify the full raw URL when fetching files from gists to ensure correct retrieval of content, particularly when the file is in markdown format.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-29T04:45:25.464Z
Learning: For future reviews, remember that reactive-firewall prefers documentation to be presented in a tone appropriate for developers, avoiding raw source code dumps, and focusing on clear explanations and real-world examples.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:55.563Z
Learning: For future scripts, reactive-firewall prefers to keep the shebang line with an extra space (e.g., `#! /bin/bash`) as per project style.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#184
File: LICENSE.md:36-43
Timestamp: 2024-11-14T07:03:35.207Z
Learning: Reactive-firewall prefers that I verify URLs before suggesting changes, and avoid raising hypothetical issues without verification.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-12-02T08:20:59.928Z
Learning: When implementing package.json, reactive-firewall prefers to maintain flexibility in npm installation methods, supporting both global (-g) installations and local project-specific installations.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-29T01:10:18.136Z
Learning: For future reviews, remember that reactive-firewall prefers documentation to be presented in a tone appropriate for developers, following the project's style and conventions.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#184
File: tests/check_pip:259-265
Timestamp: 2024-11-15T19:32:16.878Z
Learning: Reactive-firewall prefers that code changes adhere to SOLID design principles, specifically avoiding unnecessary complexity (AHA principle), maintaining the Single Responsibility Principle, and ensuring complex work is done on separate development branches (Open/Closed Principle).

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#110
File: docs/USAGE.md:66-66
Timestamp: 2024-11-12T10:29:55.563Z
Learning: Reactive-firewall prefers to use "Caveat" as a heading instead of "Caution".