[RELEASE] Version v2.0.9 (Stable)

Author: reactive-firewall

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

@@ -1,4 +1,5 @@
-# .ast-grep/multicast-rule-check-test-documentation.yml
+# .ast-grep/multicast-rule-check-documentation.yml
+---
 id: check-has-documentation
 rule:
   pattern:

.ast-grep/utils/python/structure/docstring_statement.yml

@@ -5,7 +5,7 @@ rule:
   pattern:
     selector: expression_statement
     context: |
-      $$$
+      $EXPRESSION
     has:
       pattern:
         selector: string

.coderabbit.yaml

@@ -10,7 +10,7 @@ reviews:
 
     - Ensure the code follows best practices and coding standards.
     - Check for security vulnerabilities and potential issues.
-    - Ensure the code follows the **DRY, AHA, and SOLID** principles.
+    - Ensure the code follows the **DRY, Avoid-Hasty-Abstractions, and SOLID** design principles.
     - Our "Code Review Checklist Guide" is documented in
       [CEP-4](https://gist.github.com/reactive-firewall/cc041f10aad1d43a5ef15f50a6bbd5a5),
       be sure to always consider
@@ -26,7 +26,7 @@ reviews:
       [Pure BASH Bible](https://github.com/dylanaraps/pure-bash-bible) standards.
     - Consider [CEP-5](https://gist.github.com/reactive-firewall/3d2bd3cf37f87974df6f7bee31a05a89)
       custom locking conventions.
-    - Verify all **BASH** files (e.g. are of MIME-type 'text/x-shellscript') start with an
+    - Verify all **BASH** files (e.g., are of MIME-type 'text/x-shellscript') start with an
       [extensive disclaimer](https://gist.github.com/reactive-firewall/866b42d175ae3ebefcb2a5878b30ea17).
 
     # Documentation Review Instructions
@@ -35,16 +35,16 @@ reviews:
     - Verify that technical documentation includes a "References" section at
       the end of documentation, using the same format as actual RFCs, with
       both "Normative References" and "Informative References". Suggest improvements if unable.
-    - Ensure that that project documentation and comments follow
+    - Ensure that the project documentation and source-code comments follow
       [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20)
 
     # Test Code Review Instructions
     - Ensure that test code is automated, comprehensive, and follows testing best practices.
     - Verify that all critical functionality is covered by tests.
-    - Verify that minimal acceptance tests (e.g. those run by the workflow CI-MATs) are passing and
+    - Verify that minimal acceptance tests (e.g., those run by the workflow CI-MATs) are passing and
       error free, pointing out any failure as below minimal acceptance (i.e. un-acceptable).
     - Ensure that the test coverage meets or exceeds the project's required threshold
-      (e.g., aiming for 100% coverage as per Issue #53).
+      (e.g., aiming for 100% coverage as per GitHub Issue #53).
     - For **test** code, *also* follow
       [CEP-9](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6)
 
@@ -56,7 +56,9 @@ reviews:
       a BSD License, the Unlicence, the Apache v2 License, or that the dependency is optional. Do
       not assume a dependency is optional, confirm if it is or is not optional.
     - For **Python** code, consider [PEP 290](https://peps.python.org/pep-0290/) whenever a python
-      (e.g. has the extension '.py') file is changed.
+      (e.g., has the extension '.py') file is changed.
+    - Our project's "AI Usage Policy" is documented in
+      [.github/AI_USAGE_POLICY.md](https://github.com/reactive-firewall-org/multicast/tree/master/.github/AI_USAGE_POLICY.md).
   request_changes_workflow: true
   high_level_summary: true
   high_level_summary_placeholder: '@coderabbitai summary'
@@ -77,17 +79,27 @@ reviews:
       instructions: >-
         Apply when the PR/MR contains changes to the file `Makefile` or makefile
         code snippets.
-    - label: Documentation
+    - label: documentation
       instructions: >-
         Apply whenever project documentation (namely markdown source-code) is
         updated by the PR/MR. Also apply when PR contains a commit with a commit
         message prefixed with "[DOCUMENTATION] "
+    - label: CI
+      instructions: >-
+        Apply whenever any project CI/CD components (namely GitHub Action source-code) are
+        updated by the PR/MR. Also apply when PR contains a commit with a commit
+        message prefixed with "[CI] "
     - label: Linter
       instructions: >-
         Apply when the purpose of the PR/MR is related to fixing the feedback
         from a linter. Also apply if suggested fixes are used and improve the
-        code's compliance with the PEP-8 standard.
-  path_filters: ['!*.xc*/**', '!node_modules/**', '!dist/**', '!build/**', '!.git/**', '!venv/**', '!__pycache__/**']
+        code's compliance with project conventions or adopted standards.
+    - label: Testing
+      instructions: >-
+        Apply when the purpose of the PR/MR is related to fixing/improving any
+        testing components or test-code. Also apply if suggested fixes are
+        used and improve the project's test-code.
+  path_filters: ['!*.xc*/**', '!node_modules/**', '!dist/**', '!package.json', '!package-lock.json', '!yarn.lock', '!build/**', '!.git/**', '!venv/**', '!__pycache__/**']
   path_instructions:
     - path: README.md
       instructions: >-
@@ -120,7 +132,7 @@ reviews:
            the guidelines set by
            [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20).
         6. Verify Flake8's configuration file is located at ".flake8.ini". Flake8 is run
-           automaticly by the `flake8-cq` GHA used by the `.github/workflows/flake8.yml` workflow.
+           automatically by the `flake8-cq` GHA used by the `.github/workflows/flake8.yml` workflow.
         7. Verify alignment of any new changes, with the code style advocated in
            [CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161),
            pointing out any introduced deviations.
@@ -167,8 +179,8 @@ reviews:
         4. Consider these 'requirements.txt' files the records of truth regarding project
            dependencies.
         5. Consider the 'requirements.txt' file in the base of the git repository
-           (e.g. './requirements.txt') the required python dependencies regarding Multicast project
-           dependencies.
+           (e.g., './requirements.txt') the required python dependencies regarding Multicast
+           project dependencies.
     - path: tests/requirements.txt
       instructions: >-
         1. The multicast project's own dependencies are recorded in './requirements.txt'
@@ -192,7 +204,7 @@ reviews:
         1. Consider the files in the `docs/` directory tree the core/main/in-depth documentation
            of the project. Also consider the 'docs/**.md' files the second place to look for
            project documentation after the 'README.md' file.
-        2. When reviewing the documentation files (e.g. `docs/**.md`), they should additionally
+        2. When reviewing the documentation files (e.g., `docs/**.md`), they should additionally
            be linted with help from the tool `markdownlint`, pointing out any issues.
         3. When reviewing the documentation files in `docs/` directory, they should additionally
            be linted with help from the tool `languagetool`, pointing out any issues.

.deepsource.toml

@@ -33,7 +33,6 @@ dependency_file_paths = [
   "requirements.txt",
   "tests/requirements.txt",
   "docs/requirements.txt",
-  "setup.py"
 ]
 
   [analyzers.meta]

.gitattributes

@@ -1,19 +1,44 @@
-*			text=auto
-*.cfg,*.conf	text working-tree-encoding=UTF-8 diff=config
-*.txt			text working-tree-encoding=UTF-8
-*.py			text working-tree-encoding=UTF-8 diff=python merge=python
-multicast/*.py	text working-tree-encoding=UTF-8 diff=python merge=python
-tests/*.py		text working-tree-encoding=UTF-8 diff=python merge=python
-*.pyc			-text
-*.sh			text working-tree-encoding=UTF-8 diff=shell merge=shell
-*.bash			text working-tree-encoding=UTF-8 diff=shell merge=shell
-*.ini			text
-*.md			text working-tree-encoding=UTF-8 diff=markdown merge=markdown
-*.yml			text
-*.jpg			-text
-*.png			-text
-*.conf			text diff=config
-*.bat			text
-*.rst			text
-tests/check_*	text working-tree-encoding=UTF-8 diff=shell merge=shell
-Makefile		text working-tree-encoding=UTF-8 diff=makefile merge=makefile
+# from -- https://github.com/reactive-firewall/ymmv.git
+
+# Set default behaviour to automatically normalize line endings.
+* text=auto
+
+# Force batch scripts to always use CRLF line endings so that if a repo is accessed
+# in Windows via a file share from Linux, the scripts will work.
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf
+
+# Force bash scripts to always use LF line endings so that if a repo is accessed
+# in Unix via a file share from Windows, the scripts will work.
+*.{ash,[aA][sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+*.{bash,[bB][aA][sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+*.{csh,[cC][sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+*.{dash,[dD][aA][sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+*.{sh,[sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+*.{zsh,[zZ][sS][hH]} text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+
+*.{cfg,[cC][fF][gG]},*.{conf,[cC][oO][nN][fF]} text eol=lf diff=config working-tree-encoding=UTF-8
+*.{toml,[tT][oO][mM][lL]} text eol=lf working-tree-encoding=UTF-8
+*.{ini,[iI][nN][iI]} text eol=lf working-tree-encoding=UTF-8
+*.{yml,[yY][mM][lL]},*.{yaml,[yY][aA][mM][lL]} text eol=lf working-tree-encoding=UTF-8
+*.{txt,[tT][xX][tT]} text eol=lf diff=markdown working-tree-encoding=UTF-8
+*.{rst,[rR][sS][tT]} text eol=lf working-tree-encoding=UTF-8
+*.{md,[mM][dD]},*.{markdown,[mM][aA][rR][kK][dD][oO][wW][nN]} text eol=lf diff=markdown merge=markdown working-tree-encoding=UTF-8
+
+*.py text eol=lf diff=python merge=python working-tree-encoding=UTF-8
+*.pyc export-ignore diff=python -text
+*.pyi export-ignore text eol=lf diff=python merge=python working-tree-encoding=UTF-8
+
+# May diverge in future
+# multicast/*.py text eol=lf diff=python merge=python working-tree-encoding=UTF-8
+# tests/*.py text eol=lf diff=python merge=python working-tree-encoding=UTF-8
+# docs/*.py text eol=lf diff=python merge=python working-tree-encoding=UTF-8
+# tests/check_* text eol=lf diff=bash merge=bash working-tree-encoding=UTF-8
+
+*.jpg -text
+*.png -text
+*.{svg,[sS][vV][gG]} text eol=lf diff=html merge=html working-tree-encoding=UTF-8
+
+# More rules
+.DS_Store export-ignore -text
+Makefile text eol=lf diff=makefile merge=makefile working-tree-encoding=UTF-8

.github/AI_USAGE_POLICY.md

@@ -0,0 +1,184 @@
+# Multicast Project AI Usage Policy
+
+## 1. Purpose and Scope
+
+### 1.1 Rationale :bookmark:
+
+> [!IMPORTANT]
+> This policy governs the use of AI tools, particularly CodeRabbitAI, GH Copilot, and
+> Codecov-ai-reviewer, within the Multicast project's development workflow. It establishes
+> guidelines for responsible AI integration while maintaining the project's security, quality, and
+> integrity.
+
+### 1.2 Definitions :book:
+
+* 1.2.A The following acronyms and abbreviations are used throughout this document:
+  * **AI** - Artificial Intelligence
+  * **CEP** - Convention Enhancement Proposal
+  * **CI** - Continuous Integration
+  * **CWE** - Common Weakness Enumeration (security vulnerability classification system)
+  * **e.g.** - exempli gratia (for example)
+  * **GH** - GitHub (as used in "GH Copilot")
+  * **GHI** - GitHub Issues
+  * **LLM** - Large Language Model
+  * **PR** - Pull Request
+
+## 2. AI Role Definitions
+
+### 2.1 Permitted AI Roles :information_desk_person:
+
+* 2.1.A Assistive Code Review:
+  * AI may provide feedback on code quality, style compliance, and potential issues.
+* 2.1.B Assistive Project-Management Delegation:
+  * AI may provide feedback when requested on GitHub issues (GHIs), as well as open new, or comment
+    on existing, GHI, to track suggested improvements to the project content.
+* 2.1.C Documentation Improvement:
+  * AI may suggest improvements to documentation clarity and completeness.
+* 2.1.D Test Coverage Analysis:
+  * AI may identify areas lacking test coverage.
+* 2.1.E Code Generation Assistance:
+  * AI may suggest code implementations when requested.
+
+> [!CAUTION]
+> However, AI may **NOT** apply changes, nor code suggestions, by themselves, to any protected
+> branch (That is reserved for qualified human contributors).
+
+### 2.2 Prohibited AI Roles :no_entry_sign:
+
+* 2.2.A Sole Developer:
+  * AI (especially LLM-based AI) is not well suited for innovation; No vibe-coding - the direction
+    and development of the project CANNOT meaningfully come from AI.
+* 2.2.B Sole Approver:
+  * AI approval alone is insufficient for merging any PR.
+
+> [!WARNING]
+> Only project admin may sufficiently act as a Sole Approver, and _even_ that is discouraged.
+
+* 2.2.C Security Gatekeeper:
+  * AI cannot be the only mechanism for security validation
+* 2.2.D Merge Commit Author:
+  * AI cannot trigger auto-merge without human verification
+
+## 3. PR Review Process
+
+### 3.1 Required Human Review
+
+* 3.1.A Human Review
+  * All PRs MUST receive at least one human review from an authorized maintainer
+* 3.1.B Verify or Resolve
+  * Human reviews must verify (or conversely reject) the AI's suggestions.
+  * Discussions are encouraged in both cases, as humans and AI alike may later consider relevant
+    project content in future reviews.
+* 3.1.C Very Large PRs
+  * For PRs exceeding 99 changed files, at least two human reviews are recommended.
+
+> [!NOTE]
+> Currently there is only one core maintainer. Hoping to change this.
+
+* 3.1.D Review Conventions and Instructions
+  * The project's code review conventions are currently enumerated in the living document:
+    [CEP-4](https://gist.github.com/reactive-firewall/cc041f10aad1d43a5ef15f50a6bbd5a5)
+    (convention enhancement proposal no.4)
+
+## 3.2 AI Review Requirements
+
+### 3.2 AI Assisted Code Review
+
+* 3.2.A AI Review Purpose
+  * AI reviews are supplementary and do not replace human review
+* 3.2.B AI Troubleshooting
+  * When AI review is triggered but fails (e.g., due to throttling), the PR must be marked as
+    requiring additional attention
+  * AI approval comments should not be used to bypass branch protection rules
+
+### 3.3 Large PR Handling
+
+* 3.3.A Less is More
+  * PRs with more than 99 changed files should be split into smaller PRs when possible.
+  * When splitting is not feasible, PR authors must provide a summary highlighting the most
+    critical changes for human reviewers.
+
+## 4. Security Considerations
+
+### 4.1 Verification and Validation
+
+* 4.1.A Review Line-by-Line
+  * Absolutely, NO "Vibe-coding" is acceptable for this project. ALL AI-suggestions MUST be
+    understood by at least one core maintainer (same as all other reviewed code needs to be).
+
+> [!TIP]
+> > Good code is its own best documentation. As you're about to add a comment, ask yourself,
+> > "How can I improve the code so that this comment isn't needed?" Improve the code and then
+> > document it to make it even clearer.
+> ~ Steve McConnell
+
+  * All AI-suggested code changes must be verified by a human maintainer (see § 3.1.B).
+* 4.1.B Signed Commits
+  * Code signing with different keys for human vs. AI contributions is required.
+* 4.1.C Security Assessments
+  * AI-suggested security fixes must undergo additional human security review.
+
+### 4.2 Branch Protection
+
+* 4.2.A Stable and master branches must maintain protection rules requiring:
+  * Minimum of one human approval
+  * Signed commits
+  * Passing CI checks
+  * Force-pushing to protected branches is prohibited
+
+### 4.3 CWE-655 Mitigation
+
+* 4.3.A dual-approval system
+  * The project implements a dual-approval system to help prevent single points of failure.
+  * AI approvals are tracked separately from human approvals in the review process. Humans
+    must be responsible for the actual merge of pull-requests.
+  * Every user (e.g., AI or human) must have a distinct code-signing identity (see § 4.1.B).
+  * Only human controlled identities may merge branches, or commit to the default branch directly.
+
+> [!NOTE]
+> Historically @dependabot (a simple bot, not a LLM-based AI) had been allowed to merge to the
+> default branch; this policy considers such actions in the past to now be violations of § 4.3.A
+> because the code-signing identity was not controlled by a human. Fortunately, these changes had
+> been limited to improving supply-chain security and required approval from the project admin.
+
+## 5. Implementation and Compliance
+
+### 5.1 Configuration Management
+
+* 5.1.A CoderabbitAI Configuration
+  * The `.coderabbit.yaml` file is the source of truth for CodeRabbitAI configuration.
+* 5.1.B Dependabot Configuration
+  * The `.github/dependabot.yml` file is the source of truth for @dependabot configuration.
+* 5.1.C Configuration Updates
+  * Changes to these configurations require PR approval from at least one core maintainer.
+* 5.1.D Configuration Audits
+  * Regular audits of AI configuration will be conducted to ensure alignment with this policy.
+
+### 5.2 Monitoring and Reporting
+
+* 5.2.A Monitoring
+  * Periodic audits of PR approvals will verify compliance with this policy.
+* 5.2.B Reporting
+  * Security incidents related to AI usage must be reported via project security channels.
+
+### 5.3 Developer Training
+
+* 5.3.A Contributors should understand the limitations of AI tools in the review process.
+* 5.3.B Clear communication about when and how to utilize AI assistance will be provided.
+* 5.3.C New contributors will be directed to this policy as part of onboarding.
+
+## 6. Exceptions
+
+## 6.1 Exceptions to this policy require
+
+* 6.1.A Documented justification.
+* 6.1.B Approval from at least two core maintainers.
+* 6.1.C Time-limited scope with defined expiration.
+* 6.1.D Post-implementation security review.
+
+## 7. Policy Review
+
+### 7.1 This policy will be reviewed
+
+* 7.1.A After any security incident involving AI tools.
+* 7.1.B When significant changes to project AI integration are proposed.