zshshellcheck 0.2.1__py3-none-any.whl

zshcheck/__init__.py

@@ -0,0 +1,3 @@
+"""ZshCheck - A static analysis tool for zsh shell scripts."""
+
+__version__ = "0.1.0"

zshcheck/analyzer.py

@@ -0,0 +1,269 @@
+"""Analyzer module for zshcheck.
+
+This module provides the main analysis engine that orchestrates parsing,
+running checks, and collecting diagnostics.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from tree_sitter import Node
+
+from zshcheck.checks.base import AnalysisContext, CheckRegistry, get_registry
+from zshcheck.diagnostics import Diagnostic, Position, Range, Severity
+from zshcheck.parser import ZshParser
+
+NON_ASCII_PATTERN = re.compile(r"[^\x00-\x7F]")
+
+
+def _check_non_ascii(source: str) -> list[Diagnostic]:
+    """Check for non-ASCII characters (including emojis) that may cause parsing issues.
+
+    Args:
+        source: The source code to check.
+
+    Returns:
+        List of diagnostics for non-ASCII characters found.
+    """
+    diagnostics: list[Diagnostic] = []
+    matches = list(NON_ASCII_PATTERN.finditer(source))
+
+    if not matches:
+        return diagnostics
+
+    chars = [m.group() for m in matches[:5]]
+    chars_str = " ".join(f"'{c}'" for c in chars)
+
+    diagnostic = Diagnostic(
+        code="ZC9004",
+        severity=Severity.INFO,
+        message=(
+            f"Non-ASCII characters detected ({len(matches)} found). "
+            "tree-sitter-zsh grammar may not parse these correctly. "
+            f"Found: {chars_str}"
+        ),
+        range=Range(Position(1, 1), Position(1, 1)),
+    )
+    diagnostics.append(diagnostic)
+    return diagnostics
+
+
+def apply_fixes(source: str, fixes: list[Diagnostic]) -> str:
+    """Apply fixes to source code.
+
+    Args:
+        source: Original source code.
+        fixes: List of diagnostics with fixes to apply.
+
+    Returns:
+        Source code with fixes applied.
+    """
+    if not fixes:
+        return source
+
+    result = source
+    ordered_fixes = sorted(
+        [f for f in fixes if f.fixable],
+        key=lambda d: (d.range.start.line, d.range.start.column),
+        reverse=True,
+    )
+
+    for diagnostic in ordered_fixes:
+        if diagnostic.fix is None:
+            continue
+        for replacement in diagnostic.fix.replacements:
+            start_line = replacement.range.start.line - 1
+            start_col = replacement.range.start.column - 1
+            end_line = replacement.range.end.line - 1
+            end_col = replacement.range.end.column
+
+            lines = result.splitlines(keepends=True)
+            if start_line < 0 or start_line >= len(lines):
+                continue
+            if end_line < 0 or end_line >= len(lines):
+                continue
+
+            if start_line == end_line:
+                line = lines[start_line]
+                lines[start_line] = line[:start_col] + replacement.text + line[end_col:]
+            else:
+                first_line = lines[start_line]
+                lines[start_line] = first_line[:start_col] + replacement.text + "\n"
+                del lines[start_line + 1 : end_line + 1]
+
+            result = "".join(lines)
+
+    return result
+
+
+class Analyzer:
+    """Main analysis engine for zsh shell scripts."""
+
+    def __init__(self, registry: CheckRegistry | None = None) -> None:
+        """Initialize the analyzer.
+
+        Args:
+            registry: Check registry to use (creates default if None).
+        """
+        self._parser = ZshParser()
+        self._registry = registry or get_registry()
+
+    def analyze_string(
+        self,
+        source: str,
+        filename: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+    ) -> list[Diagnostic]:
+        """Analyze a zsh script from a string.
+
+        Args:
+            source: The zsh script source code.
+            filename: Optional filename for context.
+            include: Optional list of check codes to run.
+            exclude: Optional list of check codes to skip.
+
+        Returns:
+            List of diagnostics found.
+        """
+        parse_result = self._parser.parse(source)
+
+        # Collect parse errors first
+        all_diagnostics: list[Diagnostic] = list(parse_result.diagnostics)
+
+        # Check for non-ASCII characters
+        all_diagnostics.extend(_check_non_ascii(source))
+
+        if not parse_result.success or parse_result.root_node is None:
+            return all_diagnostics
+
+        # Create analysis context
+        context = AnalysisContext(
+            source=source,
+            filename=filename,
+        )
+
+        # Run all checks on the AST
+        check_diagnostics = self._run_checks(
+            parse_result.root_node,
+            context,
+            include=include,
+            exclude=exclude,
+        )
+
+        all_diagnostics.extend(check_diagnostics)
+
+        # Sort by line number, then column
+        all_diagnostics.sort()
+
+        return all_diagnostics
+
+    def analyze_file(
+        self,
+        path: str | Path,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+    ) -> list[Diagnostic]:
+        """Analyze a zsh script from a file.
+
+        Args:
+            path: Path to the zsh script file.
+            include: Optional list of check codes to run.
+            exclude: Optional list of check codes to skip.
+
+        Returns:
+            List of diagnostics found.
+        """
+        file_path = Path(path)
+        parse_result = self._parser.parse_file(file_path)
+
+        # Collect parse errors first
+        all_diagnostics: list[Diagnostic] = list(parse_result.diagnostics)
+
+        # Check for non-ASCII characters
+        all_diagnostics.extend(_check_non_ascii(parse_result.source))
+
+        if not parse_result.success or parse_result.root_node is None:
+            return all_diagnostics
+
+        # Create analysis context
+        context = AnalysisContext(
+            source=parse_result.source,
+            filename=str(file_path),
+        )
+
+        # Run all checks on the AST
+        check_diagnostics = self._run_checks(
+            parse_result.root_node,
+            context,
+            include=include,
+            exclude=exclude,
+        )
+
+        all_diagnostics.extend(check_diagnostics)
+
+        # Sort by line number, then column
+        all_diagnostics.sort()
+
+        return all_diagnostics
+
+    def _run_checks(
+        self,
+        root_node: Node,
+        context: AnalysisContext,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+    ) -> list[Diagnostic]:
+        """Run all checks against the AST.
+
+        Args:
+            root_node: Root node of the AST.
+            context: Analysis context.
+            include: Optional list of check codes to run.
+            exclude: Optional list of check codes to skip.
+
+        Returns:
+            List of diagnostics found.
+        """
+        diagnostics: list[Diagnostic] = []
+        exclude_set = set(exclude or [])
+
+        def visit_node(node: Node, depth: int) -> None:
+            # Run checks that are not excluded
+            for check in self._registry.checks:
+                if check.code in exclude_set:
+                    continue
+                if include is not None and check.code not in include:
+                    continue
+
+                if diagnostic := check.check(node, context):
+                    diagnostics.append(diagnostic)
+
+            # Visit children
+            for child in node.children:
+                visit_node(child, depth + 1)
+
+        visit_node(root_node, 0)
+        return diagnostics
+
+
+def create_default_analyzer() -> Analyzer:
+    """Create an analyzer with all default checks registered."""
+    from zshcheck.checks.commands import DeprecatedCommandCheck
+    from zshcheck.checks.quoting import UnquotedVariableCheck
+    from zshcheck.checks.style import DoubleBracketCheck
+    from zshcheck.checks.variables import UnusedVariableCheck
+
+    registry = CheckRegistry()
+    registry.register_all(
+        [
+            UnquotedVariableCheck(),
+            UnusedVariableCheck(),
+            DeprecatedCommandCheck(),
+            DoubleBracketCheck(),
+        ]
+    )
+
+    return Analyzer(registry)

zshcheck/checks/__init__.py

@@ -0,0 +1 @@
+"""Checks package for zshcheck."""

zshcheck/checks/base.py

@@ -0,0 +1,225 @@
+"""Base check module for zshcheck.
+
+This module defines the abstract base class that all checks must implement,
+along with the check registry for managing and running checks.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from tree_sitter import Node
+
+from zshcheck.diagnostics import Diagnostic, Severity
+
+
+@dataclass
+class AnalysisContext:
+    """Context information available during analysis.
+
+    This object maintains state about the current script being analyzed,
+    including variable scopes, function definitions, and shell options.
+
+    Attributes:
+        source: The full source code being analyzed.
+        filename: Name of the file being analyzed (if available).
+        variables: Dictionary of declared variables and their scopes.
+        functions: Set of defined function names.
+        aliases: Dictionary of defined aliases.
+        shell_options: Set of enabled shell options.
+    """
+
+    source: str
+    filename: str | None = None
+    variables: dict[str, str] = field(default_factory=dict)  # name -> scope
+    functions: set[str] = field(default_factory=set)
+    aliases: dict[str, str] = field(default_factory=dict)
+    shell_options: set[str] = field(default_factory=set)
+
+    def is_variable_defined(self, name: str) -> bool:
+        """Check if a variable is defined in the current context."""
+        return name in self.variables
+
+    def is_function_defined(self, name: str) -> bool:
+        """Check if a function is defined."""
+        return name in self.functions
+
+
+class BaseCheck(ABC):
+    """Abstract base class for all zshcheck checks.
+
+    Each check must implement the following properties and methods:
+    - code: Unique check identifier (e.g., "ZC1001")
+    - description: Human-readable description of what the check looks for
+    - severity: Default severity level for this check
+    - check: The actual check logic
+    """
+
+    @property
+    @abstractmethod
+    def code(self) -> str:
+        """Unique check code (e.g., "ZC1001").
+
+        Codes should follow this convention:
+        - ZC1xxx: Quoting and word splitting issues
+        - ZC2xxx: Variable tracking issues
+        - ZC3xxx: Zsh-specific issues
+        - ZC4xxx: Command usage issues
+        - ZC5xxx: Style suggestions
+        - ZC9xxx: Internal/parsing errors
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Short human-readable description of what this check looks for."""
+        pass
+
+    @property
+    @abstractmethod
+    def severity(self) -> Severity:
+        """Default severity level for diagnostics from this check."""
+        pass
+
+    @abstractmethod
+    def check(self, node: Node, context: AnalysisContext) -> Diagnostic | None:
+        """Analyze a single AST node and return a diagnostic if an issue is found.
+
+        Args:
+            node: The AST node to analyze.
+            context: Analysis context with script state information.
+
+        Returns:
+            A Diagnostic if an issue is found, None otherwise.
+        """
+        pass
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r})"
+
+
+class CheckRegistry:
+    """Registry for managing and running all checks.
+
+    This class maintains a collection of all available checks and provides
+    methods to run them against AST nodes.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty check registry."""
+        self._checks: list[BaseCheck] = []
+
+    def register(self, check: BaseCheck) -> None:
+        """Register a check with the registry.
+
+        Args:
+            check: The check instance to register.
+        """
+        # Validate code uniqueness
+        for existing in self._checks:
+            if existing.code == check.code:
+                raise ValueError(f"Check with code {check.code!r} already registered")
+        self._checks.append(check)
+
+    def register_all(self, checks: list[BaseCheck]) -> None:
+        """Register multiple checks at once.
+
+        Args:
+            checks: List of check instances to register.
+        """
+        for check in checks:
+            self.register(check)
+
+    def get_check(self, code: str) -> BaseCheck | None:
+        """Get a check by its code.
+
+        Args:
+            code: The check code to look up.
+
+        Returns:
+            The check instance if found, None otherwise.
+        """
+        for check in self._checks:
+            if check.code == code:
+                return check
+        return None
+
+    @property
+    def checks(self) -> list[BaseCheck]:
+        """Return all registered checks."""
+        return self._checks.copy()
+
+    @property
+    def codes(self) -> list[str]:
+        """Return codes of all registered checks."""
+        return [check.code for check in self._checks]
+
+    def run_check(self, code: str, node: Node, context: AnalysisContext) -> Diagnostic | None:
+        """Run a specific check against a node.
+
+        Args:
+            code: The code of the check to run.
+            node: The AST node to check.
+            context: Analysis context.
+
+        Returns:
+            The diagnostic if found, None otherwise.
+        """
+        check = self.get_check(code)
+        if check is None:
+            raise ValueError(f"Unknown check code: {code!r}")
+        return check.check(node, context)
+
+    def run_all(
+        self,
+        node: Node,
+        context: AnalysisContext,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+    ) -> list[Diagnostic]:
+        """Run all applicable checks against a node.
+
+        Args:
+            node: The AST node to check.
+            context: Analysis context.
+            include: Optional list of check codes to run (if None, run all).
+            exclude: Optional list of check codes to skip.
+
+        Returns:
+            List of diagnostics found by any check.
+        """
+        results: list[Diagnostic] = []
+        exclude_set = set(exclude or [])
+
+        for check in self._checks:
+            # Skip if not in include list (when specified)
+            if include is not None and check.code not in include:
+                continue
+            # Skip if in exclude list
+            if check.code in exclude_set:
+                continue
+
+            if diagnostic := check.check(node, context):
+                results.append(diagnostic)
+
+        return results
+
+
+# Global registry instance
+_registry: CheckRegistry | None = None
+
+
+def get_registry() -> CheckRegistry:
+    """Get the global check registry, creating it if necessary."""
+    global _registry
+    if _registry is None:
+        _registry = CheckRegistry()
+    return _registry
+
+
+def reset_registry() -> None:
+    """Reset the global registry (mainly for testing)."""
+    global _registry
+    _registry = CheckRegistry()

zshcheck/checks/commands.py

@@ -0,0 +1,179 @@
+"""Command usage checks for zshcheck.
+
+This module contains checks for deprecated commands, unsafe command usage,
+and command-specific issues.
+"""
+
+from __future__ import annotations
+
+from tree_sitter import Node
+
+from zshcheck.checks.base import AnalysisContext, BaseCheck
+from zshcheck.diagnostics import Diagnostic, Severity
+from zshcheck.parser import get_node_text, node_to_range
+
+
+class DeprecatedCommandCheck(BaseCheck):
+    """Check for deprecated or obsolete commands."""
+
+    # Map of deprecated commands to their replacements
+    DEPRECATED_COMMANDS: dict[str, tuple[str, str]] = {
+        "which": ("command -v or type", "'which' is non-standard and not portable"),
+        "whereis": ("command -v or type", "'whereis' is not portable"),
+        "finger": ("other user lookup methods", "'finger' is outdated and often unavailable"),
+        "mail": ("sendmail or modern mail clients", "'mail' command is deprecated"),
+        "uudecode": ("base64", "'uudecode' is obsolete, use base64"),
+        "uuencode": ("base64", "'uuencode' is obsolete, use base64"),
+    }
+
+    @property
+    def code(self) -> str:
+        return "ZC4001"
+
+    @property
+    def description(self) -> str:
+        return "Deprecated or obsolete command used"
+
+    @property
+    def severity(self) -> Severity:
+        return Severity.WARNING
+
+    def check(self, node: Node, context: AnalysisContext) -> Diagnostic | None:
+        # Look for command names
+        if node.type not in ("command_name", "command"):
+            return None
+
+        # Get command text
+        cmd_text = get_node_text(node, context.source)
+
+        # Strip any path prefix to get the base command
+        base_cmd = cmd_text.split("/")[-1]
+
+        if base_cmd in self.DEPRECATED_COMMANDS:
+            replacement, reason = self.DEPRECATED_COMMANDS[base_cmd]
+            node_range = node_to_range(node)
+            source_line = self._get_source_line(node, context.source)
+
+            return Diagnostic(
+                code=self.code,
+                severity=self.severity,
+                message=f"{reason}. Consider using '{replacement}' instead.",
+                range=node_range,
+                source=source_line,
+            )
+
+        return None
+
+    def _get_source_line(self, node: Node, source: str) -> str | None:
+        """Get the source line containing this node."""
+        lines = source.split("\n")
+        line_idx = node.start_point.row
+        if 0 <= line_idx < len(lines):
+            return lines[line_idx]
+        return None
+
+
+class BacktickCheck(BaseCheck):
+    """Check for use of backticks instead of $()."""
+
+    @property
+    def code(self) -> str:
+        return "ZC4002"
+
+    @property
+    def description(self) -> str:
+        return "Use $() instead of backticks for command substitution"
+
+    @property
+    def severity(self) -> Severity:
+        return Severity.STYLE
+
+    def check(self, node: Node, context: AnalysisContext) -> Diagnostic | None:
+        # Look for backtick command substitutions
+        # In tree-sitter-bash, these might be marked as "command_substitution"
+        # but we'd need to check the actual source text
+        if node.type != "command_substitution":
+            return None
+
+        # Check if it starts with backtick
+        node_text = get_node_text(node, context.source)
+        if node_text.startswith("`") and node_text.endswith("`"):
+            node_range = node_to_range(node)
+            source_line = self._get_source_line(node, context.source)
+
+            # Extract the inner command
+            inner = node_text[1:-1]
+            replacement = f"$({inner})"
+
+            from zshcheck.diagnostics import Fix, Replacement
+
+            fix = Fix(
+                message=f"Replace with {replacement}",
+                replacements=[Replacement(range=node_range, text=replacement)],
+            )
+
+            return Diagnostic(
+                code=self.code,
+                severity=self.severity,
+                message="Backticks are deprecated. Use $() for command substitution instead.",
+                range=node_range,
+                fix=fix,
+                source=source_line,
+            )
+
+        return None
+
+    def _get_source_line(self, node: Node, source: str) -> str | None:
+        """Get the source line containing this node."""
+        lines = source.split("\n")
+        line_idx = node.start_point.row
+        if 0 <= line_idx < len(lines):
+            return lines[line_idx]
+        return None
+
+
+class EchoWithEscapesCheck(BaseCheck):
+    """Check for potentially problematic echo with escape sequences."""
+
+    @property
+    def code(self) -> str:
+        return "ZC4003"
+
+    @property
+    def description(self) -> str:
+        return "echo with escape sequences may behave differently across systems"
+
+    @property
+    def severity(self) -> Severity:
+        return Severity.WARNING
+
+    def check(self, node: Node, context: AnalysisContext) -> Diagnostic | None:
+        # Look for echo commands with -e flag
+        if node.type != "command":
+            return None
+
+        # Get command text
+        node_text = get_node_text(node, context.source)
+
+        # Check if it's echo with -e flag
+        if node_text.startswith("echo -e") or node_text.startswith("echo -E"):
+            node_range = node_to_range(node)
+            source_line = self._get_source_line(node, context.source)
+
+            return Diagnostic(
+                code=self.code,
+                severity=self.severity,
+                message="echo with -e/-E flags is non-portable. Consider using printf instead.",
+                range=node_range,
+                source=source_line,
+            )
+
+        return None
+
+    def _get_source_line(self, node: Node, source: str) -> str | None:
+        """Get the source line containing this node."""
+        lines = source.split("\n")
+        line_idx = node.start_point.row
+        if 0 <= line_idx < len(lines):
+            return lines[line_idx]
+        return None