zshshellcheck 0.2.1__tar.gz

zshshellcheck-0.2.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: zshshellcheck
+Version: 0.2.1
+Summary: A static analysis tool for zsh shell scripts
+Author-email: Rodrigo <rodregoc@gmail.com>
+License: MIT
+Project-URL: Homepage, https://rodrigo.is-a.dev/zshellcheck/
+Project-URL: Repository, https://github.com/rodrigocnascimento/zshshellcheck
+Project-URL: Issues, https://github.com/rodrigocnascimento/zshshellcheck/issues
+Keywords: zsh,shell,lint,static-analysis,script
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: tree-sitter>=0.20.0
+Requires-Dist: tree-sitter-zsh>=0.60.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+
+<h1 align="center">ZshCheck</h1>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rodrigocnascimento/zshellcheck/main/documentation/assets/header-image.png" alt="ZshCheck - Static Analysis for Zsh" width="600"/>
+</p>
+
+Uma ferramenta de análise estática para scripts zsh, construída com Python 3.12+.
+
+## Funcionalidades
+
+- **Parser Tree-sitter**: Análise AST precisa usando gramática tree-sitter-zsh
+- **Checks Plugin-based**: Sistema de verificação extensível com padrão registry
+- **CLI Rico**: Saída formatada com tabela, JSON e formatos compactos
+- **Múltiplos Formatos de Saída**: Table, JSON e compacto
+- **Auto-Fix**: Corrige automaticamente problemas detectáveis (--fix flag)
+- **Suporte a Unicode**: Aceita emojis e caracteres não-ASCII em comentários
+
+## Instalação
+
+```bash
+pip install zshshellcheck
+```
+
+## Início Rápido
+
+```bash
+# Analisar um script
+zshcheck script.zsh
+
+# Analisar múltiplos arquivos
+zshcheck *.zsh
+
+# Listar checks disponíveis
+zshcheck --list-checks
+
+# Filtrar por código de check
+zshcheck --include ZC1001 --include ZC2001
+
+# Saída em JSON
+zshcheck --format json script.zsh
+
+# Auto-fixar problemas (pergunta para cada fix)
+zshcheck script.zsh --fix
+
+# Ou usando a flag curta
+zshcheck script.zsh -F
+```
+
+## Documentação
+
+A documentação completa está disponível em: [https://developer.github.io/zshshellcheck/](https://developer.github.io/zshshellcheck/)
+
+## Limitações Conhecidas
+
+### Emojis e Unicode em scripts zsh
+
+O parser `tree-sitter-zsh` pode apresentar problemas com caracteres unicode em identificadores (nomes de variáveis, funções). Esses caracteres agora são detectados como INFO (ZC9004) em vez de erro, para que você possa decidir se quer ajustar.
+
+**Exemplo de warning**:
+```
+INFO  ZC9004  Non-ASCII characters detected (2 found). Found: 'ã' 'é'
+```
+
+Isso aparece como INFO (não blockea a análise) e indica quais caracteres foram encontrados.
+
+### Sintaxe zsh avançada
+
+Algumas sintaxes zsh avançadas (como parâmetros de glob qualifiers `${(k)functions}`) podem não ser suportadas pelo parser. Recomendamos usar a flag acima para scripts que contenham dessas expressões.
+
+## Desenvolvimento
+
+```bash
+# Executar testes
+pytest -v
+
+# Executar linting
+ruff check .
+
+# Executar type checking
+mypy .
+
+# Verificação completa
+ruff check . && mypy . && pytest
+```
+
+## Licença
+
+MIT

zshshellcheck-0.2.1/README.md

@@ -0,0 +1,88 @@
+<h1 align="center">ZshCheck</h1>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rodrigocnascimento/zshellcheck/main/documentation/assets/header-image.png" alt="ZshCheck - Static Analysis for Zsh" width="600"/>
+</p>
+
+Uma ferramenta de análise estática para scripts zsh, construída com Python 3.12+.
+
+## Funcionalidades
+
+- **Parser Tree-sitter**: Análise AST precisa usando gramática tree-sitter-zsh
+- **Checks Plugin-based**: Sistema de verificação extensível com padrão registry
+- **CLI Rico**: Saída formatada com tabela, JSON e formatos compactos
+- **Múltiplos Formatos de Saída**: Table, JSON e compacto
+- **Auto-Fix**: Corrige automaticamente problemas detectáveis (--fix flag)
+- **Suporte a Unicode**: Aceita emojis e caracteres não-ASCII em comentários
+
+## Instalação
+
+```bash
+pip install zshshellcheck
+```
+
+## Início Rápido
+
+```bash
+# Analisar um script
+zshcheck script.zsh
+
+# Analisar múltiplos arquivos
+zshcheck *.zsh
+
+# Listar checks disponíveis
+zshcheck --list-checks
+
+# Filtrar por código de check
+zshcheck --include ZC1001 --include ZC2001
+
+# Saída em JSON
+zshcheck --format json script.zsh
+
+# Auto-fixar problemas (pergunta para cada fix)
+zshcheck script.zsh --fix
+
+# Ou usando a flag curta
+zshcheck script.zsh -F
+```
+
+## Documentação
+
+A documentação completa está disponível em: [https://developer.github.io/zshshellcheck/](https://developer.github.io/zshshellcheck/)
+
+## Limitações Conhecidas
+
+### Emojis e Unicode em scripts zsh
+
+O parser `tree-sitter-zsh` pode apresentar problemas com caracteres unicode em identificadores (nomes de variáveis, funções). Esses caracteres agora são detectados como INFO (ZC9004) em vez de erro, para que você possa decidir se quer ajustar.
+
+**Exemplo de warning**:
+```
+INFO  ZC9004  Non-ASCII characters detected (2 found). Found: 'ã' 'é'
+```
+
+Isso aparece como INFO (não blockea a análise) e indica quais caracteres foram encontrados.
+
+### Sintaxe zsh avançada
+
+Algumas sintaxes zsh avançadas (como parâmetros de glob qualifiers `${(k)functions}`) podem não ser suportadas pelo parser. Recomendamos usar a flag acima para scripts que contenham dessas expressões.
+
+## Desenvolvimento
+
+```bash
+# Executar testes
+pytest -v
+
+# Executar linting
+ruff check .
+
+# Executar type checking
+mypy .
+
+# Verificação completa
+ruff check . && mypy . && pytest
+```
+
+## Licença
+
+MIT

zshshellcheck-0.2.1/pyproject.toml

@@ -0,0 +1,141 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zshshellcheck"
+version = "0.2.1"
+description = "A static analysis tool for zsh shell scripts"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Rodrigo", email = "rodregoc@gmail.com"}
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+keywords = ["zsh", "shell", "lint", "static-analysis", "script"]
+dependencies = [
+    "tree-sitter>=0.20.0",
+    "tree-sitter-zsh>=0.60.0",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-xdist>=3.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+    "pre-commit>=3.0.0",
+]
+
+[project.scripts]
+zshcheck = "zshcheck.cli:main"
+
+[project.urls]
+Homepage = "https://rodrigo.is-a.dev/zshellcheck/"
+Repository = "https://github.com/rodrigocnascimento/zshshellcheck"
+Issues = "https://github.com/rodrigocnascimento/zshshellcheck/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ruff configuration
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "D",   # pydocstyle
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "D100",  # Missing docstring in public module
+    "D104",  # Missing docstring in public package
+    "D107",  # Missing docstring in __init__
+]
+
+[tool.ruff.pydocstyle]
+convention = "google"
+
+[tool.ruff.per-file-ignores]
+"tests/*" = ["D", "S"]
+
+# Mypy configuration
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+strict_optional = true
+warn_no_return = true
+show_error_codes = true
+show_column_numbers = true
+
+# Pytest configuration
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+    "--cov=zshcheck",
+    "--cov-report=term-missing",
+    "--cov-report=html:htmlcov",
+    "--cov-report=xml:coverage.xml",
+    "--cov-fail-under=70",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+]
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["src/zshcheck"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"

zshshellcheck-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zshshellcheck-0.2.1/src/zshcheck/__init__.py

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

zshshellcheck-0.2.1/src/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)

zshshellcheck-0.2.1/src/zshcheck/checks/__init__.py

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