CLASPLint 0.4.0__tar.gz → 0.4.2__tar.gz

{CLASPLint-0.4.0 → CLASPLint-0.4.2}/CLASPLint/__init__.py

@@ -23,16 +23,16 @@ MAINTAINER           :
 
 PROJECT CREATE DATE  : 2026-06-17
 
-PROJECT VERSION DATE : 2026-07-05
+PROJECT VERSION DATE : 2026-07-06
 
-PROJECT VERSION      : 0.4.0
+PROJECT VERSION      : 0.4.2
 
 
 FILE CREATE DATE     : 2026-06-17
 
-FILE VERSION DATE    : 2026-07-05
+FILE VERSION DATE    : 2026-07-06
 
-FILE VERSION         : 0.4.0
+FILE VERSION         : 0.4.1
 
 
 STATUS               : Stable
@@ -73,6 +73,6 @@ Sort License:
 """
 
 # Define the package version string.
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 # Expose the runner and reporter modules as the public API.
 __all__ = ["runner", "reporter"]

{CLASPLint-0.4.0 → CLASPLint-0.4.2}/CLASPLint/__main__.py

@@ -21,16 +21,16 @@ MAINTAINER           :
 
 PROJECT CREATE DATE  : 2026-06-17
 
-PROJECT VERSION DATE : 2026-07-05
+PROJECT VERSION DATE : 2026-07-06
 
-PROJECT VERSION      : 0.4.0
+PROJECT VERSION      : 0.4.2
 
 
 FILE CREATE DATE     : 2026-06-17
 
-FILE VERSION DATE    : 2026-07-05
+FILE VERSION DATE    : 2026-07-06
 
-FILE VERSION         : 0.4.0
+FILE VERSION         : 0.4.1
 
 
 STATUS               : Stable
@@ -81,7 +81,14 @@ from . import __version__
 
 
 def _init_build_parser_function_() -> argparse.ArgumentParser:
-    """Construct the argument parser for the CLASPLint CLI."""
+    """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.
+
+    :return: A configured ArgumentParser ready for parse_args.
+    :rtype: argparse.ArgumentParser
+    """
     # Create the top-level argument parser with a description.
     parser_result = argparse.ArgumentParser(
         # Set the program name displayed in help text.
@@ -141,15 +148,24 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
 
 
 def main(argv: Optional[Sequence[str]] = None) -> int:
-    """Execute the CLASPLint analysis and return an exit code (0 = clean, 1 = violations)."""
+    """Execute the CLASPLint analysis and return an exit code.
+
+    Parses command-line arguments, resolves input paths, dispatches
+    to the runner, applies category filters, and prints the report.
+
+    :param argv: Optional list of command-line argument strings.
+    :type argv: Optional[Sequence[str]]
+    :return: Exit code 0 when no violations are found, 1 otherwise.
+    :rtype: int
+    """
     # Build and parse command-line arguments.
-    parser = _init_build_parser_function_()
+    command_parser = _init_build_parser_function_()
     # Parse the provided arguments or default to sys.argv.
-    args = parser.parse_args(argv)
+    parsed_options = command_parser.parse_args(argv)
     # Resolve all input paths to absolute paths for consistent processing.
     list_resolved = []
     # Iterate over each provided path argument.
-    for string_path in args.paths:
+    for string_path in parsed_options.paths:
         # Convert the path to an absolute path.
         string_absolute = os.path.abspath(string_path)
         # Only include paths that exist on the filesystem.
@@ -163,23 +179,23 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         # Return exit code 2 for usage errors.
         return 2
     # Determine whether to recurse into subdirectories.
-    bool_recursive = not args.no_recursive
+    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.
-    if args.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.
-            v for v in report_result.list_violations
+            violation_item for violation_item in report_result.list_violations
             # Keep only violations matching the requested category filter.
-            if v.string_category == args.category
+            if violation_item.string_category == parsed_options.category
         # Close the filtered list comprehension.
         ]
     # Print the summary line to stdout.
     print(report_result.summary())
     # Print individual violations unless quiet mode is active.
-    if report_result.list_violations and not args.quiet:
+    if report_result.list_violations and not parsed_options.quiet:
         # Add a blank line before the violation listing.
         print()
         # Print the formatted violation details.

{CLASPLint-0.4.0 → CLASPLint-0.4.2}/CLASPLint/comment_checker.py

@@ -21,16 +21,16 @@ MAINTAINER           :
 
 PROJECT CREATE DATE  : 2026-06-17
 
-PROJECT VERSION DATE : 2026-07-05
+PROJECT VERSION DATE : 2026-07-06
 
-PROJECT VERSION      : 0.4.0
+PROJECT VERSION      : 0.4.2
 
 
 FILE CREATE DATE     : 2026-06-17
 
-FILE VERSION DATE    : 2026-07-05
+FILE VERSION DATE    : 2026-07-06
 
-FILE VERSION         : 0.4.0
+FILE VERSION         : 0.4.1
 
 
 STATUS               : Stable
@@ -75,38 +75,26 @@ from typing import List, Set, cast
 
 from .reporter import Violation
 
-# Keywords that start lines are exempt from comments since they are structural declarations.
-comment_exempt = frozenset({
-    # Include the standard import statement keyword.
-    "import",
-    # Include the from-import statement keyword.
-    "from",
-    # Include the class definition keyword.
-    "class",
-    # Include the function definition keyword.
-    "def",
-# Close the exempt keywords frozenset literal.
-})
-
-# Define weak comment starter patterns that merely restate code rather than explain intent.
-weak_patterns = (
-    # Detect "Check if ..." and "Check whether ..." patterns that restate conditions.
-    r'^Check\s+if\b',
-    # Detect "Check whether ..." variant.
-    r'^Check\s+whether\b',
-# Close the weak comment pattern tuple.
-)
+from .configuration import comment_exempt, weak_patterns
 
 # Compile the encoding declaration regex for detecting coding declarations.
 regex_encoding = re.compile(
     # Match the standard PEP 263 encoding declaration format.
     r'^[ \t\f]*#.*?coding[:=][ \t]*([-_.a-zA-Z0-9]+)',
-# Close the regex compilation call.
 )
 
 
-def _tokenize_source(string_source: str) -> List[tokenize.TokenInfo]:
-    """Tokenize source code and return the list of tokens."""
+def _init_tokenize_code_function_(string_source: str) -> List[tokenize.TokenInfo]:
+    """Tokenize a source string into a list of token information objects.
+
+    Wraps tokenize.generate_tokens with a StringIO buffer to convert
+    the source string into an iterable token stream for inspection.
+
+    :param string_source: Complete Python source code as a single string.
+    :type string_source: str
+    :return: A flat list of token information tuples from the tokenizer.
+    :rtype: List[tokenize.TokenInfo]
+    """
     # Generate tokens from the source string using a StringIO buffer.
     return list(tokenize.generate_tokens(io.StringIO(string_source).readline))
 
@@ -198,7 +186,7 @@ class CommentChecker:
         # Attempt to tokenize the source; skip if tokenization fails.
         try:
             # Tokenize the full source code into a list of token objects.
-            list_tokens = _tokenize_source(self.string_source)
+            list_tokens = _init_tokenize_code_function_(self.string_source)
         # Return early if the source cannot be tokenized.
         except tokenize.TokenError:
             # Exit the method early when tokenization fails.
@@ -371,7 +359,7 @@ class CommentChecker:
         # Attempt to tokenize the source; skip if tokenization fails.
         try:
             # Tokenize the full source code for comment format checking.
-            list_tokens = _tokenize_source(self.string_source)
+            list_tokens = _init_tokenize_code_function_(self.string_source)
         # Return early if the source cannot be tokenized.
         except tokenize.TokenError:
             # Exit the method early when tokenization fails.
@@ -526,7 +514,7 @@ class CommentChecker:
         # Attempt to tokenize the source; skip if tokenization fails.
         try:
             # Tokenize the full source code for symbol-line comment detection.
-            list_tokens = _tokenize_source(self.string_source)
+            list_tokens = _init_tokenize_code_function_(self.string_source)
         # Return early if the source cannot be tokenized.
         except tokenize.TokenError:
             # Exit the method early when tokenization fails.
@@ -699,7 +687,7 @@ class CommentChecker:
         # Attempt to tokenize the source; skip if tokenization fails.
         try:
             # Tokenize the full source code for weak comment detection.
-            list_tokens = _tokenize_source(self.string_source)
+            list_tokens = _init_tokenize_code_function_(self.string_source)
         # Return early if the source cannot be tokenized.
         except tokenize.TokenError:
             # Exit the method early when tokenization fails.
@@ -759,7 +747,7 @@ class CommentChecker:
         # Attempt to tokenize the source; skip if tokenization fails.
         try:
             # Tokenize the full source code for comment language detection.
-            list_tokens = _tokenize_source(self.string_source)
+            list_tokens = _init_tokenize_code_function_(self.string_source)
         # Return early if the source cannot be tokenized.
         except tokenize.TokenError:
             # Exit the method early when tokenization fails.

CLASPLint-0.4.2/CLASPLint/configuration.py

@@ -0,0 +1,306 @@
+# -*- coding: utf-8 -*-
+"""
+THIS FILE IS CORE PART OF CLASPLINT BY MATT BELFAST BROWN.
+
+===============================================================================
+
+MODULE               : CLASPLint.configuration
+
+TYPE                 : Python Script
+
+DESCRIPTION          :
+    Lightweight YAML configuration loader for CLASP 3.2 word lists.
+    Parses configuration.yaml without external dependencies and exposes
+    all exemption sets, forbidden terms, and whitelist collections
+    as module-level constants for use by checker modules.
+
+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-06
+
+PROJECT VERSION      : 0.4.2
+
+
+FILE CREATE DATE     : 2026-07-06
+
+FILE VERSION DATE    : 2026-07-06
+
+FILE VERSION         : 0.1.0
+
+
+STATUS               : Stable
+
+PYTHON               : >=3.8
+
+LICENSE              : GPL-3.0-only
+
+SPDX ID              : GPL-3.0-only
+
+
+USAGE                :
+    from CLASPLint.config import common_words, forbidden_terms
+
+===============================================================================
+
+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 os
+from typing import Any, Dict, List, Union
+
+
+# Define the return type alias for the YAML value parser.
+type_yaml = Union[str, List[str], Dict[str, str], bool, None]
+
+
+def _init_parse_value_function_(string_text: str) -> type_yaml:
+    """Parse a YAML scalar or inline collection value from stripped text.
+
+    Handles flow sequences, flow mappings, quoted scalars, null literals,
+    boolean literals, and bare unquoted scalars.
+
+    :param string_text: The stripped string value from a YAML list item or mapping value.
+    :type string_text: str
+    :return: A parsed Python object representing the YAML value.
+    :rtype: Union[str, List[str], Dict[str, str], bool, None]
+    """
+    # Detect and parse an inline flow-sequence value like [a, b, c].
+    if string_text.startswith("[") and string_text.endswith("]"):
+        # Strip the outer brackets to extract the inner comma-separated content.
+        string_inner = string_text[1:-1].strip()
+        # Build a list by splitting on commas and stripping quotes from each element.
+        list_elements = []
+        # Iterate over each comma-separated token within the brackets.
+        for string_element in string_inner.split(","):
+            # Strip whitespace from the current element token.
+            string_token = string_element.strip()
+            # Include non-empty tokens after quote removal.
+            if string_token:
+                # Strip single and double quotes from the token value.
+                list_elements.append(string_token.strip("'\""))
+        # Return the parsed list of cleaned element strings.
+        return list_elements
+    # Detect and parse an inline flow-mapping value like {key: val}.
+    if string_text.startswith("{") and string_text.endswith("}"):
+        # Strip the outer braces to extract the inner key-value pairs.
+        string_inner = string_text[1:-1].strip()
+        # Initialize an empty dictionary to collect the parsed key-value entries.
+        dict_output: Dict[str, str] = {}
+        # Split the mapping content on commas for each key-value pair.
+        for string_pair in string_inner.split(","):
+            # Require a colon separator to identify a valid key-value pair.
+            if ":" in string_pair:
+                # Split the pair on the first colon to separate key and value.
+                string_key, string_value = string_pair.split(":", 1)
+                # Strip whitespace and quotes from the key before storage.
+                string_cleankey = string_key.strip().strip("'\"")
+                # Strip whitespace and quotes from the value after the colon.
+                clean_value = string_value.strip().strip("'\"")
+                # Store the cleaned key-value entry in the output dictionary.
+                dict_output[string_cleankey] = clean_value
+        # Return the fully parsed inline mapping dictionary.
+        return dict_output
+    # Detect a single-quoted or double-quoted scalar value, verifying the wrapping pair match.
+    if (string_text.startswith("'") and string_text.endswith("'")) or (
+        # Also verify the double-quote pair variant for quoted scalar detection.
+            string_text.startswith('"') and string_text.endswith('"')
+    ):
+        # Strip the surrounding quote characters and return the inner text.
+        return string_text[1:-1]
+    # Detect the YAML null literal keyword or tilde shorthand.
+    if string_text.lower() == "null" or string_text == "~":
+        # Return Python None to represent the absence of a value.
+        return None
+    # Detect the YAML boolean true literal keyword.
+    if string_text.lower() == "true":
+        # Return the Python boolean True constant.
+        return True
+    # Detect the YAML boolean false literal keyword.
+    if string_text.lower() == "false":
+        # Return the Python boolean False constant.
+        return False
+    # Return the bare unquoted scalar text as an ordinary string.
+    return string_text
+
+
+def _init_load_yaml_function_(file_path: str) -> Dict[str, Any]:
+    """Load a simplified YAML file and return a dictionary of parsed top-level keys.
+
+    Supports comments, block sequences, block mappings, and inline scalars.
+    Does not support anchors, aliases, tags, or multi-line strings.
+
+    :param file_path: Absolute or relative path to the YAML configuration file.
+    :type file_path: str
+    :return: Dictionary mapping top-level section keys to their parsed data values.
+    :rtype: Dict[str, Any]
+    """
+    # Open the YAML file with UTF-8 encoding for reading.
+    with open(file_path, "r", encoding="utf-8") as file_handle:
+        # Read every line from the configuration file into memory.
+        list_lines = file_handle.readlines()
+    # Initialize the top-level dictionary to accumulate parsed section data.
+    dict_result: Dict[str, Any] = {}
+    # Track the name of the currently active top-level YAML section key.
+    current_key: str = ""
+    # Track the indentation depth of the current top-level section header.
+    current_indent: int = 0
+    # Buffer accumulated child entries for the currently active section.
+    list_buffer = []
+    # Track whether the current section contains a mapping or a sequence.
+    is_mapping: bool = False
+    # Iterate over each physical line in the file to parse the structure.
+    for string_line in list_lines:
+        # Strip the platform-specific trailing newline to obtain clean content.
+        line_raw = string_line.rstrip("\n").rstrip("\r")
+        # Skip lines that are empty or consist entirely of a YAML comment.
+        if not line_raw or line_raw.lstrip().startswith("#"):
+            # Move to the next line without processing this one.
+            continue
+        # Compute the leading whitespace indent for hierarchy level detection.
+        trim_line = line_raw.lstrip()
+        # Derive the indentation depth from the difference between raw and stripped length.
+        int_indent = len(line_raw) - len(trim_line)
+        # Detect a top-level key declaration ending with a colon at zero indent.
+        if int_indent == 0 and trim_line.endswith(":") and not trim_line.startswith("-"):
+            # Flush any previously buffered section data into the result dictionary.
+            if current_key and list_buffer:
+                # Distinguish between mapping and sequence buffer formats.
+                if is_mapping:
+                    # Construct a dictionary from the accumulated key-value pair strings.
+                    work_map: Dict[str, str] = {}
+                    # Process each buffered entry that should contain a colon separator.
+                    for each_one in list_buffer:
+                        # Verify the entry contains a key-value separator.
+                        if ":" in each_one:
+                            # Split on the first colon to separate the key from the value.
+                            text_key, text_value = each_one.split(":", 1)
+                            # Store the cleaned key-value mapping entry.
+                            work_map[text_key.strip()] = text_value.strip()
+                    # Assign the constructed mapping dictionary to the result.
+                    dict_result[current_key] = work_map
+                # Branch to handle sequence mode when the buffer contains list items.
+                else:
+                    # Assign the accumulated sequence items as an immutable frozenset.
+                    dict_result[current_key] = frozenset(list_buffer)
+            # Clear the buffer to prepare for the newly encountered section.
+            list_buffer = []
+            # Extract the new section key by removing the trailing colon.
+            current_key = trim_line[:-1].strip()
+            # Record the base indentation level for this section header.
+            current_indent = int_indent
+            # Default to treating the section as a sequence until a mapping entry appears.
+            is_mapping = False
+            # Skip further processing of this header line.
+            continue
+        # Detect a first-level list item introduced by a dash and space at section depth.
+        if int_indent > current_indent and trim_line.startswith("- "):
+            # Extract the raw value following the dash-space prefix.
+            value_text = trim_line[2:].strip()
+            # Determine whether the value contains a colon indicating an inline mapping entry.
+            if ":" in value_text and not value_text.startswith(("{", "[", "'", '"')):
+                # Switch the section mode to mapping since key-value syntax was detected.
+                is_mapping = True
+                # Append the raw key-value string to the buffer for later mapping construction.
+                list_buffer.append(value_text)
+            # Branch to handle a plain scalar value when the item is not a mapping entry.
+            else:
+                # Interpret the value as a plain scalar and parse it through the value parser.
+                out_data = _init_parse_value_function_(value_text)
+                # Buffer the parsed value, falling back to the raw string for unknown types.
+                list_buffer.append(out_data if out_data is not None else value_text)
+            # Skip further processing of this list item line.
+            continue
+        # Detect continuation lines at a deeper indent that do not carry a list dash.
+        if int_indent > current_indent and current_key:
+            # Strip surrounding whitespace from the continuation line content.
+            clean_text = trim_line.strip()
+            # Exclude continuation lines that are purely YAML comment markers.
+            if clean_text and not clean_text.startswith("#"):
+                # Determine whether this continuation line contains mapping-style colon syntax.
+                if ":" in clean_text and not clean_text.startswith(("{", "[", "'", '"')):
+                    # Switch the section mode to mapping for colon-delimited entries.
+                    is_mapping = True
+                # Append the continuation line content to the active section buffer.
+                list_buffer.append(clean_text)
+    # Flush the final buffered section into the result dictionary after the loop ends.
+    if current_key and list_buffer:
+        # Distinguish the final buffer type between mapping and sequence data.
+        if is_mapping:
+            # Build a dictionary from the remaining key-value pair strings.
+            work_map = {}
+            # Process each leftover buffered entry for colon-separated pairs.
+            for each_one in list_buffer:
+                # Confirm the entry still contains a valid key-value separator.
+                if ":" in each_one:
+                    # Split on the first colon to extract key and value portions.
+                    text_key, text_value = each_one.split(":", 1)
+                    # Store the cleaned final mapping entry.
+                    work_map[text_key.strip()] = text_value.strip()
+            # Assign the final constructed mapping to the result dictionary.
+            dict_result[current_key] = work_map
+        # Branch to collect the sequence items when the buffer is not a mapping.
+        else:
+            # Assign the final accumulated sequence as an immutable frozenset.
+            dict_result[current_key] = frozenset(list_buffer)
+    # Return the fully populated configuration data dictionary.
+    return dict_result
+
+
+# Resolve the absolute path to the configuration.yaml file next to this module.
+yaml_path = os.path.join(str(os.path.dirname(__file__)), "configuration.yaml")
+# Parse the YAML configuration file into a top-level dictionary of sets and mappings.
+yaml_data = _init_load_yaml_function_(yaml_path)
+
+# Expose each YAML section as a typed module-level constant for direct import by checker modules.
+# Extract the set of permitted lowercase acronyms from the configuration data.
+lower_acronyms: frozenset = yaml_data.get("lower_acronyms", frozenset())
+# Extract the set of permitted uppercase acronyms from the configuration data.
+upper_acronyms: frozenset = yaml_data.get("upper_acronyms", frozenset())
+# Extract the mapping of forbidden abbreviations to their full word equivalents.
+forbidden_terms: dict = yaml_data.get("forbidden_terms", {})
+# Extract the set of allowed type-prefix words for variable name group1.
+type_words: frozenset = yaml_data.get("type_words", frozenset())
+# Extract the set of mandatory boolean prefixes for variable name group1.
+bool_words: frozenset = yaml_data.get("bool_words", frozenset())
+# Extract the set of overly generic verbs that trigger function name warnings.
+verbs_vague: frozenset = yaml_data.get("verbs_vague", frozenset())
+# Extract the set of variable names that bypass all naming checks.
+names_exempt: frozenset = yaml_data.get("names_exempt", frozenset())
+# Extract the set of compound names exempt from per-group abbreviation scanning.
+compound_allow: frozenset = yaml_data.get("compound_allow", frozenset())
+# Extract the set of common short English words that should not trigger the heuristic.
+common_words: frozenset = yaml_data.get("common_words", frozenset())
+# Extract the set of source code keywords that are exempt from preceding-comment rules.
+comment_exempt: frozenset = yaml_data.get("comment_exempt", frozenset())
+# Convert the weak comment regex pattern list into a tuple for re.compile compatibility.
+weak_patterns: tuple = tuple(yaml_data.get("weak_patterns", frozenset()))
+# Extract the set of parameter names not requiring Sphinx directives in method docstrings.
+exempt_context: set = set(yaml_data.get("exempt_context", frozenset()))
+# Extract the set of technical terms exempt from abbreviation checks within docstring prose.
+tech_exemptions: set = set(yaml_data.get("tech_exemptions", frozenset()))
+# Extract dict keys exempt from PascalCase enforcement for external system compatibility.
+dictkey_exempt: frozenset = yaml_data.get("dictkey_exempt", frozenset())