[PATCH] Work as part of #199 and related tasks.

  - [x] Includes PR #290
  - [x] Includes PR #292
  - [x] Includes PR #293
  - [x] Includes PR #294
  - [x] Includes Security Patch for [CVE-2024-53899](https://osv.dev/vulnerability/GHSA-rqc4-2hc7-8c8v) (- WIP #299 -)

Author: reactive-firewall

.coderabbit.yaml

@@ -227,13 +227,32 @@ reviews:
           - EN_QUOTES
           - CONSECUTIVE_SPACES
         enabled_rules:
-          - STYLE
+          # Grammar rules
+          - BEEN_PART_AGREEMENT
+          - COMMA_COMPOUND_SENTENCE
+          # Compound word rules
+          - COMPOUNDING
+          - EN_COMPOUNDS
+          - EN_COMPOUND_ADJECTIVE_INTERNAL
+          # Word usage and consistency
           - EN_CONTRACTION_SPELLING
           - EN_WORD_COHERENCY
+          - ENGLISH_WORD_REPEAT_RULE
+          - EN_A_VS_AN
+          # Style and semantics
           - IT_IS_OBVIOUS
-          - TWELFTH_OF_NEVER
+          - NONSTANDARD_PHRASES
           - OXFORD_SPELLING
           - PASSIVE_VOICE
+          - REDUNDANCY
+          - SEMANTICS
+          - STYLE
+          - TYPOGRAPHY
+          # Time and date conventions
+          - TWELFTH_OF_NEVER
+          - WIKIPEDIA_12_AM
+          - WIKIPEDIA_12_PM
+          - WIKIPEDIA_CONTRACTIONS
     shellcheck:
       enabled: true
     ruff:

Makefile

@@ -77,6 +77,9 @@ ifeq "$(PYTHON)" ""
 		#COV_CORE_SOURCE = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))/
 		COV_CORE_CONFIG = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))/.coveragerc
 		COV_CORE_DATAFILE = .coverage
+		COVERAGE_ARGS := --cov=. --cov-append --cov-report=xml
+	else
+		COVERAGE_ARGS :=
 	endif
 	ifeq "$(COVERAGE)" ""
 		COVERAGE!=$(COMMAND) coverage
@@ -87,9 +90,16 @@ else
 		#COV_CORE_SOURCE = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))/
 		COV_CORE_CONFIG = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))/.coveragerc
 		COV_CORE_DATAFILE = .coverage
+		COVERAGE_ARGS := --cov=. --cov-append --cov-report=xml
+	else
+		COVERAGE_ARGS :=
 	endif
 endif
 
+ifndef PYTEST
+	PYTEST=$(PYTHON) -m pytest --cache-clear --junitxml=test-reports/junit.xml -v --rootdir=.
+endif
+
 ifndef PIP_COMMON_FLAGS
 	# Define common pip install flags
 	PIP_COMMON_FLAGS := --use-pep517 --exists-action s --upgrade --upgrade-strategy eager
@@ -198,11 +208,6 @@ purge: legacy-purge
 	$(QUIET)$(RMDIR) ./test-reports/ 2>$(ERROR_LOG_PATH) || :
 	$(QUIET)$(ECHO) "$@: Done."
 
-just-test: cleanup MANIFEST.in
-	$(QUIET)$(COVERAGE) run -p --source=multicast -m unittest discover --verbose --buffer -s ./tests -t $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) || $(PYTHON) -m unittest discover --verbose --buffer -s ./tests -t ./ || DO_FAIL="exit 2" ;
-	$(QUITE)$(WAIT) ;
-	$(QUIET)$(DO_FAIL) ;
-
 test: just-test
 	$(QUIET)$(DO_FAIL) ;
 	$(QUIET)$(COVERAGE) combine 2>$(ERROR_LOG_PATH) || : ;
@@ -227,8 +232,63 @@ docs-reqs: ./docs/ ./docs/requirements.txt init
 	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -r docs/requirements.txt  2>$(ERROR_LOG_PATH) || : ;
 	$(QUIET)$(WAIT) ;
 
+# === Test Group Targets ===
+just-test: cleanup MANIFEST.in ## Run all minimum acceptance tests
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) --doctest-glob=multicast/*.py,tests/*.py --doctest-modules $(COVERAGE_ARGS) || DO_FAIL="exit 2" ; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m unittest discover --verbose --buffer -s ./tests -t $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) || $(PYTHON) -m unittest discover --verbose --buffer -s ./tests -t ./ || DO_FAIL="exit 2" ; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
+test-mat-%: MANIFEST.in ## Run specific MAT category (basic|doctests|say|hear|usage|build|bootstrap)
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) tests/ --verbose $(COVERAGE_ARGS) --junitxml=test-reports/junit.xml -v --rootdir=. -m "mat and $*"; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group mat --category $*; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
+test-extra: ## Run all extra tests
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) tests/ --verbose $(COVERAGE_ARGS) -m "extra"; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group extra; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
+test-extra-%: ## Run specific extra test category
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) tests/ --verbose $(COVERAGE_ARGS) -m "extra and $*"; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group extra --category $*; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
+test-fuzzing: ## Run all fuzzing tests
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) tests/ --verbose $(COVERAGE_ARGS) -m "fuzzing"; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group fuzzing; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
+test-perf: ## Run all performance tests
+	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
+		$(PYTEST) tests/ --verbose $(COVERAGE_ARGS) -m "performance"; \
+	else \
+		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group performance; \
+	fi
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
+
 test-pytest: cleanup MANIFEST.in must_have_pytest test-reports
-	$(QUIET)$(PYTHON) -m pytest --cache-clear --doctest-glob=multicast/*.py,tests/*.py --doctest-modules --cov=. --cov-append --cov-report=xml --junitxml=test-reports/junit.xml -v --rootdir=. || DO_FAIL="exit 2" ;
+	$(QUIET)$(PYTEST) --doctest-glob=multicast/*.py,tests/*.py --doctest-modules $(COVERAGE_ARGS) || DO_FAIL="exit 2" ;
 	$(QUITE)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;
 	$(QUIET)$(ECHO) "$@: Done."

docs/utils.py

@@ -19,10 +19,21 @@
 import re
 
 
+# Git reference validation pattern
+# Enforces:
+# - Must start with alphanumeric character
+# - Can contain alphanumeric characters, underscore, hyphen, forward slash, and dot
+GIT_REF_PATTERN = r'^[a-zA-Z0-9][a-zA-Z0-9_\-./]*$'
+
+
 def _validate_git_ref(ref: str) -> str:
 	"""
 	Validate if the provided string is a valid Git reference.
 
+	Git reference naming rules:
+		- Must start with an alphanumeric character
+		- Can contain alphanumeric characters, underscore, hyphen, forward slash, and dot
+		- Cannot contain consecutive dots (..)
 	Args:
 		ref (str) -- The Git reference to validate.
 
@@ -57,8 +68,15 @@ def _validate_git_ref(ref: str) -> str:
 			Traceback (most recent call last):
 			...
 			ValueError: Invalid Git reference:...
+
+		Testcase 5: Invalid reference with disallowed dot-dot characters.
+
+			>>> _validate_git_ref('invalid..ref')  #doctest: +IGNORE_EXCEPTION_DETAIL +ELLIPSIS
+			Traceback (most recent call last):
+			...
+			ValueError: Invalid Git reference: invalid..ref
 	"""
-	if not re.match(r'^[a-zA-Z0-9_\-./]+$', ref):
+	if not re.match(GIT_REF_PATTERN, ref) or ".." in ref:
 		raise ValueError(f"Invalid Git reference: {ref}")
 	return ref
 

multicast/hear.py

@@ -427,11 +427,14 @@ def handle(self):
 
 			Testcase 3: `handle` requires valid requests or ignores input.
 
-			>>> handler.request = ("The Test", multicast.genSocket())
+			>>> tst_fixture_sock = multicast.genSocket()
+			>>> handler.request = ("The Test", tst_fixture_sock)
 			>>> handler.client_address = ("224.0.1.2", 51234)
 			>>> handler.handle() is None
 			True
 			>>>
+			>>> multicast.endSocket(tst_fixture_sock)
+			>>>
 		"""
 		(data, sock) = self.request
 		if data is None or not sock:

multicast/recv.py

@@ -233,6 +233,12 @@ def joinstep(groups, port, iface=None, bind_group=None, isock=None):
 		>>>
 
 	Testcase 1: Stability testing.
+		A: Verify the multicast.recv module is properly initialized.
+		B: Verify the joinstep function exists and has the expected type.
+		C: Test socket creation with no groups (default behavior).
+		D: Test socket creation with a specified multicast group.
+		E: Test socket creation with a multicast group and binding to that group.
+		F: Test socket creation using an existing socket handle.
 
 		>>> import multicast
 		>>>
@@ -243,20 +249,36 @@ def joinstep(groups, port, iface=None, bind_group=None, isock=None):
 		False
 		>>> type(multicast.recv.joinstep)
 		<class 'function'>
-		>>> multicast.recv.joinstep(None, 59991) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
-		<socket.socket...>
+		>>> tst_sk = multicast.recv.joinstep(None, 59991)
+		>>> tst_sk #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		<socket.socket...laddr=...>
+		>>> multicast.endSocket(tst_sk)
+		>>> tst_sk #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		<socket.socket [closed]...>
 		>>> tst_fxtr = multicast._MCAST_DEFAULT_GROUP
-		>>> multicast.recv.joinstep([tst_fxtr], 59991) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		>>> tst_sk_2 = multicast.recv.joinstep([tst_fxtr], 59991)
+		>>> tst_sk_2 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
 		<socket.socket...>
-		>>> multicast.recv.joinstep(
+		>>> multicast.endSocket(tst_sk_2)
+		>>> tst_sk_2 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		<socket.socket [closed]...>
+		>>> tst_sk_3 = multicast.recv.joinstep(
 		... 		[tst_fxtr], 59991, None, tst_fxtr
 		... ) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		>>> tst_sk_3 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
 		<socket.socket...>
+		>>> multicast.endSocket(tst_sk_3)
+		>>> tst_sk_3 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		<socket.socket [closed]...>
 		>>> sk_fxtr = multicast.genSocket()
-		>>> multicast.recv.joinstep(
+		>>> tst_sk_4 = multicast.recv.joinstep(
 		... 		[tst_fxtr], 59991, None, tst_fxtr, sk_fxtr
-		... ) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		... )
+		>>> tst_sk_4 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
 		<socket.socket...>
+		>>> multicast.endSocket(tst_sk_4)
+		>>> tst_sk_4 #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
+		<socket.socket [closed]...>
 		>>> sk_fxtr.close()
 		>>>
 

pyproject.toml

@@ -20,11 +20,32 @@ extend-ignore = ["E117", "D203", "D208", "D212"]
 max-line-length = 100
 docstring-convention = "google"
 
-[pytest.enabler.flake8]
+[tool.pytest]
+testpaths = "tests"
+python_files = "test_*.py"
+
+[tool.pytest.markers]
+mat = "minimum acceptance tests"
+mat_basic = "basic component tests"
+mat_doctests = "documentation tests"
+mat_say = "send.py focused tests"
+mat_hear = "recv.py and hear.py focused tests"
+mat_usage = "__main__.py and API tests"
+mat_build = "build and packaging tests"
+mat_bootstrap = "init/exceptions/env/skt tests"
+extra = "additional important tests"
+extra_coverage = "coverage-focused tests"
+extra_linting = "linting tests"
+extra_security = "security tests"
+fuzzing = "fuzzing tests"
+fuzzing_basic = "smaller sub-set of fuzzing tests"
+performance = "performance and scalability tests"
+
+[tool.pytest.enabler.flake8]
 addopts = "--flake8"
 
-[pytest.enabler.doctest]
+[tool.pytest.enabler.doctest]
 addopts = "--doctest-glob=**/*.py --doctest-modules"
 
-[pytest.enabler.cov]
+[tool.pytest.enabler.cov]
 addopts = "--cov=. --cov-append --cov-report=xml --junitxml=test-reports/junit.xml"

pytest.ini

@@ -0,0 +1,20 @@
+[pytest]
+addopts = --doctest-modules --cov=multicast --cov-append --cov-report=xml
+testpaths = tests
+python_files = test_*.py
+markers =
+    mat: minimum acceptance tests
+    mat_basic: basic component tests
+    mat_doctests: documentation tests
+    mat_say: send.py focused tests
+    mat_hear: recv.py and hear.py focused tests
+    mat_usage: __main__.py and API tests
+    mat_build: build and packaging tests
+    mat_bootstrap: init/exceptions/env/skt tests
+    extra: additional important tests
+    extra_coverage: coverage-focused tests
+    extra_linting: linting tests
+    extra_security: security tests
+    fuzzing: fuzzing tests
+    fuzzing_basic: smaller sub-set of fuzzing tests
+    performance: performance and scalability tests

requirements.txt

@@ -27,7 +27,7 @@
 # setuptools - MIT license
 setuptools>=75.0
 # virtualenv - MIT license
-#virtualenv>=15.0.1
+#virtualenv>=20.26.6
 # pip - MIT license
 pip>=24.3.1
 # build - MIT license

setup.cfg

@@ -81,7 +81,7 @@ testing =
   pytest-enabler >= 1.0.1
   # local
   flake8 >= 5.0
-  virtualenv >= 20.26.5
+  virtualenv >= 20.26.6
   wheel >= 0.44.0
   pip >= 24.3.1
   pytest-cov >= 4.0.0; \