CLASPLint 0.4.4__tar.gz → 0.5.0__tar.gz

{CLASPLint-0.4.4 → CLASPLint-0.5.0}/CLASPLint/__init__.py

@@ -2,8 +2,7 @@
 """
 THIS FILE IS CORE PART OF CLASPLINT BY MATT BELFAST BROWN.
 
-===============================================================================
-
+====================
 MODULE               : CLASPLint.__init__
 
 TYPE                 : Python Script
@@ -11,7 +10,7 @@ TYPE                 : Python Script
 DESCRIPTION          :
     Package entry point and public API surface. Exposes the runner and reporter
     modules as the primary public interface for programmatic use of the CLASP
-    3.2 / PEP 2606 static analysis engine.
+    Stage 3.3 / PEP 2606 static analysis engine.
 
 AUTHOR               : Matt Belfast Brown
 
@@ -23,16 +22,16 @@ MAINTAINER           :
 
 PROJECT CREATE DATE  : 2026-06-17
 
-PROJECT VERSION DATE : 2026-07-06
+PROJECT VERSION DATE : 2026-07-08
 
-PROJECT VERSION      : 0.4.4
+PROJECT VERSION      : 0.5.0
 
 
 FILE CREATE DATE     : 2026-06-17
 
-FILE VERSION DATE    : 2026-07-06
+FILE VERSION DATE    : 2026-07-08
 
-FILE VERSION         : 0.4.1
+FILE VERSION         : 0.5.0
 
 
 STATUS               : Stable
@@ -50,8 +49,7 @@ USAGE                :
     report = CLASPLint.runner.run(["path/to/code/"])
     print(report.summary())
 
-===============================================================================
-
+====================
 THIS PROGRAM IS LICENSED UNDER GPL-3.0-only LICENSE.
 YOU SHOULD HAVE RECEIVED A COPY OF GPL-3.0-only LICENSE.
 
@@ -73,6 +71,6 @@ Sort License:
 """
 
 # Define the package version string.
-__version__ = "0.4.4"
+__version__ = "0.5.0"
 # Expose the runner and reporter modules as the public API.
 __all__ = ["runner", "reporter"]

{CLASPLint-0.4.4 → CLASPLint-0.5.0}/CLASPLint/__main__.py

@@ -2,14 +2,13 @@
 """
 THIS FILE IS CORE PART OF CLASPLINT BY MATT BELFAST BROWN.
 
-===============================================================================
-
+====================
 MODULE               : CLASPLint.__main__
 
 TYPE                 : Python Script
 
 DESCRIPTION          :
-    Command-line entry point for the CLASP 3.2 / PEP 2606 static analysis tool.
+    Command-line entry point for the CLASP Stage 3.3 / PEP 2606 static analysis tool.
 
 AUTHOR               : Matt Belfast Brown
 
@@ -21,16 +20,16 @@ MAINTAINER           :
 
 PROJECT CREATE DATE  : 2026-06-17
 
-PROJECT VERSION DATE : 2026-07-06
+PROJECT VERSION DATE : 2026-07-08
 
-PROJECT VERSION      : 0.4.4
+PROJECT VERSION      : 0.5.0
 
 
 FILE CREATE DATE     : 2026-06-17
 
-FILE VERSION DATE    : 2026-07-06
+FILE VERSION DATE    : 2026-07-08
 
-FILE VERSION         : 0.4.1
+FILE VERSION         : 1.0.0
 
 
 STATUS               : Stable
@@ -49,8 +48,7 @@ USAGE                :
 
     CLASPLint --category variable src/
 
-===============================================================================
-
+====================
 THIS PROGRAM IS LICENSED UNDER GPL-3.0-only LICENSE.
 YOU SHOULD HAVE RECEIVED A COPY OF GPL-3.0-only LICENSE.
 
@@ -70,36 +68,39 @@ Sort License:
     You should have received a copy of the GNU General Public License
     along with CLASPLint.  If not, see <https://www.gnu.org/licenses/>.
 """
-
 import argparse
-import sys
 import os
+import sys
 from typing import Optional, Sequence
 
-from .runner import run
 from . import __version__
+from .runner import run
 
 
 def _init_build_parser_function_() -> argparse.ArgumentParser:
-    """Construct the argument parser for the CLASPLint command-line interface.
+    """
+    Construct the argument parser for the CLASPLint command-line interface.
 
-    Registers positional paths, --version, --no-recursive, --quiet,
-    and --category arguments on a new ArgumentParser instance.
+    Defines the complete CLI surface with five argument groups: positional
+    paths for file and directory scanning, a version flag, a recursive-mode
+    toggle, a quiet-mode switch for summary-only output, and a category
+    filter to restrict violation reporting to a single checker type.
 
     :return: A configured ArgumentParser ready for parse_args.
     :rtype: argparse.ArgumentParser
     """
-    # Create the top-level argument parser with a description.
+    # Build the description string in progressive segments for readability.
+    string_about = f"CLASP Stage 3.3 / PEP 2606 static analysis tool v{__version__}. "
+    # Append the first fragment describing what the tool checks.
+    string_about += "Checks variable, dict key, function, class naming "
+    # Append the final fragment covering remaining convention categories.
+    string_about += "and comment/log conventions."
+    # Instantiate the parser with the assembled description and program name.
     parser_result = argparse.ArgumentParser(
         # Set the program name displayed in help text.
         prog="CLASPLint",
-        # Provide a description of what the tool does.
-        description="CLASP 3.2 / PEP 2606 static analysis tool. "
-                    # Continue the description across multiple lines for readability.
-                    "Checks variable, dict key, function, class naming "
-                    # Complete the tool description with comment and log conventions.
-                    "and comment/log conventions.",
-    # Close the ArgumentParser constructor call.
+        # Supply the pre-built description string to the parser.
+        description=string_about,
     )
     # Accept one or more file or directory paths as positional arguments.
     parser_result.add_argument(
@@ -107,7 +108,6 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
         "paths", nargs="*", default=["."],
         # Provide the help text for the paths' argument.
         help="Python files or directories to check (default: current directory).",
-    # Close the first add_argument call.
     )
     # Provide a --version flag to display the tool version.
     parser_result.add_argument(
@@ -115,7 +115,6 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
         "--version", action="version",
         # Construct the version message from the package version.
         version=f"CLASPLint {__version__}",
-    # Close the second add_argument call.
     )
     # Provide a flag to disable recursive directory traversal.
     parser_result.add_argument(
@@ -123,7 +122,6 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
         "--no-recursive", action="store_true",
         # Provide the help text for the no-recursive flag.
         help="Do not recursively check subdirectories.",
-    # Close the third add_argument call.
     )
     # Provide a quiet mode that suppresses per-violation output.
     parser_result.add_argument(
@@ -131,27 +129,30 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
         "--quiet", "-q", action="store_true",
         # Provide the help text for the quiet flag.
         help="Suppress individual violation output; show only summary.",
-    # Close the fourth add_argument call.
     )
     # Provide a category filter to report only specific violation types.
     parser_result.add_argument(
         # Accept --category or -c with a choice of violation types.
         "--category", "-c",
         # Restrict the value to the five supported violation categories.
-        choices=["variable", "dict_key", "function", "comment", "log", "docstring"],
+        choices=["variable", "dict_key", "function", "comment", "log", "docstring", "tryexcept"],
         # Provide the help text for the category filter.
         help="Only report violations of a specific category.",
-    # Close the fifth add_argument call.
     )
     # Return the fully configured argument parser.
     return parser_result
 
 
 def main(argv: Optional[Sequence[str]] = None) -> int:
-    """Execute the CLASPLint analysis and return an exit code.
+    """
+    Execute the CLASPLint analysis and return an exit code.
+
+    Interprets command-line arguments to discover Python source files,
+    dispatches each file through the full checker pipeline, narrows
+    results by an optional category filter, and prints a formatted
+    summary followed by individual violation details when requested.
 
-    Parses command-line arguments, resolves input paths, dispatches
-    to the runner, applies category filters, and prints the report.
+    The parameters are as follows:
 
     :param argv: Optional list of command-line argument strings.
     :type argv: Optional[Sequence[str]]
@@ -182,16 +183,18 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     bool_recursive = not parsed_options.no_recursive
     # Run all checkers on the resolved paths.
     report_result = run(list_resolved, bool_recursive=bool_recursive)
-    # Apply category filter if one was specified.
+    # Filter violations to only the requested category.
     if parsed_options.category:
-        # Filter violations to only the requested category.
-        report_result.list_violations = [
-            # Iterate over each violation to check against the filter.
-            violation_item for violation_item in report_result.list_violations
-            # Keep only violations matching the requested category filter.
-            if violation_item.string_category == parsed_options.category
-        # Close the filtered list comprehension.
-        ]
+        # Build a filtered list excluding non-matching categories.
+        list_filtered = []
+        # Iterate through each violation for category comparison.
+        for violation_item in report_result.list_violations:
+            # Include violations whose category matches the filter.
+            if violation_item.string_category == parsed_options.category:
+                # Add the matching violation to the filtered list.
+                list_filtered.append(violation_item)
+        # Replace the violations with the filtered subset.
+        report_result.list_violations = list_filtered
     # Print the summary line to stdout.
     print(report_result.summary())
     # Print individual violations unless quiet mode is active.

CLASPLint-0.5.0/CLASPLint/checker_base.py

@@ -0,0 +1,226 @@
+# -*- coding: utf-8 -*-
+"""
+THIS FILE IS CORE PART OF CLASPLINT BY MATT BELFAST BROWN.
+
+====================
+MODULE               : CLASPLint.checker_base
+
+TYPE                 : Python Script
+
+DESCRIPTION          :
+    Base class providing shared infrastructure for CLASP Stage 3.3 AST checkers.
+    Supports source line extraction, violation recording, and previous line
+    retrieval for both log and try-except validation visitors.
+
+AUTHOR               : Matt Belfast Brown
+
+CONTACT              : thedayofthedo@gmail.com
+
+MAINTAINER           :
+    Matt Belfast Brown (thedayofthedo@gmail.com)
+
+
+PROJECT CREATE DATE  : 2026-06-17
+
+PROJECT VERSION DATE : 2026-07-08
+
+PROJECT VERSION      : 0.5.0
+
+
+FILE CREATE DATE     : 2026-07-08
+
+FILE VERSION DATE    : 2026-07-08
+
+FILE VERSION         : 1.0.0
+
+
+STATUS               : Stable
+
+PYTHON               : >=3.8
+
+LICENSE              : GPL-3.0-only
+
+SPDX ID              : GPL-3.0-only
+
+
+USAGE                :
+    from CLASPLint.checker_base import CheckerBase
+
+    class MyChecker(CheckerBase):
+        def visit_SomeNode(self, node):
+            source = self.extract_source_line(node)
+            self.record_violation(node, "Violation message.", "mycategory")
+            previous = self.extract_previous_line(node.lineno)
+
+====================
+THIS PROGRAM IS LICENSED UNDER GPL-3.0-only LICENSE.
+YOU SHOULD HAVE RECEIVED A COPY OF GPL-3.0-only LICENSE.
+
+Copyright (C) 2026 Matt Belfast Brown.
+
+Sort License:
+
+    CLASPLint is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, version 3 of the License.
+
+    CLASPLint is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty
+    of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with CLASPLint.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import ast
+from typing import List
+
+from .reporter import Violation
+
+
+class CheckerBase(ast.NodeVisitor):
+    """
+    CheckerBase CLASS IS CORE PART OF CLASPLINT CHECKER_BASE.
+
+    CLASPLint.checker_base.CheckerBase:
+        Base AST visitor class providing shared infrastructure for CLASP
+        Stage 3.3 checkers. Handles source line extraction, violation
+        recording, and previous line retrieval for derived checker classes.
+
+    ATTRIBUTES                         :
+        file_path (str): Path to the file being checked.
+        source_lines (list): Source lines for contextual messages.
+        list_violations (list): Collected violations from derived checkers.
+
+    PUBLIC METHODS                     :
+        extract_source_line(code_node: ast.AST) -> str:
+            Retrieve the source line text for a given AST node.
+        record_violation(code_node: ast.AST, string_message: str, string_category: str) -> None:
+            Record a violation with the specified category and source context.
+        extract_previous_line(int_lineno: int) -> str:
+            Get the source line immediately before the given line number.
+
+    PRIVATE METHODS                    :
+        None.
+
+    USAGE                             :
+        class MyChecker(CheckerBase):
+            def visit_SomeNode(self, node):
+                source = self.extract_source_line(node)
+                self.record_violation(node, "Message.", "mycategory")
+
+    WARNING                           :
+        Private methods should not be called from outside the class.
+    """
+
+    def __init__(self, file_path: str, source_lines: List[str]):
+        """
+        Initialize the checker base with file path and source lines.
+
+        Stores the file path and source lines for later use during AST traversal
+        and initializes an empty violations list for derived checkers.
+
+        The parameters are as follows:
+
+        :param file_path: Path to the file being checked.
+        :type file_path: str
+        :param source_lines: Source lines of the file for contextual messages.
+        :type source_lines: List[str]
+        """
+        # Store the file path for violation reporting.
+        self.file_path = file_path
+        # Store source lines for contextual violation messages.
+        self.source_lines = source_lines
+        # Collect violations found during AST traversal.
+        self.list_violations: List[Violation] = []
+
+    def extract_source_line(self, code_node: ast.AST) -> str:
+        """
+        Retrieve the source line text for a given AST node.
+
+        Uses the node line number to index into the stored source lines list
+        and returns the full source line text for violation context messages.
+
+        The parameters are as follows:
+
+        :param code_node: The AST node whose source line text is needed.
+        :type code_node: ast.AST
+        :return: The source line corresponding to the node, or an empty string.
+        :rtype: str
+        """
+        # Retrieve the line number from the node attributes.
+        int_lineno = getattr(code_node, 'lineno', 0)
+        # Guard against nodes without line numbers or out-of-range indices.
+        if int_lineno and int_lineno <= len(self.source_lines):
+            # Return the corresponding source line string.
+            return self.source_lines[int_lineno - 1]
+        # Return an empty string for unavailable line numbers.
+        return ""
+
+    def record_violation(
+            # Accept the self-reference for this instance method invocation.
+            self,
+            # Define the AST node where the violation was detected.
+            code_node: ast.AST,
+            # Define the message identifier for the violation.
+            string_message: str,
+            # Define the category identifier for violation classification.
+            string_category: str
+    # Return nothing after recording the violation in the internal list.
+    ) -> None:
+        """
+        Record a violation with the specified category and source context.
+
+        Constructs a Violation instance with file path, node line number,
+        the given category string, the message, and the source line. Appends
+        the violation to the internal list for later collection.
+
+        The parameters are as follows:
+
+        :param code_node: The AST node where the violation was detected.
+        :type code_node: ast.AST
+        :param string_message: The human-readable violation message.
+        :type string_message: str
+        :param string_category: The violation category identifier.
+        :type string_category: str
+        """
+        # Append a new Violation to the internal list with full context.
+        self.list_violations.append(
+            # Create a Violation data class instance.
+            Violation(
+                # Supply the file path for the violation location.
+                file_path=self.file_path,
+                # Extract the line number from the AST node.
+                int_linenumber=getattr(code_node, 'lineno', 0),
+                # Assign the caller-provided violation category identifier.
+                string_category=string_category,
+                # Assign the human-readable violation message.
+                string_message=string_message,
+                # Extract the source line for contextual display.
+                source_line=self.extract_source_line(code_node),
+            )
+        )
+
+    def extract_previous_line(self, int_lineno: int) -> str:
+        """
+        Get the source line immediately before the given line number.
+
+        Used by derived checkers to verify comment presence before statements
+        such as raise or return.
+
+        The parameters are as follows:
+
+        :param int_lineno: The line number to look before (1-based).
+        :type int_lineno: int
+        :return: The previous source line string, or an empty string.
+        :rtype: str
+        """
+        # Calculate the zero-based index of the previous line.
+        int_index = int_lineno - 2
+        # Guard against negative indices when checking line 1.
+        if 0 <= int_index < len(self.source_lines):
+            # Return the source line immediately before the target line.
+            return self.source_lines[int_index]
+        # Return an empty string when no previous line exists.
+        return ""