shrinkray 0.0.2__tar.gz → 25.12.26__tar.gz

shrinkray-25.12.26/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2023 David R. MacIver
+
+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.

shrinkray-25.12.26/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: shrinkray
+Version: 25.12.26
+Summary: Shrink Ray
+Author-email: "David R. MacIver" <david@drmaciver.com>
+License: MIT
+Project-URL: Homepage, https://github.com/DRMacIver/shrinkray
+Project-URL: Repository, https://github.com/DRMacIver/shrinkray
+Project-URL: Documentation, https://shrinkray.readthedocs.io
+Project-URL: Changelog, https://github.com/DRMacIver/shrinkray/releases
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.1
+Requires-Dist: chardet>=5.2.0
+Requires-Dist: trio>=0.28.0
+Requires-Dist: textual>=0.47.0
+Requires-Dist: humanize>=4.9.0
+Requires-Dist: libcst>=1.1.0
+Requires-Dist: exceptiongroup>=1.2.0
+Requires-Dist: binaryornot>=0.4.4
+Requires-Dist: black
+Provides-Extra: dev
+Requires-Dist: coverage>=7.13.0; extra == "dev"
+Requires-Dist: hypothesis>=6.92.1; extra == "dev"
+Requires-Dist: hypothesmith>=0.3.1; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-trio; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-textual-snapshot; extra == "dev"
+Requires-Dist: coverage[toml]; extra == "dev"
+Requires-Dist: pygments; extra == "dev"
+Requires-Dist: basedpyright; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pexpect>=4.9.0; extra == "dev"
+Requires-Dist: pyte>=0.8.2; extra == "dev"
+Dynamic: license-file
+
+# Shrink Ray
+
+Shrink Ray is a modern multiformat test-case reducer.
+
+## What is test-case reduction?
+
+Test-case reduction is the process of automatically taking a *test case* and *reducing* it to something close to a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example).
+
+That is, you have some file that has some interesting property (usually that it triggers a bug in some software),
+but it is large and complicated and as a result you can't figure out what about the file actually matters.
+You want to be able to trigger the bug with a small, simple, version of it that contains only the features of interest.
+
+For example, the following is some Python code that [triggered a bug in libcst](https://github.com/Instagram/LibCST/issues/1061):
+
+```python
+() if 0 else(lambda:())
+```
+
+This was extracted from a large Python file (probably several thousand lines of code) and systematically reduced down to this example.
+
+You would obtain this by running `shrinkray breakslibcst.py mytestcase.py`, where `breakslibcst.py` looks something like this:
+
+```python
+import libcst
+import sys
+
+if __name__  == '__main__':
+    try:
+        libcst.parse_module(sys.stdin.read())
+    except TypeError:
+        sys.exit(0)
+    sys.exit(1)
+```
+
+This script exits with 0 if the code passed to it on standard input triggers the relevant bug (that libcst raises a TypeError when parsing this code), and with a non-zero exit code otherwise.
+
+shrinkray (or any other test-case reducer) then systematically tries smaller and simpler variants of your original source file until it reduces it to something as small as it can manage.
+
+While it runs, you will see the following user interface:
+
+![Demo of shrink ray running](demo.png)
+
+When it finishes you will be left with the reduced test case in `mytestcase.py`.
+
+Test-case reducers are useful for any tools that handle files with complex formats that can trigger bugs in them. Historically this has been particularly useful for compilers and other programming tools, but in principle it can be used for anything.
+
+Most test-case reducers only work well on a few formats. Shrink Ray is designed to be able to support a wide variety of formats, including binary ones, although it's currently best tuned for "things that look like programming languages".
+
+## What makes Shrink Ray distinctive?
+
+It's designed to be highly parallel, and work with a very wide variety of formats, through a mix of good generic algorithms and format-specific reduction passes.
+
+Currently shrink ray is a "prerelease" version in the sense that there is no official release yet and you're expected to just run off main (don't worry this is easy to do), as it's a bit experimental.
+
+That being said this probably doesn't matter that much for the question of whether to use it. It's in the nature of test-case reduction that it doesn't matter all that much if it's bad, because it's still going to do a bunch of work that you didn't have to do by hand. Try it out, see if it works. If it doesn't, please tell me and I'll make it work better.
+
+## Installation
+
+Shrink Ray requires Python 3.11 or later, and can be installed using pip.
+
+Official releases for shrink ray are infrequent, and I recommend running off main. You can install it as follows:
+
+```
+pipx install shrinkray
+# or
+pipx install git+https://github.com/DRMacIver/shrinkray.git
+```
+
+(if you don't have or want [pipx](https://pypa.github.io/pipx/) you could also do this with pip or `uv pip` and it would work fine)
+
+Shrink Ray requires Python 3.11 or later and won't work on earlier versions. If everything is working correctly, it should refuse to install
+on versions it's incompatible with. If you do not have Python 3.11 installed, I recommend [pyenv](https://github.com/pyenv/pyenv) for managing
+Python installs.
+
+If you want to use it from the git repo directly, you can do the following:
+
+```
+git clone https://github.com/DRMacIver/shrinkray.git
+cd shrinkray
+python -m venv .venv
+.venv/bin/pip install -e .
+```
+
+You will now have a shrinkray executable in .venv/bin, which you can also put on your path by running `source .venv/bin/activate`.
+
+## Usage
+
+Shrink Ray is run as follows:
+
+```
+shrinkray is_interesting.sh my-test-case
+```
+
+Where `my-test-case` is some file you want to reduce and `is_interesting.sh` can be any executable that exits with `0` when a test case passed to it is interesting and non-zero otherwise.
+
+Variant test cases are passed to the interestingness test both on STDIN and as a file name passed as an argument. Additionally for creduce compatibility, the file has the same base name as the original test case and is in the current working directory the script is run with. This behaviour can be customised with the `--input-type` argument.
+
+`shrinkray --help` will give more usage instructions.
+
+## Supported formats
+
+Shrink Ray is fully generic in the sense that it will work with literally any file you give it in any format. However, some formats will work a lot better than others.
+
+It has a generic reduction algorithm that should work pretty well with any textual format, and an architecture that is designed to make it easy to add specialised support for specific formats as needed.
+
+Additionally, Shrink Ray has special support for the following formats:
+
+* C and C++ (via `clang_delta`, which you will have if creduce is installed)
+* Python
+* JSON
+* Dimacs CNF format for SAT problems
+
+Most of this support is quite basic and is just designed to deal with specific cases that the generic logic is known
+not to handle well, but it's easy to extend with additional transformations.
+It is also fairly easy to add support for new formats as needed.
+
+If you run into a test case and interestingness test that you care about that shrink ray handles badly please let me know and I'll likely see about improving its handling of that format.
+
+## Parallelism
+
+You can control the number of parallel tasks shrinkray will run with the `--parallelism` flag. By default this will be the number of CPU cores you have available
+
+Shrink Ray is designed to be able to run heavily in parallel, with a basic heuristic of aiming to be embarrassingly parallel when making no progress, mostly sequential when making progress, and smoothly scaling in between the two. It mostly succeeds at this.
+
+Currently the bottleneck on scaling to a very large number of cores is how fast the controlling Python program can generate variant test cases to try and pass them to the interestingness test. This isn't well optimised at present and I don't currently have good benchmarks for it, but I'd expect you to be able to get linear speedups on most workflows while running 10-20 test cases in parallel, and to start to struggle past that.
+
+This also depends on the performance of the interestingness test - the slower your test is to run, the more you'll be able to scale linearly with the number of cores available.
+
+I'm quite interested in getting this part to scale well, so please let me know if you find examples where it doesn't seem to work.
+
+## Bug Reports
+
+Shrink Ray is still pretty new and under-tested software, so it definitely has bugs. If you run into any, [please file an issue](https://github.com/DRMacIver/shrinkray/issues).
+
+As well as obvious bugs (crashes, etc) I'm also very interested in hearing about usability issues and cases where the reduced test case isn't very good.
+
+Requests for new features, new supported formats, etc. also welcome although I'm less likely to jump right on them.
+
+## Sponsorship
+
+Shrink Ray is something of a labour of love - I wanted to have a tool that actually put into practice many of my ideas about test-case reduction, as I think the previous state of the art was well behind where I'd like it to be.
+
+That being said, it is first and foremost designed to be a useful tool for practical engineering problems.
+If you find it useful as such, please [consider sponsoring my development of it](https://github.com/sponsors/DRMacIver).

shrinkray-25.12.26/README.md

@@ -0,0 +1,144 @@
+# Shrink Ray
+
+Shrink Ray is a modern multiformat test-case reducer.
+
+## What is test-case reduction?
+
+Test-case reduction is the process of automatically taking a *test case* and *reducing* it to something close to a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example).
+
+That is, you have some file that has some interesting property (usually that it triggers a bug in some software),
+but it is large and complicated and as a result you can't figure out what about the file actually matters.
+You want to be able to trigger the bug with a small, simple, version of it that contains only the features of interest.
+
+For example, the following is some Python code that [triggered a bug in libcst](https://github.com/Instagram/LibCST/issues/1061):
+
+```python
+() if 0 else(lambda:())
+```
+
+This was extracted from a large Python file (probably several thousand lines of code) and systematically reduced down to this example.
+
+You would obtain this by running `shrinkray breakslibcst.py mytestcase.py`, where `breakslibcst.py` looks something like this:
+
+```python
+import libcst
+import sys
+
+if __name__  == '__main__':
+    try:
+        libcst.parse_module(sys.stdin.read())
+    except TypeError:
+        sys.exit(0)
+    sys.exit(1)
+```
+
+This script exits with 0 if the code passed to it on standard input triggers the relevant bug (that libcst raises a TypeError when parsing this code), and with a non-zero exit code otherwise.
+
+shrinkray (or any other test-case reducer) then systematically tries smaller and simpler variants of your original source file until it reduces it to something as small as it can manage.
+
+While it runs, you will see the following user interface:
+
+![Demo of shrink ray running](demo.png)
+
+When it finishes you will be left with the reduced test case in `mytestcase.py`.
+
+Test-case reducers are useful for any tools that handle files with complex formats that can trigger bugs in them. Historically this has been particularly useful for compilers and other programming tools, but in principle it can be used for anything.
+
+Most test-case reducers only work well on a few formats. Shrink Ray is designed to be able to support a wide variety of formats, including binary ones, although it's currently best tuned for "things that look like programming languages".
+
+## What makes Shrink Ray distinctive?
+
+It's designed to be highly parallel, and work with a very wide variety of formats, through a mix of good generic algorithms and format-specific reduction passes.
+
+Currently shrink ray is a "prerelease" version in the sense that there is no official release yet and you're expected to just run off main (don't worry this is easy to do), as it's a bit experimental.
+
+That being said this probably doesn't matter that much for the question of whether to use it. It's in the nature of test-case reduction that it doesn't matter all that much if it's bad, because it's still going to do a bunch of work that you didn't have to do by hand. Try it out, see if it works. If it doesn't, please tell me and I'll make it work better.
+
+## Installation
+
+Shrink Ray requires Python 3.11 or later, and can be installed using pip.
+
+Official releases for shrink ray are infrequent, and I recommend running off main. You can install it as follows:
+
+```
+pipx install shrinkray
+# or
+pipx install git+https://github.com/DRMacIver/shrinkray.git
+```
+
+(if you don't have or want [pipx](https://pypa.github.io/pipx/) you could also do this with pip or `uv pip` and it would work fine)
+
+Shrink Ray requires Python 3.11 or later and won't work on earlier versions. If everything is working correctly, it should refuse to install
+on versions it's incompatible with. If you do not have Python 3.11 installed, I recommend [pyenv](https://github.com/pyenv/pyenv) for managing
+Python installs.
+
+If you want to use it from the git repo directly, you can do the following:
+
+```
+git clone https://github.com/DRMacIver/shrinkray.git
+cd shrinkray
+python -m venv .venv
+.venv/bin/pip install -e .
+```
+
+You will now have a shrinkray executable in .venv/bin, which you can also put on your path by running `source .venv/bin/activate`.
+
+## Usage
+
+Shrink Ray is run as follows:
+
+```
+shrinkray is_interesting.sh my-test-case
+```
+
+Where `my-test-case` is some file you want to reduce and `is_interesting.sh` can be any executable that exits with `0` when a test case passed to it is interesting and non-zero otherwise.
+
+Variant test cases are passed to the interestingness test both on STDIN and as a file name passed as an argument. Additionally for creduce compatibility, the file has the same base name as the original test case and is in the current working directory the script is run with. This behaviour can be customised with the `--input-type` argument.
+
+`shrinkray --help` will give more usage instructions.
+
+## Supported formats
+
+Shrink Ray is fully generic in the sense that it will work with literally any file you give it in any format. However, some formats will work a lot better than others.
+
+It has a generic reduction algorithm that should work pretty well with any textual format, and an architecture that is designed to make it easy to add specialised support for specific formats as needed.
+
+Additionally, Shrink Ray has special support for the following formats:
+
+* C and C++ (via `clang_delta`, which you will have if creduce is installed)
+* Python
+* JSON
+* Dimacs CNF format for SAT problems
+
+Most of this support is quite basic and is just designed to deal with specific cases that the generic logic is known
+not to handle well, but it's easy to extend with additional transformations.
+It is also fairly easy to add support for new formats as needed.
+
+If you run into a test case and interestingness test that you care about that shrink ray handles badly please let me know and I'll likely see about improving its handling of that format.
+
+## Parallelism
+
+You can control the number of parallel tasks shrinkray will run with the `--parallelism` flag. By default this will be the number of CPU cores you have available
+
+Shrink Ray is designed to be able to run heavily in parallel, with a basic heuristic of aiming to be embarrassingly parallel when making no progress, mostly sequential when making progress, and smoothly scaling in between the two. It mostly succeeds at this.
+
+Currently the bottleneck on scaling to a very large number of cores is how fast the controlling Python program can generate variant test cases to try and pass them to the interestingness test. This isn't well optimised at present and I don't currently have good benchmarks for it, but I'd expect you to be able to get linear speedups on most workflows while running 10-20 test cases in parallel, and to start to struggle past that.
+
+This also depends on the performance of the interestingness test - the slower your test is to run, the more you'll be able to scale linearly with the number of cores available.
+
+I'm quite interested in getting this part to scale well, so please let me know if you find examples where it doesn't seem to work.
+
+## Bug Reports
+
+Shrink Ray is still pretty new and under-tested software, so it definitely has bugs. If you run into any, [please file an issue](https://github.com/DRMacIver/shrinkray/issues).
+
+As well as obvious bugs (crashes, etc) I'm also very interested in hearing about usability issues and cases where the reduced test case isn't very good.
+
+Requests for new features, new supported formats, etc. also welcome although I'm less likely to jump right on them.
+
+## Sponsorship
+
+Shrink Ray is something of a labour of love - I wanted to have a tool that actually put into practice many of my ideas about test-case reduction, as I think the previous state of the art was well behind where I'd like it to be.
+
+That being said, it is first and foremost designed to be a useful tool for practical engineering problems.
+If you find it useful as such, please [consider sponsoring my development of it](https://github.com/sponsors/DRMacIver).

shrinkray-25.12.26/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "shrinkray"
+version = "25.12.26"
+description = "Shrink Ray"
+authors = [
+    {name = "David R. MacIver", email = "david@drmaciver.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.0.1",
+    "chardet>=5.2.0",
+    "trio>=0.28.0",
+    "textual>=0.47.0",
+    "humanize>=4.9.0",
+    "libcst>=1.1.0",
+    "exceptiongroup>=1.2.0",
+    "binaryornot>=0.4.4",
+    "black",
+]
+
+[project.urls]
+Homepage = "https://github.com/DRMacIver/shrinkray"
+Repository = "https://github.com/DRMacIver/shrinkray"
+Documentation = "https://shrinkray.readthedocs.io"
+Changelog = "https://github.com/DRMacIver/shrinkray/releases"
+
+[project.scripts]
+shrinkray = "shrinkray.__main__:main"
+shrinkray-worker = "shrinkray.__main__:worker_main"
+
+[project.optional-dependencies]
+dev = [
+    "coverage>=7.13.0",
+    "hypothesis>=6.92.1",
+    "hypothesmith>=0.3.1",
+    "pytest",
+    "pytest-trio",
+    "pytest-asyncio",
+    "pytest-textual-snapshot",
+    "coverage[toml]",
+    "pygments",
+    "basedpyright",
+    "ruff",
+    "pexpect>=4.9.0",
+    "pyte>=0.8.2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.paths]
+source = ["src", "*/site-packages"]
+
+[tool.coverage.run]
+branch = true
+source = ["shrinkray"]
+# Use ctrace core instead of sysmon to avoid Python 3.14 async for branch bug
+core = "ctrace"
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "C4", "UP"]
+ignore = [
+    "E501",  # line too long - handled by formatter
+    "B007",  # unused loop variable
+    "B023",  # function definition in loop
+    "B904",  # raise without from - intentional in some exception handling
+    "C408",  # unnecessary dict() call - sometimes more readable
+    "UP031", # use format specifiers - % format is fine
+    "B018",  # useless expression - sometimes intentional for side effects
+    "C403",  # unnecessary list comprehension - sometimes more readable
+    "UP022", # prefer capture_output - explicit is fine
+]
+
+[tool.ruff.lint.isort]
+force-single-line = false
+lines-after-imports = 2
+
+[tool.basedpyright]
+include = ["src", "tests"]
+exclude = ["build", "bugs", ".venv", ".venv2"]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+# These are too noisy with third-party libraries that lack type stubs
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownArgumentType = false
+reportUnknownLambdaType = false
+# These are often false positives or stylistic
+reportUnusedFunction = false
+reportMissingTypeArgument = false
+reportPrivateUsage = false  # Tests need to access private attributes
+reportIncompatibleMethodOverride = false  # Often false positives with textual
+reportUnnecessaryIsInstance = false  # Needed for runtime type checking of untrusted input
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

shrinkray-25.12.26/src/shrinkray/__init__.py

@@ -0,0 +1 @@
+"""Shrink Ray."""