Version 2.0.8 Release Candidate

.ast-grep/rules/GHA-avoid-always.yml

@@ -0,0 +1,21 @@
+# GHA-avoid-always.yml
+id: gha-jobs-should-avoid-always
+rule:
+  matches: gha_job_condition_map
+  kind: block_mapping_pair
+  has:
+    kind: flow_node
+    field: value
+    has:
+      pattern:
+        selector: plain_scalar
+        context: |
+          $$$
+      has:
+        kind: string_scalar
+        regex: \$\{\{.*always\(\).*\}\}
+fix: |
+  if: ${{ !cancelled() }}
+language: YAML
+message: 'Condition "always()" is dangerous as it runs even when the workflow is canceled. Use "if: ${{ !cancelled() }}" instead for safer execution control.'
+severity: warning

.ast-grep/rules/multicast-rule-check-class-has-documentation.yml

@@ -0,0 +1,41 @@
+# .ast-grep/multicast-rule-check-class-has-documentation.yml
+id: check-has-class-documentation
+rule:
+  pattern:
+    selector: class_definition
+    context: |
+      class $CLASS_NAME($$$)$$$:$$$
+        $BODY
+  not:
+    has:
+      matches: block_with_docstring
+      kind: block
+  kind: class_definition
+language: python
+message: "Class definitions must have documentation. However $CLASS_NAME is missing a docstring."
+severity: warning
+description: |
+  This rule ensures that all class definitions include proper documentation strings.
+  The documentation must be a triple-quoted string (''' or """) immediately after
+  the class definition.
+examples:
+  - name: Valid class documentation examples
+    code: |
+      class MyClass:
+        """
+        A class that demonstrates proper documentation.
+
+        Attributes:
+          attr1: Description of first attribute
+          attr2: Description of second attribute
+        Methods:
+          method1: Description of first method
+          method2: Description of second method
+
+        Testing:
+          >>> obj = MyClass()
+          >>> obj.method1()
+          True
+
+       """
+       pass

.ast-grep/rules/multicast-rule-check-documentation.yml

@@ -0,0 +1,14 @@
+# .ast-grep/multicast-rule-check-test-documentation.yml
+id: check-has-documentation
+rule:
+  pattern:
+    selector: function_definition
+    context: |
+      def $FUNC_NAME($PARAMS)$RET_TYPE:$$$
+        $BODY
+  kind: function_definition
+  not:
+    matches: function_docstring
+language: python
+message: "Functions should have documentation. However, $FUNC_NAME is missing a docstring."
+severity: warning

.ast-grep/rules/multicast-rule-check-test-documentation.yml

@@ -0,0 +1,62 @@
+# .ast-grep/multicast-rule-check-test-documentation.yml
+---
+id: check-test-documentation
+rule:
+  all:
+    - any:
+        - matches: data_class_docstring
+        - matches: function_docstring
+        - matches: method_docstring
+    - not:
+        all:
+          - matches: cep7_docstring_purpose
+          - matches: cep7_docstring_arguments
+          - any:
+              - matches: data_class_docstring
+              - matches: cep7_docstring_returns
+language: python
+message: "[CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20#2-docstring-style) Documentation must include purpose, args, and returns sections."
+severity: hint
+description: |
+  Ensures that Python docstrings are comprehensive with multiple sections as advocated by CEP-7.
+  [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20#2-docstring-style)
+  This rule helps maintain consistent documentation and style.
+examples:
+  - name: Valid docstring with sections examples
+    code: |
+      def something():
+        """
+        Demonstrate with imperative.
+
+        Describes the subject after a oneline gap as per PEP-257 and PEP-8 style.
+        No line gap is needed for additional documentation.
+
+        Args:
+          arg (arg type) -- indented argument detail
+
+        Returns:
+          Good documentation.
+
+        Raises:
+          TypeError: if arg is not an `arg type`
+
+        Testing:
+
+          1. Numbered Test description.
+
+          >>> indented test code
+          Test Result followed by blank lines
+
+        """
+  - name: Invalid docstring without sections examples
+    code: |
+      def something():
+        """
+        Terse descriptive phrase. Second sentence on same line.
+        No gap before next line.
+
+        Test description
+
+        >>> unindented test code
+        Test Result with no following space
+        """

.ast-grep/rules/multicast-rule-enforce-testcase-format.yml

@@ -0,0 +1,34 @@
+# .ast-grep/multicast-rule-enforce-testcase-format.yml
+id: enforce-testcase-format
+rule:
+  pattern:
+    selector: class_definition
+    context: |
+      class $CLASS_NAME($$$):$$$
+        """$DOCSTRING"""
+        $$$
+  kind: class_definition
+  inside:
+    kind: module
+  has:
+    kind: block
+    has:
+      kind: expression_statement
+      has:
+        pattern:
+          selector: string
+          context: |
+            """$DOCSTRING"""
+        kind: string
+        has:
+          kind: string_content
+          not:
+            pattern: |
+              *.+Testcase \d+: $DESCRIPTION
+              .+?
+              >>> $ASSERTION_CODE
+              $ASSERTION_RESULT
+              .*?
+language: python
+message: "Test cases must follow format: Testcase N: description followed by assertions"
+severity: hint

.ast-grep/rules/multicast-rule-exception-handling-pattern.yml

@@ -0,0 +1,13 @@
+#.ast-grep/multicast-rule-exception-handling-pattern.yml
+id: exception-handling-pattern
+rule:
+  pattern:
+    selector: try_statement
+    context: |
+      try:
+        $$$
+      except $ERR_TYPE as $ERR:
+        raise CommandExecutionError(str($ERR))
+language: python
+message: "Ensure proper exception handling for $ERR_TYPE with CommandExecutionError"
+severity: warning

.ast-grep/rules/multicast-rule-has-module-documentation.yml

@@ -0,0 +1,10 @@
+# .ast-grep/multicast-rule-has-module-documentation.yml
+id: check-has-module-documentation
+rule:
+  kind: module
+  not:
+    has:
+      matches: module_docstring
+language: python
+message: "Module docstring must be present and well formatted."
+severity: warning

.ast-grep/rules/multicast-rule-require-docstring-testing.yml

@@ -0,0 +1,45 @@
+# .ast-grep/multicast-rule-require-docstring-testing.yml
+id: require-docstring-testing
+rule:
+  kind: class_definition
+  inside:
+    kind: module
+  has:
+    kind: block
+    has:
+      kind: expression_statement
+      has:
+        pattern: |
+          """$DOCSTRING"""
+        kind: string
+        has:
+          kind: string_content
+          not:
+            pattern: |
+              .*(Minimal Acceptance |Meta-)Testing:.*
+language: python
+message: "Class must include docstring with testing examples"
+files:
+  - tests{/**/,/}test_[a-z0-9_]*.py
+severity: hint
+description: |
+  Ensures that Python classes include proper docstrings with testing examples.
+  This rule helps maintain consistent documentation and testing practices.
+examples:
+  - name: Valid class with testing examples
+    code: |
+      class MyClass:
+          """
+          My class description.
+
+          Testing:
+              >>> obj = MyClass()
+              >>> obj.method()
+              True
+          """
+  - name: Invalid class without testing examples
+    code: |
+      class MyClass:
+          """
+          My class description.
+          """

.ast-grep/rules/multicast-rule-require-docstring.yml

@@ -0,0 +1,25 @@
+# .ast-grep/multicast-rule-require-docstring.yml
+id: check-has-docstring-documentation
+rule:
+  not:
+    has:
+      matches: block_with_docstring
+      kind: block
+  any:
+    - kind: class_definition
+      pattern:
+        selector: class_definition
+        context: |
+          class $NAME($PARAMS):$$$
+            $$$
+            $CLASS_BODY
+    - kind: function_definition
+      pattern:
+        selector: function_definition
+        context: |
+          def $NAME($PARAMS)$RET_TYPE:$$$
+            $$$
+            $FUNC_BODY
+language: python
+message: "$NAME must have documentation, add docstring."
+severity: warning

.ast-grep/rules/multicast-rule-require-doctests-in-docstrings.yml

@@ -0,0 +1,41 @@
+# .ast-grep/multicast-rule-require-doctests-in-docstrings.yml
+---
+id: require-doctests-in-docstrings
+rule:
+  all:
+    - matches: block_docstring
+    - not:
+        has:
+          matches: cep7_docstring_tests
+language: python
+message: "[CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20#2-docstring-style) Documentation must include proper doctests."
+severity: warning
+description: |
+  Ensures that Python docstrings are comprehensive with doctests as advocated by CEP-7.
+  [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20)
+  This rule helps maintain consistent test coverage.
+examples:
+  - name: Valid docstring with sections examples
+    code: |
+      """
+      Test description
+
+      >>> indented test code
+      Test Result
+
+      """
+  - name: Invalid docstring without doctests examples
+    code: |
+      """
+      Possible Test description.
+      No actual doctest
+      """
+  - name: Invalid docstring with invalid doctest examples
+    code: |
+      """
+      Test description
+
+      >>> unindented test code
+      Test Result
+
+      """

.ast-grep/rules/multicast-rule-require-test-cleanup.yml

@@ -0,0 +1,18 @@
+# .ast-grep/multicast-rule-require-test-cleanup.yml
+id: require-test-cleanup
+language: python
+rule:
+  all:
+    - pattern:
+        selector: class_definition
+        context: |
+          class $TEST_CLASS(unittest.TestCase):
+            $BODY
+      inside:
+        kind: module
+    - not:
+        regex: def tearDown\(
+message: "Test classes must include tearDown method for cleanup."
+severity: "warning"
+files:
+  - tests{/**/,/}test_[a-z0-9_]*.py

.ast-grep/rules/multicast-rule-require-test-fixtures.yml

@@ -0,0 +1,18 @@
+# .ast-grep/multicast-rule-require-test-fixtures.yml
+id: require-test-fixtures
+language: python
+rule:
+  all:
+    - pattern:
+        selector: class_definition
+        context: |
+          class $TEST_CLASS(unittest.TestCase):
+            $SETUP
+      inside:
+        kind: module
+    - not:
+        regex: def setUp\(
+message: "Test classes must include setUp method for fixtures"
+severity: warning
+files:
+  - tests{/**/,/}test_[a-z0-9_]*.py

.ast-grep/rules/multicast-rule-server-implementation-pattern-dostep.yml

@@ -0,0 +1,39 @@
+# .ast-grep/rules/multicast-rule-server-implementation-pattern-dostep.yml
+id: multicast-rule-server-implementation-pattern-dostep
+rule:
+  kind: block
+  pattern: |
+    $BLOCK
+  inside:
+    matches: multicast-mtool-subclass
+  not:
+    has:
+      matches: multicast-mtool-subclass-function-dostep
+language: python
+message: "Verify $MCASTNAME implementation follows standard pattern."
+fix: |
+    $BLOCK
+
+    def doStep(self, *args, **kwargs) -> tuple:
+    	"""
+    	Abstracts the __call__ behavior for sub-classing the tool.
+
+    	This method should be overridden by subclasses to implement the specific functionality
+    	of each multicast tool. It accepts variable positional and keyword arguments as needed
+    	by the specific implementation.
+
+    	Args:
+    		*args: Variable length argument list.
+    		**kwargs: Arbitrary keyword arguments.
+
+    	Returns:
+    		tuple: A tuple containing a status indicator and a result.
+
+    	Raises:
+    		NotImplementedError: If the subclass does not implement this method.
+    	"""
+    	raise NotImplementedError("Subclasses must implement this method.")
+
+severity: error
+files:
+  - multicast{/**/,/}*.py