blinter 1.1.43__py3-none-any.whl

blinter/__init__.py

@@ -0,0 +1,36 @@
+"""Blinter - professional batch file linter for Windows.
+
+Public API
+----------
+Import the symbols below from ``blinter`` for normal library and CLI use.
+
+Advanced / internal APIs live in subpackages, for example::
+
+    from blinter.rules.registry import RULES
+    from blinter.patterns import DANGEROUS_COMMAND_PATTERNS
+    from blinter.checkers.syntax import _check_syntax_errors
+"""
+
+from blinter._version import __author__, __license__, __version__
+from blinter.cli.main import main
+from blinter.config.loader import create_default_config_file, load_config
+from blinter.engine.linter import lint_batch_file
+from blinter.io.discovery import find_batch_files
+from blinter.io.encoding import read_file_with_encoding
+from blinter.models import BlinterConfig, LintIssue, Rule, RuleSeverity
+
+__all__ = [
+    "__author__",
+    "__license__",
+    "__version__",
+    "BlinterConfig",
+    "LintIssue",
+    "Rule",
+    "RuleSeverity",
+    "create_default_config_file",
+    "find_batch_files",
+    "lint_batch_file",
+    "load_config",
+    "main",
+    "read_file_with_encoding",
+]

blinter/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m blinter."""
+
+from blinter.cli.main import main
+
+if __name__ == "__main__":
+    main()

blinter/_version.py

@@ -0,0 +1,101 @@
+"""Package version resolution."""
+
+from importlib.metadata import PackageNotFoundError, version
+import logging
+from pathlib import Path
+import re
+
+__author__ = "tboy1337"
+
+__license__ = "AGPL-3.0-or-later"
+
+_PACKAGE_NAME = "Blinter"
+
+logger = logging.getLogger(__name__)
+
+# Static import so Nuitka compiles VERSION into the exe as a constant.
+# scripts/build_exe.py generates the module; source checkouts do not have it.
+# Pylint then reports import-error and a false cycle through blinter/__init__.py.
+_BAKED_VERSION: str | None
+try:
+    from ._build_version import (  # pylint: disable=import-error,cyclic-import
+        VERSION as _BAKED_VERSION,
+    )
+except ImportError:
+    logger.debug("Build version module is not present")
+    _BAKED_VERSION = None
+
+
+_PROJECT_NAME_RE = re.compile(
+    r"""^\s*name\s*=\s*['"]Blinter['"]\s*$""",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+
+def _pyproject_path() -> Path:
+    """Return pyproject.toml two directories above this module."""
+    module_file = Path(__file__).resolve()
+    package_dir = module_file.parent
+    source_path = package_dir.parent.parent / "pyproject.toml"
+    logger.debug("Resolved source pyproject.toml at %s", source_path)
+    return source_path
+
+
+def _source_checkout_pyproject() -> Path | None:
+    """Return pyproject.toml only for a src/ checkout of this project."""
+    package_dir = Path(__file__).resolve().parent
+    if package_dir.parent.name != "src":
+        logger.debug("Package directory %s is not a src/ checkout", package_dir)
+        return None
+    pyproject = package_dir.parent.parent / "pyproject.toml"
+    if not pyproject.is_file():
+        logger.debug("pyproject.toml is missing at %s", pyproject)
+        return None
+    text = pyproject.read_text(encoding="utf-8")
+    if _PROJECT_NAME_RE.search(text) is None:
+        logger.debug("pyproject.toml at %s does not declare name = Blinter", pyproject)
+        return None
+    return pyproject
+
+
+def _version_from_pyproject(pyproject: Path) -> str:
+    """Read the version assignment from a pyproject.toml file."""
+    for line in pyproject.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("version = "):
+            parsed = stripped.split("=", 1)[1].strip().strip('"').strip("'")
+            logger.debug("Parsed pyproject.toml version %s", parsed)
+            return parsed
+    logger.debug("pyproject.toml at %s has no version assignment", pyproject)
+    return "unknown"
+
+
+def _fallback_version() -> str:
+    """Read version from pyproject.toml when the package is not installed."""
+    pyproject = _pyproject_path()
+    if not pyproject.is_file():
+        logger.debug("pyproject.toml is missing at %s", pyproject)
+        return "unknown"
+    return _version_from_pyproject(pyproject)
+
+
+def get_version() -> str:
+    """Return the package version, preferring the Nuitka build constant."""
+    if isinstance(_BAKED_VERSION, str) and _BAKED_VERSION:
+        logger.debug("Using build-time version %s", _BAKED_VERSION)
+        return _BAKED_VERSION
+    source_pyproject = _source_checkout_pyproject()
+    if source_pyproject is not None:
+        pyproject_version = _version_from_pyproject(source_pyproject)
+        if pyproject_version != "unknown":
+            return pyproject_version
+    try:
+        installed = version(_PACKAGE_NAME)
+    except PackageNotFoundError:
+        logger.debug("Package metadata for %s was not found", _PACKAGE_NAME)
+        return "unknown"
+    logger.debug("Using installed metadata version %s", installed)
+    return installed
+
+
+__version__ = get_version()

blinter/checkers/__init__.py

@@ -0,0 +1,5 @@
+"""Lint rule implementations organized by category."""
+
+from blinter.checkers.orchestration import _process_file_checks
+
+__all__ = ["_process_file_checks"]

blinter/checkers/advanced/__init__.py

@@ -0,0 +1,81 @@
+"""Advanced checker subpackage."""
+
+from blinter.checkers.advanced.enhanced import (
+    _check_cmd_error_handling,
+    _check_deprecated_commands,
+    _check_enhanced_commands,
+    _check_for_f_options,
+    _check_if_comparison_quotes,
+)
+from blinter.checkers.advanced.escaping import (
+    _check_advanced_escaping_rules,
+    _check_continuation_spaces,
+    _check_double_percent_escaping,
+    _check_improper_caret_escape,
+    _check_multilevel_escaping,
+    _should_flag_caret_escape,
+)
+from blinter.checkers.advanced.style_security_perf import (
+    _check_advanced_performance,
+    _check_advanced_security,
+    _check_advanced_style_patterns,
+    _check_advanced_style_rules,
+    _check_enhanced_performance,
+    _check_enhanced_security_rules,
+    _check_function_docs,
+    _check_line_length,
+    _check_magic_numbers,
+    _check_unnecessary_output_p014,
+    _check_variable_naming,
+    _find_set_exclusion_ranges,
+    _get_safe_system_variables,
+    _has_nearby_interactive_cmds,
+    _is_number_in_special_context,
+    _is_safe_command_injection,
+)
+from blinter.checkers.advanced.vars_syntax import (
+    _check_advanced_for_rules,
+    _check_advanced_process_mgmt,
+    _check_advanced_vars,
+    _check_for_loop_var_syntax,
+    _check_percent_tilde_syntax,
+    _check_set_a_quoting,
+    _check_string_operation_syntax,
+)
+
+__all__ = [
+    "_should_flag_caret_escape",
+    "_check_improper_caret_escape",
+    "_check_multilevel_escaping",
+    "_check_continuation_spaces",
+    "_check_double_percent_escaping",
+    "_check_advanced_escaping_rules",
+    "_check_advanced_for_rules",
+    "_check_advanced_process_mgmt",
+    "_check_percent_tilde_syntax",
+    "_check_for_loop_var_syntax",
+    "_check_string_operation_syntax",
+    "_check_set_a_quoting",
+    "_check_advanced_vars",
+    "_check_for_f_options",
+    "_check_if_comparison_quotes",
+    "_check_deprecated_commands",
+    "_check_cmd_error_handling",
+    "_check_enhanced_commands",
+    "_check_advanced_security",
+    "_check_advanced_performance",
+    "_check_advanced_style_patterns",
+    "_check_variable_naming",
+    "_check_function_docs",
+    "_find_set_exclusion_ranges",
+    "_is_number_in_special_context",
+    "_check_magic_numbers",
+    "_check_line_length",
+    "_check_advanced_style_rules",
+    "_get_safe_system_variables",
+    "_is_safe_command_injection",
+    "_check_enhanced_security_rules",
+    "_check_unnecessary_output_p014",
+    "_has_nearby_interactive_cmds",
+    "_check_enhanced_performance",
+]

blinter/checkers/advanced/enhanced.py

@@ -0,0 +1,200 @@
+"""Enhanced command and deprecation checks."""
+
+import re
+from typing import (
+    List,
+    Optional,
+)
+
+from blinter.models import LintIssue
+from blinter.patterns import DEPRECATED_COMMANDS, REMOVED_COMMANDS
+from blinter.rules.registry import RULES
+
+
+def _check_for_f_options(stripped: str, line_number: int) -> Optional[LintIssue]:
+    """Check FOR /F without proper options (W020)."""
+    if re.match(
+        r'\s*for\s+/f\s+(?!.*"[^"]*(?:tokens|delims)[^"]*")[^(]*\(',
+        stripped,
+        re.IGNORECASE,
+    ):
+        return LintIssue(
+            line_number=line_number,
+            rule=RULES["W020"],
+            context="FOR /F without explicit tokens/delims options",
+        )
+    return None
+
+
+def _check_if_comparison_quotes(stripped: str, line_number: int) -> Optional[LintIssue]:
+    """Check IF comparisons without quotes (W021)."""
+    if_pattern = r'\s*if\s+(?:not\s+)?%\w+%\s*==\s*[^"\']\w+'
+    if re.search(if_pattern, stripped, re.IGNORECASE):
+        return LintIssue(
+            line_number=line_number,
+            rule=RULES["W021"],
+            context="IF comparison should be quoted",
+        )
+    return None
+
+
+def _check_deprecated_commands(stripped: str, line_number: int) -> List[LintIssue]:
+    """Check for deprecated commands (W024) and removed commands (E034)."""
+    issues: List[LintIssue] = []
+
+    # Skip comment lines (REM or ::)
+    if stripped.lower().startswith("rem ") or stripped.startswith("::"):
+        return issues
+
+    # First check for removed commands (more severe - Error level)
+    # Special handling for "NET PRINT" (just NET PRINT is removed, not NET itself)
+    if re.search(r"\bnet\s+print\b", stripped, re.IGNORECASE):
+        issues.append(
+            LintIssue(
+                line_number=line_number,
+                rule=RULES["E034"],
+                context="NET PRINT has been removed - use PowerShell Print cmdlets instead",
+            )
+        )
+
+    # Check other removed commands
+    first_word = stripped.split()[0].lower() if stripped.split() else ""
+    if first_word in REMOVED_COMMANDS:
+        replacement_map = {
+            "assign": "drive mounting with modern tools",
+            "backup": "modern backup tools (wbadmin)",
+            "diskcomp": "FC (file comparison)",
+            "append": "modify PATH or use full paths",
+            "browstat": "NET VIEW or PowerShell",
+            "edlin": "modern text editors",
+            "graftabl": "modern code-page handling",
+            "inuse": "HANDLE.EXE from Sysinternals",
+            "join": "drive mounting with modern tools",
+            "diskcopy": "ROBOCOPY or XCOPY",
+            "streams": "PowerShell Get-Item -Stream",
+        }
+        replacement = replacement_map.get(first_word, "a modern alternative")
+        issues.append(
+            LintIssue(
+                line_number=line_number,
+                rule=RULES["E034"],
+                context=(
+                    f"Command '{first_word.upper()}' has been removed "
+                    f"from Windows - use {replacement}"
+                ),
+            )
+        )
+
+    # Check for deprecated commands (Warning level)
+    # Special case for NET SEND
+    if re.search(r"\bnet\s+send\b", stripped, re.IGNORECASE):
+        issues.append(
+            LintIssue(
+                line_number=line_number,
+                rule=RULES["W024"],
+                context="Use MSG command instead of deprecated 'NET SEND'",
+            )
+        )
+
+    # Special case for AT command (needs special handling because AT is a common word)
+    # Only flag if it looks like the scheduling command (e.g., "at 14:00" or "at \\computer")
+    if re.search(r"\bat\s+(\d|\\\\)", stripped, re.IGNORECASE):
+        issues.append(
+            LintIssue(
+                line_number=line_number,
+                rule=RULES["W024"],
+                context="Use SCHTASKS command instead of deprecated 'AT'",
+            )
+        )
+
+    # Check single-word deprecated commands (skip AT; regex branch handles scheduling)
+    if first_word in DEPRECATED_COMMANDS and first_word != "at":
+        replacement_map = {
+            "wmic": "PowerShell WMI cmdlets (Get-WmiObject/Get-CimInstance)",
+            "cacls": "ICACLS command",
+            "caspol": "Code Access Security Policy Tool from SDK",
+            "winrm": "PowerShell Remoting (Enter-PSSession/Invoke-Command)",
+            "bitsadmin": "PowerShell BitsTransfer module",
+            "dpath": "PATH environment variable modification",
+            "keys": "CHOICE or SET /P commands",
+        }
+        replacement = replacement_map.get(first_word, "a modern alternative")
+        issues.append(
+            LintIssue(
+                line_number=line_number,
+                rule=RULES["W024"],
+                context=f"Command '{first_word.upper()}' is deprecated - use {replacement}",
+            )
+        )
+
+    return issues
+
+
+def _check_cmd_error_handling(
+    stripped: str, line_number: int, lines: List[str]
+) -> Optional[LintIssue]:
+    """Check for missing error handling (W025)."""
+    commands_needing_handling = ["del", "copy", "move", "mkdir", "rmdir"]
+
+    for cmd in commands_needing_handling:
+        if re.match(rf"\s*{cmd}\s+", stripped, re.IGNORECASE):
+            # Check if next 3 lines have error handling
+            for j in range(line_number, min(line_number + 3, len(lines) + 1)):
+                if j <= len(lines) and (
+                    "errorlevel" in lines[j - 1].lower()
+                    or "if " in lines[j - 1].lower()
+                ):
+                    return None
+
+            return LintIssue(
+                line_number=line_number,
+                rule=RULES["W025"],
+                context=f"{cmd.upper()} command without error checking",
+            )
+
+    return None
+
+
+def _check_enhanced_commands(lines: List[str]) -> List[LintIssue]:
+    """Check for enhanced command validation issues (W020-W025)."""
+    issues: List[LintIssue] = []
+    uses_delayed_expansion = False
+
+    for i, line in enumerate(lines, start=1):
+        stripped = line.strip()
+
+        # Check for delayed expansion usage
+        if re.search(r"!\w+!", stripped):
+            uses_delayed_expansion = True
+
+        # Run all line-level checks
+        issue = _check_for_f_options(stripped, i)
+        if issue:
+            issues.append(issue)
+
+        issue = _check_if_comparison_quotes(stripped, i)
+        if issue:
+            issues.append(issue)
+
+        issues.extend(_check_deprecated_commands(stripped, i))
+
+        issue = _check_cmd_error_handling(stripped, i, lines)
+        if issue:
+            issues.append(issue)
+
+    # Check for missing SETLOCAL EnableDelayedExpansion (W022)
+    if uses_delayed_expansion:
+        has_setlocal = any(
+            re.search(r"setlocal.*enabledelayedexpansion", line, re.IGNORECASE)
+            for line in lines
+        )
+        if not has_setlocal:
+            issues.append(
+                LintIssue(
+                    line_number=1,
+                    rule=RULES["W022"],
+                    context="Script uses !var! but missing SETLOCAL EnableDelayedExpansion",
+                )
+            )
+
+    return issues

blinter/checkers/advanced/escaping.py

@@ -0,0 +1,145 @@
+"""Advanced caret and percent escaping rules (E030-E033)."""
+
+import re
+from typing import List
+
+from blinter.models import LintIssue
+from blinter.rules.helpers import strip_percent_expansions
+from blinter.rules.registry import RULES
+
+
+def _should_flag_caret_escape(stripped: str, caret_pos: int, line: str = "") -> bool:
+    """Check if a caret escape sequence should be flagged as improper."""
+    # Check if this is within a FOR loop command string (within single quotes)
+    # In FOR loops, command strings like 'command 2^>nul ^| filter' use single caret correctly
+    if re.search(r"\bfor\s+", stripped, re.IGNORECASE):
+        # Find all single-quoted strings in FOR commands
+        # Look for patterns like FOR ... IN ('...') where carets inside quotes are valid
+        for_match = re.search(r"\bin\s*\('([^']*)'\)", stripped, re.IGNORECASE)
+        if for_match:
+            # Check if the caret is within the quoted string
+            quote_start = for_match.start(1)
+            quote_end = for_match.end(1)
+            if quote_start <= caret_pos < quote_end:
+                return False
+
+    # Check if this is an ECHO statement (likely ASCII art)
+    if re.match(r"echo\s+", stripped, re.IGNORECASE):
+        # ECHO statements often contain ASCII art with carets - don't flag these
+        return False
+
+    # Check if this is a SET statement (storing escaped commands)
+    # SET commands often store command strings with escaped special characters
+    # Example: SET @PRINT_IF_DEBUG=ECHO:^& SET @^& ECHO:^& TIMEOUT 5
+    # Also check for SET inside IF statements: IF ... (SET VAR=value^&...)
+    if re.search(r"\bset\s+", stripped, re.IGNORECASE):
+        # SET statements commonly use single carets to store command strings - don't flag these
+        return False
+
+    # Check if this line is within a parenthesized command block (FOR DO block, IF block, etc.)
+    # Lines inside blocks are typically indented and need carets for proper redirection
+    # Pattern: line starts with whitespace/tabs (indented) and contains command with redirection
+    if line and re.match(r"^\s+", line):
+        # This is an indented line, likely inside a block
+        # Carets for redirection (2^>NUL, ^|, etc.) are necessary in blocks
+        # to prevent premature evaluation
+        return False
+
+    # Check if this line is a DO block on the same line as FOR
+    # Pattern: FOR ... DO ( command with carets )
+    if re.search(r"\bdo\s*\(", stripped, re.IGNORECASE):
+        # This is a FOR DO block, carets are necessary
+        return False
+
+    return True
+
+
+def _check_improper_caret_escape(
+    stripped: str, line_number: int, line: str = ""
+) -> List[LintIssue]:
+    """Check for E030: Improper caret escape sequence."""
+    issues: List[LintIssue] = []
+    # Look for single caret attempting to escape special chars
+    # But exclude FOR loop command strings, ECHO statements (ASCII art), and SET commands
+    caret_matches = re.finditer(r"\^[&|><](?!\^)", stripped)
+    for match in caret_matches:
+        caret_pos = match.start()
+        if _should_flag_caret_escape(stripped, caret_pos, line):
+            issues.append(LintIssue(line_number, RULES["E030"], context=stripped))
+    return issues
+
+
+def _check_multilevel_escaping(stripped: str, line_number: int) -> List[LintIssue]:
+    """Check for E031: Invalid multilevel escaping."""
+    issues: List[LintIssue] = []
+    # Check for incorrect caret counts in multilevel escaping
+    caret_sequences: List[str] = re.findall(r"\^+[&|><]", stripped)
+    for seq in caret_sequences:
+        caret_count = len(seq) - 1  # -1 for the target character
+        # Valid counts follow 2^n-1 pattern: 1, 3, 7, 15...
+        valid_counts: List[int] = [1, 3, 7, 15, 31]  # 2^n-1 pattern for n=1 to 5
+        if caret_count > 0 and caret_count not in valid_counts:
+            issues.append(LintIssue(line_number, RULES["E031"], context=seq))
+    return issues
+
+
+def _check_continuation_spaces(
+    line: str, stripped: str, line_number: int
+) -> List[LintIssue]:
+    """Check for E032: Continuation character with trailing spaces."""
+    issues: List[LintIssue] = []
+    # Check if line ends with ^ followed by spaces/tabs (before the line ending)
+    if stripped.endswith("^"):
+        # Get the line without line endings
+        line_no_newline = line.rstrip("\r\n")
+        # If the line doesn't end with ^ after removing spaces,
+        # then there are trailing spaces after ^
+        if not line_no_newline.endswith("^"):
+            issues.append(
+                LintIssue(
+                    line_number, RULES["E032"], context="Caret with trailing spaces"
+                )
+            )
+    return issues
+
+
+def _check_double_percent_escaping(stripped: str, line_number: int) -> List[LintIssue]:
+    """Check for E033: Double percent escaping error."""
+    issues: List[LintIssue] = []
+    # Look for single % in echo statements that should be %%
+    if stripped.lower().startswith("echo") and "%" in stripped:
+        # Only flag if there's a literal percentage (like "50%") not a variable reference
+        # Variable references like %var% are fine
+        # Check for percentage signs that might need escaping (number followed by %)
+        # But exclude variable references %VAR%
+        line_without_vars = strip_percent_expansions(stripped)
+        if re.search(r"\b\d+%(?!%)", line_without_vars):
+            issues.append(
+                LintIssue(
+                    line_number,
+                    RULES["E033"],
+                    context="Percentage needs double escaping",
+                )
+            )
+    return issues
+
+
+def _check_advanced_escaping_rules(line: str, line_number: int) -> List[LintIssue]:
+    """Check for advanced escaping technique issues."""
+    # Multiple escaping rules (E030-E033) require checking various patterns
+    issues: List[LintIssue] = []
+    stripped = line.strip()
+
+    # E030: Improper caret escape sequence
+    issues.extend(_check_improper_caret_escape(stripped, line_number, line))
+
+    # E031: Invalid multilevel escaping
+    issues.extend(_check_multilevel_escaping(stripped, line_number))
+
+    # E032: Continuation character with trailing spaces
+    issues.extend(_check_continuation_spaces(line, stripped, line_number))
+
+    # E033: Double percent escaping error
+    issues.extend(_check_double_percent_escaping(stripped, line_number))
+
+    return issues