pureshellcheck 0.1.0__tar.gz

pureshellcheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adam2go
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pureshellcheck-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+prune tests
+prune tools
+prune .github

pureshellcheck-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: pureshellcheck
+Version: 0.1.0
+Summary: A pure Python reimplementation of ShellCheck's most common checks
+Author: adam2go
+License: MIT
+Project-URL: Homepage, https://github.com/adam2go/pureshellcheck
+Keywords: shellcheck,shell,bash,lint,static-analysis,pure-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pureshellcheck
+
+[![CI](https://github.com/adam2go/pureshellcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/adam2go/pureshellcheck/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pureshellcheck)](https://pypi.org/project/pureshellcheck/)
+[![Conformance](https://img.shields.io/badge/ShellCheck%20test%20suite-619%2F620%20(99.8%25)-brightgreen)](tests/data/expected_failures.txt)
+
+A pure Python reimplementation of [ShellCheck](https://github.com/koalaman/shellcheck)'s
+most common checks. No binaries, no Haskell runtime, no compilation —
+`pip install pureshellcheck` and it works anywhere Python runs, including
+AWS Lambda, Pyodide/WASM, and locked-down CI sandboxes where you can't
+install the real ShellCheck binary.
+
+```console
+$ pip install pureshellcheck
+$ pureshellcheck deploy.sh
+
+In deploy.sh line 8:
+rm -rf $BUILD_DIR/*
+       ^--------^ SC2086 (info): Double quote to prevent globbing and word splitting.
+```
+
+## Why
+
+- **Agent & tooling friendly.** LLM-generated shell scripts fail in
+  exactly the ways ShellCheck catches (unquoted expansions, word
+  splitting, `cd` without `|| exit`). Existing Python packages such as
+  `shellcheck-py` just download the 30 MB Haskell binary — useless in
+  WASM, Lambda layers, or hermetic build sandboxes. pureshellcheck is
+  ~7000 lines of stdlib-only Python.
+- **In-process speed.** Calling `pureshellcheck.check()` takes ~2 ms for a
+  typical script vs ~40 ms to spawn the shellcheck binary — and it's
+  8–13× faster than the binary even on 1200-line scripts (see
+  [Benchmarks](#benchmarks)).
+- **Verified against the real thing.** Test cases are extracted from
+  ShellCheck's own test suite and the output is differentially tested
+  against the shellcheck binary on real-world scripts.
+
+## What it checks
+
+71 SC codes are implemented, chosen by real-world frequency — the quoting
+and word-splitting family (SC2086, SC2046, SC2068, SC2206/2207...),
+variable lifecycle (SC2034 unused, SC2154 unassigned, SC2155),
+command pitfalls (SC2164 unchecked `cd`, SC2162 `read` without `-r`,
+useless `cat`/`echo`, `ls | grep`, `find | xargs`, printf argument
+counting, catastrophic `rm -rf`), structural mistakes
+(`A && B || C`, constant test expressions, `$?` anti-patterns), and more.
+
+<details>
+<summary>All implemented codes</summary>
+
+SC2002 SC2003 SC2004 SC2005 SC2006 SC2007 SC2009 SC2010 SC2011 SC2012
+SC2015 SC2016 SC2026 SC2027 SC2028 SC2034 SC2035 SC2038 SC2041 SC2042
+SC2043 SC2046 SC2048 SC2050 SC2059 SC2064 SC2065 SC2066 SC2068 SC2086
+SC2089 SC2090 SC2093 SC2094 SC2103 SC2114 SC2115 SC2116 SC2126 SC2128
+SC2140 SC2145 SC2148 SC2153 SC2154 SC2155 SC2162 SC2164 SC2174 SC2178
+SC2179 SC2181 SC2182 SC2183 SC2187 SC2188 SC2189 SC2206 SC2207 SC2223
+SC2239 SC2246 SC2248 SC2250 SC2258 SC2304 SC2305 SC2306 SC2307 SC2308
+
+</details>
+
+## Conformance scoreboard
+
+The repository vendors **1508 test cases extracted from ShellCheck's own
+test suite** (`tests/data/corpus.json`), run by pytest on every commit:
+
+| metric | result |
+|---|---|
+| official test cases for the implemented checks | **619/620 (99.8%)** |
+| whole official corpus (incl. unimplemented checks) | 1025/1508 (68.0%) |
+| real-world differential test vs `shellcheck` 0.11.0 | **113/113 findings agree, 0 missed, 0 false positives** (48 scripts from Homebrew/npm) |
+
+The single implemented-check failure is documented in
+`tests/data/expected_failures.txt` (a test of ShellCheck's non-default
+`check-unassigned-uppercase` mode); every other non-passing corpus case is
+listed there with a reason. Reproduce with:
+
+```console
+$ python tools/conformance.py                  # scoreboard
+$ python tools/diff_shellcheck.py *.sh         # vs the real binary
+```
+
+## Usage
+
+### CLI
+
+```console
+$ pureshellcheck [-s bash] [-f tty|gcc|json|json1] [-e SC2086] \
+                 [-S error|warning|info|style] script.sh [more.sh ...]
+```
+
+Exit status is 0 for a clean script, 1 if there are findings, 2 on file
+errors — same convention as shellcheck. `# shellcheck disable=SC2086`
+and `# shellcheck shell=dash` directives are honored.
+
+### Library
+
+```python
+import pureshellcheck
+
+for f in pureshellcheck.check('echo $foo', shell='bash'):
+    print(f.line, f.column, f.code, f.severity, f.message)
+# 1 6 2086 info Double quote to prevent globbing and word splitting.
+```
+
+`check()` returns a list of findings with `code`, `severity`
+(`error|warning|info|style`), `message`, and 1-based
+`line`/`column`/`end_line`/`end_column`. `pureshellcheck.parse()` exposes
+the bash AST if you want to build your own analyses.
+
+## Benchmarks
+
+Measured with `python tools/bench.py` (median of 7 runs, after verifying
+both tools report identical findings on the workload; CPython 3.12,
+shellcheck 0.11.0, Apple Silicon):
+
+| workload | shellcheck | pureshellcheck | speedup |
+|---|---|---|---|
+| CLI, brew.sh (1216 lines) | 604 ms | 68 ms | **8.9×** |
+| embedded `check()`, brew.sh | 604 ms | 45 ms | **13.3×** |
+| CLI, 75-line script | 42 ms | 24 ms | 1.8× |
+| embedded `check()`, 75-line script | 42 ms | 2.4 ms | **17×** |
+
+The embedded rows are what an agent or editor integration pays per call:
+no process spawn, no binary.
+
+## Compatibility notes
+
+- Targets bash (default), sh/dash/ash and ksh dialects are accepted via
+  shebang, directive, or `-s`; sh-specific portability checks (the
+  SC2039/SC3xxx family) are not implemented yet.
+- The parser is deliberately lenient: it keeps checking past constructs
+  the real shellcheck refuses to parse (e.g. `[ $tar --version ]`).
+- Optional checks (`SC2002`, `SC2248`, `SC2250`) are off by default,
+  matching shellcheck 0.11; enable with `-o` / `include_optional=True`.
+- Wiki links work the same: see <https://www.shellcheck.net/wiki/SC2086>
+  for any reported code.
+
+## Development
+
+```console
+$ pip install -e . pytest
+$ pytest                                # corpus + unit tests, < 1 s
+$ python tools/extract_corpus.py /path/to/shellcheck   # refresh corpus
+$ python tools/update_expected_failures.py             # refresh scoreboard
+$ python tools/bench.py                                # benchmarks
+```
+
+The package itself is MIT licensed and has zero runtime dependencies
+(CPython 3.9–3.14 and PyPy). The vendored test corpus in `tests/data/` is
+extracted from the GPLv3-licensed ShellCheck project and is used only for
+development-time testing; it is not part of the distributed wheel.
+
+## See also
+
+- [purejq](https://github.com/adam2go/purejq) — pure Python jq, same
+  philosophy: vendored official test suite, differential testing, no
+  binaries.

pureshellcheck-0.1.0/README.md

@@ -0,0 +1,157 @@
+# pureshellcheck
+
+[![CI](https://github.com/adam2go/pureshellcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/adam2go/pureshellcheck/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pureshellcheck)](https://pypi.org/project/pureshellcheck/)
+[![Conformance](https://img.shields.io/badge/ShellCheck%20test%20suite-619%2F620%20(99.8%25)-brightgreen)](tests/data/expected_failures.txt)
+
+A pure Python reimplementation of [ShellCheck](https://github.com/koalaman/shellcheck)'s
+most common checks. No binaries, no Haskell runtime, no compilation —
+`pip install pureshellcheck` and it works anywhere Python runs, including
+AWS Lambda, Pyodide/WASM, and locked-down CI sandboxes where you can't
+install the real ShellCheck binary.
+
+```console
+$ pip install pureshellcheck
+$ pureshellcheck deploy.sh
+
+In deploy.sh line 8:
+rm -rf $BUILD_DIR/*
+       ^--------^ SC2086 (info): Double quote to prevent globbing and word splitting.
+```
+
+## Why
+
+- **Agent & tooling friendly.** LLM-generated shell scripts fail in
+  exactly the ways ShellCheck catches (unquoted expansions, word
+  splitting, `cd` without `|| exit`). Existing Python packages such as
+  `shellcheck-py` just download the 30 MB Haskell binary — useless in
+  WASM, Lambda layers, or hermetic build sandboxes. pureshellcheck is
+  ~7000 lines of stdlib-only Python.
+- **In-process speed.** Calling `pureshellcheck.check()` takes ~2 ms for a
+  typical script vs ~40 ms to spawn the shellcheck binary — and it's
+  8–13× faster than the binary even on 1200-line scripts (see
+  [Benchmarks](#benchmarks)).
+- **Verified against the real thing.** Test cases are extracted from
+  ShellCheck's own test suite and the output is differentially tested
+  against the shellcheck binary on real-world scripts.
+
+## What it checks
+
+71 SC codes are implemented, chosen by real-world frequency — the quoting
+and word-splitting family (SC2086, SC2046, SC2068, SC2206/2207...),
+variable lifecycle (SC2034 unused, SC2154 unassigned, SC2155),
+command pitfalls (SC2164 unchecked `cd`, SC2162 `read` without `-r`,
+useless `cat`/`echo`, `ls | grep`, `find | xargs`, printf argument
+counting, catastrophic `rm -rf`), structural mistakes
+(`A && B || C`, constant test expressions, `$?` anti-patterns), and more.
+
+<details>
+<summary>All implemented codes</summary>
+
+SC2002 SC2003 SC2004 SC2005 SC2006 SC2007 SC2009 SC2010 SC2011 SC2012
+SC2015 SC2016 SC2026 SC2027 SC2028 SC2034 SC2035 SC2038 SC2041 SC2042
+SC2043 SC2046 SC2048 SC2050 SC2059 SC2064 SC2065 SC2066 SC2068 SC2086
+SC2089 SC2090 SC2093 SC2094 SC2103 SC2114 SC2115 SC2116 SC2126 SC2128
+SC2140 SC2145 SC2148 SC2153 SC2154 SC2155 SC2162 SC2164 SC2174 SC2178
+SC2179 SC2181 SC2182 SC2183 SC2187 SC2188 SC2189 SC2206 SC2207 SC2223
+SC2239 SC2246 SC2248 SC2250 SC2258 SC2304 SC2305 SC2306 SC2307 SC2308
+
+</details>
+
+## Conformance scoreboard
+
+The repository vendors **1508 test cases extracted from ShellCheck's own
+test suite** (`tests/data/corpus.json`), run by pytest on every commit:
+
+| metric | result |
+|---|---|
+| official test cases for the implemented checks | **619/620 (99.8%)** |
+| whole official corpus (incl. unimplemented checks) | 1025/1508 (68.0%) |
+| real-world differential test vs `shellcheck` 0.11.0 | **113/113 findings agree, 0 missed, 0 false positives** (48 scripts from Homebrew/npm) |
+
+The single implemented-check failure is documented in
+`tests/data/expected_failures.txt` (a test of ShellCheck's non-default
+`check-unassigned-uppercase` mode); every other non-passing corpus case is
+listed there with a reason. Reproduce with:
+
+```console
+$ python tools/conformance.py                  # scoreboard
+$ python tools/diff_shellcheck.py *.sh         # vs the real binary
+```
+
+## Usage
+
+### CLI
+
+```console
+$ pureshellcheck [-s bash] [-f tty|gcc|json|json1] [-e SC2086] \
+                 [-S error|warning|info|style] script.sh [more.sh ...]
+```
+
+Exit status is 0 for a clean script, 1 if there are findings, 2 on file
+errors — same convention as shellcheck. `# shellcheck disable=SC2086`
+and `# shellcheck shell=dash` directives are honored.
+
+### Library
+
+```python
+import pureshellcheck
+
+for f in pureshellcheck.check('echo $foo', shell='bash'):
+    print(f.line, f.column, f.code, f.severity, f.message)
+# 1 6 2086 info Double quote to prevent globbing and word splitting.
+```
+
+`check()` returns a list of findings with `code`, `severity`
+(`error|warning|info|style`), `message`, and 1-based
+`line`/`column`/`end_line`/`end_column`. `pureshellcheck.parse()` exposes
+the bash AST if you want to build your own analyses.
+
+## Benchmarks
+
+Measured with `python tools/bench.py` (median of 7 runs, after verifying
+both tools report identical findings on the workload; CPython 3.12,
+shellcheck 0.11.0, Apple Silicon):
+
+| workload | shellcheck | pureshellcheck | speedup |
+|---|---|---|---|
+| CLI, brew.sh (1216 lines) | 604 ms | 68 ms | **8.9×** |
+| embedded `check()`, brew.sh | 604 ms | 45 ms | **13.3×** |
+| CLI, 75-line script | 42 ms | 24 ms | 1.8× |
+| embedded `check()`, 75-line script | 42 ms | 2.4 ms | **17×** |
+
+The embedded rows are what an agent or editor integration pays per call:
+no process spawn, no binary.
+
+## Compatibility notes
+
+- Targets bash (default), sh/dash/ash and ksh dialects are accepted via
+  shebang, directive, or `-s`; sh-specific portability checks (the
+  SC2039/SC3xxx family) are not implemented yet.
+- The parser is deliberately lenient: it keeps checking past constructs
+  the real shellcheck refuses to parse (e.g. `[ $tar --version ]`).
+- Optional checks (`SC2002`, `SC2248`, `SC2250`) are off by default,
+  matching shellcheck 0.11; enable with `-o` / `include_optional=True`.
+- Wiki links work the same: see <https://www.shellcheck.net/wiki/SC2086>
+  for any reported code.
+
+## Development
+
+```console
+$ pip install -e . pytest
+$ pytest                                # corpus + unit tests, < 1 s
+$ python tools/extract_corpus.py /path/to/shellcheck   # refresh corpus
+$ python tools/update_expected_failures.py             # refresh scoreboard
+$ python tools/bench.py                                # benchmarks
+```
+
+The package itself is MIT licensed and has zero runtime dependencies
+(CPython 3.9–3.14 and PyPy). The vendored test corpus in `tests/data/` is
+extracted from the GPLv3-licensed ShellCheck project and is used only for
+development-time testing; it is not part of the distributed wheel.
+
+## See also
+
+- [purejq](https://github.com/adam2go/purejq) — pure Python jq, same
+  philosophy: vendored official test suite, differential testing, no
+  binaries.

pureshellcheck-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pureshellcheck"
+version = "0.1.0"
+description = "A pure Python reimplementation of ShellCheck's most common checks"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "adam2go" }]
+keywords = ["shellcheck", "shell", "bash", "lint", "static-analysis", "pure-python"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/adam2go/pureshellcheck"
+
+[project.scripts]
+pureshellcheck = "pureshellcheck.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pureshellcheck-0.1.0/setup.cfg

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

pureshellcheck-0.1.0/src/pureshellcheck/__init__.py

@@ -0,0 +1,58 @@
+"""pureshellcheck: a pure Python reimplementation of ShellCheck's most
+common checks.
+
+>>> import pureshellcheck
+>>> for finding in pureshellcheck.check('echo $foo'):
+...     print(finding.line, finding.column, finding.code, finding.message)
+"""
+
+__version__ = "0.1.0"
+
+from .analyzer import Finding, run_checks  # noqa: F401
+from .parser import ParseError, parse  # noqa: F401
+from . import checks  # noqa: F401  (registers all checks)
+
+
+def check(source, shell=None, include_optional=False):
+    """Analyze a shell script and return a list of Finding objects.
+
+    `shell` overrides shebang detection ("bash", "sh", "dash", "ksh").
+    Findings have: code (int), severity, message, line, column, end_line,
+    end_column.
+    """
+    findings, _ = run_checks(source, shell=shell,
+                             include_optional=include_optional)
+    return findings
+
+
+def implemented_codes():
+    """The set of SC codes this version can emit."""
+    from .analyzer import NODE_CHECKS, TREE_CHECKS  # noqa: F401
+    return set(_IMPLEMENTED)
+
+
+# maintained by hand; verified by tests/test_implemented.py
+_IMPLEMENTED = set()
+
+
+def _register_codes(*codes):
+    _IMPLEMENTED.update(codes)
+
+
+_register_codes(
+    1073,  # parse errors
+    2006, 2016, 2026, 2027, 2041, 2042, 2043, 2046, 2048, 2066, 2068,
+    2086, 2089, 2090, 2140, 2145, 2206, 2207, 2223, 2248, 2250, 2258,
+)
+_register_codes(
+    2002, 2003, 2005, 2009, 2010, 2011, 2012, 2015, 2038, 2050, 2059,
+    2064, 2065, 2114, 2115, 2116, 2126, 2148, 2162, 2164, 2174, 2181,
+    2182, 2183, 2187, 2188, 2189, 2239, 2246, 2304, 2305,
+    2306, 2307, 2308,
+)
+_register_codes(
+    2004, 2034, 2128, 2153, 2154, 2155, 2178, 2179,
+)
+_register_codes(
+    2007, 2028, 2035, 2093, 2094, 2103,
+)