CLASPLint 0.1.0__cp38-none-any.whl

CLASPLint/__init__.py

@@ -0,0 +1,6 @@
+# Provide the CLASPLint package entry point and version information.
+
+# Define the package version string.
+__version__ = "0.1.0"
+# Expose the runner and reporter modules as the public API.
+__all__ = ["runner", "reporter"]

CLASPLint/__main__.py

@@ -0,0 +1,98 @@
+# Provide the CLASPLint command-line interface entry point.
+
+import argparse
+import sys
+import os
+
+from .runner import run
+from . import __version__
+
+
+def _init_build_parser_function_() -> argparse.ArgumentParser:
+    """Construct the argument parser for the CLASPLint CLI."""
+    # Create the top-level argument parser with a description.
+    parser_result = argparse.ArgumentParser(
+        prog="CLASPLint",
+        description="CLASP 3.0 / PEP 2606 static analysis tool. "
+                    "Checks variable, dict key, function, class naming "
+                    "and comment/log conventions.",
+    )
+    # Accept one or more file or directory paths as positional arguments.
+    parser_result.add_argument(
+        "paths", nargs="*", default=["."],
+        help="Python files or directories to check (default: current directory).",
+    )
+    # Provide a --version flag to display the tool version.
+    parser_result.add_argument(
+        "--version", action="version",
+        version=f"CLASPLint {__version__}",
+    )
+    # Provide a flag to disable recursive directory traversal.
+    parser_result.add_argument(
+        "--no-recursive", action="store_true",
+        help="Do not recursively check subdirectories.",
+    )
+    # Provide a quiet mode that suppresses per-violation output.
+    parser_result.add_argument(
+        "--quiet", "-q", action="store_true",
+        help="Suppress individual violation output; show only summary.",
+    )
+    # Provide a category filter to report only specific violation types.
+    parser_result.add_argument(
+        "--category", "-c",
+        choices=["variable", "dict_key", "function", "comment", "log"],
+        help="Only report violations of a specific category.",
+    )
+    # Return the fully configured argument parser.
+    return parser_result
+
+
+def main(argv: list = None) -> int:
+    """Execute the CLASPLint analysis and return an exit code (0 = clean, 1 = violations)."""
+    # Build and parse command-line arguments.
+    parser = _init_build_parser_function_()
+    # Parse the provided arguments or default to sys.argv.
+    args = 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:
+        # Convert the path to an absolute path.
+        string_absolute = os.path.abspath(string_path)
+        # Only include paths that exist on the filesystem.
+        if os.path.exists(string_absolute):
+            list_resolved.append(string_absolute)
+    # Report an error if no valid paths were found.
+    if not list_resolved:
+        # Print an error message to stderr.
+        print("CLASPLint: No valid Python files or directories found.", file=sys.stderr)
+        # Return exit code 2 for usage errors.
+        return 2
+    # Determine whether to recurse into subdirectories.
+    bool_recursive = not args.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:
+        # Filter violations to only the requested category.
+        report_result.list_violations = [
+            v for v in report_result.list_violations
+            # Keep only violations matching the requested category filter.
+            if v.string_category == args.category
+        ]
+    # 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:
+        # Add a blank line before the violation listing.
+        print()
+        # Print the formatted violation details.
+        print(report_result.format_violations())
+    # Return exit code 1 if violations were found, 0 otherwise.
+    return 1 if report_result.has_violations else 0
+
+
+# Execute the main function when the module is run directly.
+if __name__ == "__main__":
+    # Exit with the code returned by main().
+    sys.exit(main())

CLASPLint/comment_checker.py

@@ -0,0 +1,227 @@
+# Check that every code line has a proper CLASP 3.0 formatted comment.
+
+import ast
+import io
+import tokenize
+from typing import List, Set
+
+from .reporter import Violation
+
+# Define control flow and operation keywords that require a preceding comment.
+keywords_requirecomment = frozenset({
+    "if", "elif", "else", "for", "while", "try", "except",
+    "finally", "with", "return", "raise", "continue", "break",
+    "pass",
+})
+
+
+def _tokenize_source(string_source: str) -> List[tokenize.TokenInfo]:
+    """Tokenize source code and return the list of tokens."""
+    # Generate tokens from the source string using a StringIO buffer.
+    return list(tokenize.generate_tokens(io.StringIO(string_source).readline))
+
+
+class CommentChecker:
+    """Check that every code line has a proper CLASP 3.0 comment."""
+
+    def __init__(self, string_filepath: str, string_source: str):
+        # Store the file path for violation reporting.
+        self.string_filepath = string_filepath
+        # Store the full source code as a string.
+        self.string_source = string_source
+        # Split source into lines for per-line access.
+        self.list_sourcelines = string_source.splitlines()
+        # Collect violations found during checking.
+        self.list_violations: List[Violation] = []
+
+    def run(self) -> None:
+        """Run all comment format and presence checks."""
+        # Check that every code line requiring a comment has one.
+        self._init_line_comments_function_()
+        # Check that every comment follows the required format.
+        self._init_comment_format_function_()
+
+    def _init_line_comments_function_(self) -> None:
+        """Verify that every physical code line with a control keyword has a comment."""
+        # Attempt to tokenize the source; skip if tokenization fails.
+        try:
+            list_tokens = _tokenize_source(self.string_source)
+        # Return early if the source cannot be tokenized.
+        except tokenize.TokenError:
+            # Exit the method early when tokenization fails.
+            return
+        # Build a set of line numbers containing code tokens.
+        set_codelines: Set[int] = set()
+        # Build a set of line numbers containing comment tokens.
+        set_commentlines: Set[int] = set()
+        # Classify each token to identify code lines and comment lines.
+        for token_item in list_tokens:
+            # Add comment token line numbers to the comment set.
+            if token_item.type == tokenize.COMMENT:
+                set_commentlines.add(token_item.start[0])
+            # Add single-line string token line numbers to the code set.
+            elif token_item.type == tokenize.STRING and token_item.start[0] == token_item.end[0]:
+                set_codelines.add(token_item.start[0])
+            # Add all other meaningful token line numbers to the code set.
+            elif token_item.type not in (
+                tokenize.NEWLINE, tokenize.NL, tokenize.ENDMARKER,
+                tokenize.INDENT, tokenize.DEDENT, tokenize.ENCODING,
+            ):
+                set_codelines.add(token_item.start[0])
+        # Check each code line for required comments.
+        for int_lineno in sorted(set_codelines):
+            # Skip lines beyond the source file length.
+            if int_lineno > len(self.list_sourcelines):
+                # Exit the loop iteration for out-of-bounds line numbers.
+                continue
+            # Get the trimmed text of the current line.
+            string_linetext = self.list_sourcelines[int_lineno - 1].strip()
+            # Skip blank lines as they contain no code to comment.
+            if not string_linetext:
+                # Exit the loop iteration for blank lines.
+                continue
+            # Skip comment-only lines as they serve as their own comment.
+            if int_lineno in set_commentlines and string_linetext.startswith("#"):
+                # Exit the loop iteration for comment-only lines.
+                continue
+            # Skip lines that are part of a docstring.
+            if self._init_docstring_line_function_(int_lineno):
+                # Exit the loop iteration for docstring lines.
+                continue
+            # Determine whether a comment exists on the same line or the previous line.
+            bool_hascomment = int_lineno in set_commentlines
+            # Check the previous non-blank line as an alternative comment location.
+            if not bool_hascomment and int_lineno > 1:
+                # Get the trimmed text of the previous line.
+                string_previoustext = self.list_sourcelines[int_lineno - 2].strip()
+                # Treat a preceding comment line as satisfying the requirement.
+                if string_previoustext.startswith("#"):
+                    bool_hascomment = True
+            # Report a violation if no comment was found for a keyword line.
+            if not bool_hascomment:
+                # Extract the first word of the line to check against required keywords.
+                list_words = string_linetext.split()
+                # Default to empty string if the line has no words.
+                string_firstword = list_words[0] if list_words else ""
+                # Strip trailing colon from keywords like "if:" or "else:".
+                string_keyword = string_firstword.rstrip(":")
+                # Check if this line's keyword requires a comment.
+                if string_keyword in keywords_requirecomment:
+                    # Record a missing-comment violation for this keyword line.
+                    self.list_violations.append(Violation(
+                        string_filepath=self.string_filepath,
+                        int_linenumber=int_lineno,
+                        string_category="comment",
+                        string_message=(
+                            f"Line {int_lineno} with keyword '{string_keyword}' "
+                            f"lacks a required preceding comment."
+                        ),
+                        string_sourceline=self.list_sourcelines[int_lineno - 1],
+                    ))
+
+    def _init_comment_format_function_(self) -> None:
+        """Verify that every comment follows the 'Capitalized sentence.' format."""
+        # Attempt to tokenize the source; skip if tokenization fails.
+        try:
+            list_tokens = _tokenize_source(self.string_source)
+        # Return early if the source cannot be tokenized.
+        except tokenize.TokenError:
+            # Exit the method early when tokenization fails.
+            return
+        # Check each comment token for format compliance.
+        for token_item in list_tokens:
+            # Skip non-comment tokens.
+            if token_item.type != tokenize.COMMENT:
+                # Proceed to the next token in the loop.
+                continue
+            # Get the raw comment text including the leading '#'.
+            string_comment = token_item.string
+            # Check that the comment starts with '# ' (hash followed by space).
+            if not string_comment.startswith("# "):
+                # Record a violation for missing space after hash.
+                self.list_violations.append(Violation(
+                    string_filepath=self.string_filepath,
+                    int_linenumber=token_item.start[0],
+                    string_category="comment",
+                    string_message=(
+                        f"Comment must start with '# ' (hash, space). "
+                        f"Found: '{string_comment[:20]}...'"
+                    ),
+                    string_sourceline=self.list_sourcelines[token_item.start[0] - 1],
+                ))
+                # Skip further checks on malformed comments.
+                continue
+            # Extract the content after '# '.
+            string_content = string_comment[2:].strip()
+            # Skip empty comments as they are permitted placeholder comments.
+            if not string_content:
+                # Proceed to the next token for empty comment content.
+                continue
+            # Skip special marker comments like shebang, type: ignore, and noqa.
+            if string_content.startswith("!") or string_content.startswith("type:") or string_content.startswith("noqa"):
+                # Proceed to the next token for special marker comments.
+                continue
+            # Check that the comment text starts with a capital letter.
+            if string_content[0].islower():
+                # Record a violation for lowercase start.
+                self.list_violations.append(Violation(
+                    string_filepath=self.string_filepath,
+                    int_linenumber=token_item.start[0],
+                    string_category="comment",
+                    string_message=(
+                        f"Comment text must start with a capital letter. "
+                        f"Found: '{string_content[:30]}...'"
+                    ),
+                    string_sourceline=self.list_sourcelines[token_item.start[0] - 1],
+                ))
+            # Check that the comment text ends with a period or other valid punctuation.
+            if not string_content.endswith("."):
+                # Allow common sentence-ending punctuation alternatives.
+                if not any(string_content.endswith(p) for p in (".", "!", "?", ":", ";", ")")):
+                    # Record a violation for missing terminal period.
+                    self.list_violations.append(Violation(
+                        string_filepath=self.string_filepath,
+                        int_linenumber=token_item.start[0],
+                        string_category="comment",
+                        string_message=(
+                            f"Comment must end with a period. "
+                            f"Found: '{string_content[:40]}'"
+                        ),
+                        string_sourceline=self.list_sourcelines[token_item.start[0] - 1],
+                    ))
+
+    def _init_docstring_line_function_(self, int_lineno: int) -> bool:
+        """Determine whether a given line is part of a docstring."""
+        # Attempt to parse the source into an AST; skip if parsing fails.
+        try:
+            tree = ast.parse(self.string_source)
+        # Return False if the source has syntax errors.
+        except SyntaxError:
+            # Return False to indicate the line is not part of a docstring.
+            return False
+        # Walk all AST nodes to find docstring nodes.
+        for node in ast.walk(tree):
+            # Check function, class, and module nodes for docstrings.
+            if isinstance(node, (ast.FunctionDef, ast.ClassDef, ast.Module)):
+                # Retrieve the docstring using ast.get_docstring.
+                string_docstring = ast.get_docstring(node)
+                # Skip nodes without docstrings.
+                if string_docstring:
+                    # Access the first statement in the body (the docstring expression).
+                    list_body = node.body
+                    # Verify the body exists and the first statement is an expression.
+                    if list_body and isinstance(list_body[0], ast.Expr):
+                        # Get the expression node.
+                        node_expression = list_body[0]
+                        # Verify the expression value is a string constant.
+                        if isinstance(node_expression.value, ast.Constant) and isinstance(node_expression.value.value, str):
+                            # Get the starting line of the docstring.
+                            int_startline = node_expression.lineno
+                            # Get the ending line, defaulting to start line if not set.
+                            int_endline = node_expression.end_lineno or int_startline
+                            # Check whether the queried line falls within the docstring range.
+                            if int_startline <= int_lineno <= int_endline:
+                                # The line is part of a docstring.
+                                return True
+        # The line is not part of any docstring.
+        return False

CLASPLint/dict_key_checker.py

@@ -0,0 +1,87 @@
+# Check dictionary key names against CLASP 3.0 PascalCase and abbreviation rules.
+
+import ast
+from typing import List
+
+from .naming_utils import validate_dictkey_format
+from .reporter import Violation
+
+
+class DictKeyChecker(ast.NodeVisitor):
+    """Walk the AST and check dictionary key names against CLASP 3.0 rules."""
+
+    def __init__(self, string_filepath: str, list_sourcelines: List[str]):
+        # Store the file path for violation reporting.
+        self.string_filepath = string_filepath
+        # Store source lines for contextual violation messages.
+        self.list_sourcelines = list_sourcelines
+        # Collect violations found during AST traversal.
+        self.list_violations: List[Violation] = []
+
+    def _init_key_function_(self, node_key: ast.AST, node_dict: ast.AST) -> None:
+        """Validate a single dictionary key literal."""
+        # Only string literal keys are checked; skip non-constant or non-string keys.
+        if not isinstance(node_key, ast.Constant):
+            # Exit early for non-constant dict key nodes.
+            return
+        # Skip keys whose values are not strings.
+        if not isinstance(node_key.value, str):
+            # Exit early for keys whose values are not strings.
+            return
+        # Extract the key string value.
+        string_key = node_key.value
+        # Run the CLASP 3.0 dict key format validation.
+        list_issues = validate_dictkey_format(string_key)
+        # Retrieve the source line for contextual output.
+        string_sourceline = ""
+        # Ensure the line number is within bounds before accessing source lines.
+        if node_key.lineno and node_key.lineno <= len(self.list_sourcelines):
+            string_sourceline = self.list_sourcelines[node_key.lineno - 1]
+        # Append each detected violation to the violations list.
+        for string_message in list_issues:
+            self.list_violations.append(Violation(
+                string_filepath=self.string_filepath,
+                int_linenumber=node_key.lineno,
+                string_category="dict_key",
+                string_message=string_message,
+                string_sourceline=string_sourceline,
+            ))
+
+    def visit_Dict(self, node: ast.Dict) -> None:
+        """Check keys in dictionary literal expressions."""
+        # Iterate over each key node in the dictionary literal.
+        for node_key in node.keys:
+            # Process non-None keys through the key validator.
+            if node_key is not None:
+                self._init_key_function_(node_key, node)
+        # Continue visiting child nodes for nested dictionaries.
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        """Check dict() constructor calls for keyword argument key names."""
+        # Detect calls to the built-in dict() constructor.
+        if isinstance(node.func, ast.Name) and node.func.id == "dict":
+            # Check each keyword argument name as a potential dict key.
+            for node_keyword in node.keywords:
+                # Validate the keyword argument if it has an explicit name.
+                if node_keyword.arg:
+                    self._init_keyword_as_key_function_(node_keyword)
+        # Continue visiting child nodes.
+        self.generic_visit(node)
+
+    def _init_keyword_as_key_function_(self, node_keyword: ast.keyword) -> None:
+        """Validate a keyword argument name used as a dictionary key."""
+        # Extract the keyword argument name.
+        string_key = node_keyword.arg
+        # Skip empty or missing keyword argument names.
+        if not string_key:
+            # Exit early for empty keyword argument names.
+            return
+        # Python keyword arguments are identifiers and cannot use PascalCase directly;
+        # Only flag if the name clearly violates PascalCase convention expectations.
+        pass
+
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        """Visit subscript nodes for potential dict key access within Assign statements."""
+        # Subscript key checks are handled during Assign target walking.
+        self.generic_visit(node)

CLASPLint/function_checker.py

@@ -0,0 +1,95 @@
+# Check function and class names against CLASP 3.0 naming conventions.
+
+import ast
+from typing import List
+
+from .naming_utils import (
+    validate_function_name,
+    validate_class_name,
+    length_namemax,
+)
+from .reporter import Violation
+
+
+class FunctionChecker(ast.NodeVisitor):
+    """Walk the AST and check function and class names against CLASP 3.0 rules."""
+
+    def __init__(self, string_filepath: str, list_sourcelines: List[str]):
+        # Store the file path for violation reporting.
+        self.string_filepath = string_filepath
+        # Store source lines for contextual violation messages.
+        self.list_sourcelines = list_sourcelines
+        # Collect violations found during AST traversal.
+        self.list_violations: List[Violation] = []
+        # Track the current class context for method detection.
+        self.string_currentclass: str = ""
+
+    def _init_source_line_function_(self, node: ast.AST) -> str:
+        """Retrieve the source line text for a given AST node."""
+        # Return the source line if the node has a valid line number within bounds.
+        if node.lineno and node.lineno <= len(self.list_sourcelines):
+            # Retrieve and return the corresponding source line text.
+            return self.list_sourcelines[node.lineno - 1]
+        # Return an empty string if the line number is unavailable or out of range.
+        return ""
+
+    def _init_add_violations_function_(self, string_name: str, string_category: str,
+                         list_issues: list, node: ast.AST) -> None:
+        """Record a list of naming violations with source context."""
+        # Retrieve the source line associated with the violation node.
+        string_sourceline = self._init_source_line_function_(node)
+        # Append each issue as a Violation to the violations list.
+        for string_message in list_issues:
+            self.list_violations.append(Violation(
+                string_filepath=self.string_filepath,
+                int_linenumber=node.lineno,
+                string_category=string_category,
+                string_message=string_message,
+                string_sourceline=string_sourceline,
+            ))
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Check the class name for PascalCase format and abbreviation violations."""
+        # Validate the class name against CLASP 3.0 class naming rules.
+        list_issues = validate_class_name(node.name)
+        # Record any class name violations found.
+        self._init_add_violations_function_(node.name, "function", list_issues, node)
+        # Save the previous class context before entering the new class.
+        string_previous = self.string_currentclass
+        # Set the current class context for method detection.
+        self.string_currentclass = node.name
+        # Visit child nodes within the class body.
+        self.generic_visit(node)
+        # Restore the previous class context after leaving the class.
+        self.string_currentclass = string_previous
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Check the function or method name for snake_case and abbreviation violations."""
+        # Determine whether this function is a method inside a class.
+        bool_ismethod = bool(self.string_currentclass)
+        # Validate the function name against CLASP 3.0 function naming rules.
+        list_issues = validate_function_name(node.name, is_method=bool_ismethod)
+        # Use the "function" category for all function and method violations.
+        string_category = "function"
+        # Record any function name violations found.
+        self._init_add_violations_function_(node.name, string_category, list_issues, node)
+        # Check method name length for public methods specifically.
+        if bool_ismethod and len(node.name) > length_namemax:
+            # Record a violation for excessively long method names.
+            self.list_violations.append(Violation(
+                string_filepath=self.string_filepath,
+                int_linenumber=node.lineno,
+                string_category=string_category,
+                string_message=(
+                    f"Method '{node.name}' exceeds {length_namemax} characters "
+                    f"(length: {len(node.name)})."
+                ),
+                string_sourceline=self._init_source_line_function_(node),
+            ))
+        # Continue visiting the function body for nested definitions.
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        """Check async function names using the same logic as regular functions."""
+        # Delegate to the standard function definition visitor.
+        self.visit_FunctionDef(node)