shakeout 0.1.0__tar.gz

shakeout-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 4 * * *"  # nightly tier
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint and types
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv lock --check
+      - run: uv sync --locked --python 3.14
+      - run: uv run ruff format --check .
+      - run: uv run ruff check --output-format=github .
+      - run: uv run pyright
+      - run: uv run mypy
+      - run: uv run codespell src tests/*.py tests/harness tests/unit tests/fuzz/*.py docs README.md
+      - run: uv run vulture src vulture_whitelist.py --min-confidence 60
+      - run: uv run validate-pyproject pyproject.toml
+      - run: uv run actionlint
+      - run: uv run zizmor --persona=pedantic --quiet .github/workflows
+
+  test:
+    name: test (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv sync --locked --python "$PYTHON"
+        env:
+          PYTHON: ${{ matrix.python }}
+      - name: tests (branch coverage gate on one interpreter)
+        env:
+          PYTHON: ${{ matrix.python }}
+          OS: ${{ matrix.os }}
+        run: |
+          if [ "$PYTHON" = "3.14" ] && [ "$OS" = "ubuntu-latest" ]; then
+            uv run pytest -n auto --cov --cov-report=term-missing:skip-covered
+          else
+            uv run pytest -n auto
+          fi
+
+  package:
+    name: package and docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv sync --locked --python 3.14 --group docs
+      - run: uv run mkdocs build --strict --site-dir build/site
+      - run: uv build
+      - run: uv run twine check --strict dist/*
+      - run: uv run check-wheel-contents dist/*.whl
+      - run: uv run --isolated --no-project --with dist/*.whl shakeout --version
+
+  audit:
+    name: dependency audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv sync --locked --python 3.14
+      - run: uv export --frozen --all-groups --no-hashes --no-emit-project -o requirements.txt
+      - run: uv run pip-audit --strict --progress-spinner off -r requirements.txt
+
+  nightly:
+    name: nightly (corpus, long fuzz, mutation)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv sync --locked --python 3.14
+      - name: corpus and 1500-program fuzz campaign
+        run: uv run pytest -n auto -m nightly
+      - name: mutation testing of the analysis core
+        run: scripts/mutation.sh
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        if: always()
+        with:
+          name: nightly-results
+          path: |
+            tests/corpus/metrics.json
+            tests/fuzz/failures/
+            mutants/
+          if-no-files-found: ignore

shakeout-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+        with:
+          enable-cache: false
+      - run: uv run --locked --group docs mkdocs build --strict --site-dir build/site
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
+        with:
+          path: build/site
+
+  deploy:
+    name: deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write  # publish the site
+      id-token: write  # prove the deployment's origin to Pages
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5.0.1

shakeout-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: release
+
+# Push a tag like v0.1.0 to publish. PyPI trusted publishing (OIDC): no API tokens are stored.
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false  # never interrupt a publish
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+        with:
+          enable-cache: false  # never restore caches into a release build
+      - name: tag matches the package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match version $version" >&2
+            exit 1
+          fi
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - run: uvx check-wheel-contents dist/*.whl
+      - run: uv run --isolated --no-project --with dist/*.whl shakeout --version
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/shakeout/
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+
+  github-release:
+    name: GitHub release
+    needs: pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write  # create the GitHub release
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: create release with the distributions attached
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --generate-notes --verify-tag

shakeout-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+/build/
+/dist/
+tests/fuzz/failures/
+.corpus/
+.venv-*/
+mutants/

shakeout-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+# Uses the tool versions pinned in uv.lock. Install: uv run pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+      - id: ruff
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: codespell
+        name: codespell
+        entry: uv run codespell
+        language: system
+        types_or: [python, markdown]
+        exclude: ^tests/cases/
+      - id: uv-lock
+        name: uv lock --check
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+      - id: actionlint
+        name: actionlint
+        entry: uv run actionlint
+        language: system
+        files: ^\.github/workflows/

shakeout-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-11-08)
+
+First release.
+
+- Static, sound tree shaking of first-party code (and opted-in third-party packages) across
+  module boundaries, with esbuild-style rewriting of kept imports.
+- Targets: `single` (one runnable or importable `.py`), `pyz` (zipapp), `tree`, and `lambda`
+  (reproducible AWS Lambda zip with `--export` handlers).
+- Exact tracebacks from bundles: original file names, line numbers and source lines; runtime notes
+  that name the `keep` setting when removed code is reached; `shakeout trace`.
+- Dependencies: vendoring of unshaken distributions, `include` to shake them, `--uv` staging from
+  `uv.lock` for a target Python and platform.
+- `--minify` with exact line numbers, `--strip-docstrings`.
+- CLI: `build`, `report`, `why`, `trace`; configuration in `[tool.shakeout]`.
+- CPython 3.10 to 3.15.

shakeout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mischa Spiegelmock
+
+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.

shakeout-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: shakeout
+Version: 0.1.0
+Summary: Static tree-shaking bundler for Python
+Project-URL: Homepage, https://github.com/revmischa/shakeout
+Project-URL: Documentation, https://revmischa.github.io/shakeout/
+Project-URL: Repository, https://github.com/revmischa/shakeout
+Project-URL: Issues, https://github.com/revmischa/shakeout/issues
+Project-URL: Changelog, https://github.com/revmischa/shakeout/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aws-lambda,bundler,dead-code,tree-shaking,zipapp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: 3.15
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# shakeout
+
+A static, tree-shaking bundler for Python. Give it an entry script: it finds every module the
+program can import, removes top-level code nothing can reach, and writes a self-contained
+artifact. That can be one runnable `.py`, a zipapp, a pruned directory or a reproducible AWS
+Lambda zip. Tracebacks from bundles name the original files and lines.
+
+```console
+$ uvx shakeout build app/main.py -o dist                       # one runnable file
+$ uvx shakeout build handler.py -t lambda --export handler     # Lambda package
+$ uvx shakeout report app/main.py                              # what is kept, and why
+$ uvx shakeout why app/main.py pkg.core:helper                 # the chain that keeps a symbol
+```
+
+**Documentation:** https://revmischa.github.io/shakeout/ (sources in [`docs/`](docs/); the
+design and roadmap are in [docs/project/design.md](docs/project/design.md)).
+
+## Guarantees
+
+- **Sound by default.** Anything the analysis can't prove unused is kept: registration
+  decorators, `__init_subclass__` and metaclass registries, modules that use `globals()`, `eval`
+  or `sys.modules`, module objects passed around as values, star imports.
+- **Exact tracebacks without source maps.** Modules keep their original file names and line
+  numbers, and their sources are registered with `linecache`. Tracebacks, `warnings`,
+  `inspect.getsource` and error trackers show real files, lines, carets and code, even in
+  Lambda.
+- **Self-explaining failures.** Reaching a removed name at runtime raises the usual exception
+  with a note that names the `keep` setting to add.
+
+## How it is tested
+
+| Tier | What it checks |
+|---|---|
+| Case catalog (`tests/cases/**/*.case`) | 126 multi-file programs: expected removals, behavioral equivalence of every target (stdout, exit code, traceback frames), a no-shake build, reviewed golden reports |
+| Soundness oracle | runs the original under `sys.monitoring`; fails if any function that executed was removed |
+| Differential checks | scope analysis vs. CPython's `symtable`, and minified vs. original bytecode, over the whole stdlib |
+| Fuzzing | Hypothesis-generated multi-module programs; equivalence + soundness |
+| Mutation testing | 100% of mutants in the effects rules, class analysis and shaker are killed (floor 99%) |
+| Real-world corpus (nightly) | attrs, click, dateutil, idna, jinja2, packaging, rich, six, tomli |
+| Self-hosting | shakeout bundles itself byte-identically and contains no dead code |
+
+Every gate CI runs is in `scripts/check.sh`: `ruff` with all rules, strict `pyright` and `mypy`,
+96% branch coverage, vulture, codespell, packaging checks, pip-audit, zizmor and actionlint, and
+a strict docs build. CPython 3.10 to 3.15 are supported (`scripts/matrix.sh`).

shakeout-0.1.0/README.md

@@ -0,0 +1,44 @@
+# shakeout
+
+A static, tree-shaking bundler for Python. Give it an entry script: it finds every module the
+program can import, removes top-level code nothing can reach, and writes a self-contained
+artifact. That can be one runnable `.py`, a zipapp, a pruned directory or a reproducible AWS
+Lambda zip. Tracebacks from bundles name the original files and lines.
+
+```console
+$ uvx shakeout build app/main.py -o dist                       # one runnable file
+$ uvx shakeout build handler.py -t lambda --export handler     # Lambda package
+$ uvx shakeout report app/main.py                              # what is kept, and why
+$ uvx shakeout why app/main.py pkg.core:helper                 # the chain that keeps a symbol
+```
+
+**Documentation:** https://revmischa.github.io/shakeout/ (sources in [`docs/`](docs/); the
+design and roadmap are in [docs/project/design.md](docs/project/design.md)).
+
+## Guarantees
+
+- **Sound by default.** Anything the analysis can't prove unused is kept: registration
+  decorators, `__init_subclass__` and metaclass registries, modules that use `globals()`, `eval`
+  or `sys.modules`, module objects passed around as values, star imports.
+- **Exact tracebacks without source maps.** Modules keep their original file names and line
+  numbers, and their sources are registered with `linecache`. Tracebacks, `warnings`,
+  `inspect.getsource` and error trackers show real files, lines, carets and code, even in
+  Lambda.
+- **Self-explaining failures.** Reaching a removed name at runtime raises the usual exception
+  with a note that names the `keep` setting to add.
+
+## How it is tested
+
+| Tier | What it checks |
+|---|---|
+| Case catalog (`tests/cases/**/*.case`) | 126 multi-file programs: expected removals, behavioral equivalence of every target (stdout, exit code, traceback frames), a no-shake build, reviewed golden reports |
+| Soundness oracle | runs the original under `sys.monitoring`; fails if any function that executed was removed |
+| Differential checks | scope analysis vs. CPython's `symtable`, and minified vs. original bytecode, over the whole stdlib |
+| Fuzzing | Hypothesis-generated multi-module programs; equivalence + soundness |
+| Mutation testing | 100% of mutants in the effects rules, class analysis and shaker are killed (floor 99%) |
+| Real-world corpus (nightly) | attrs, click, dateutil, idna, jinja2, packaging, rich, six, tomli |
+| Self-hosting | shakeout bundles itself byte-identically and contains no dead code |
+
+Every gate CI runs is in `scripts/check.sh`: `ruff` with all rules, strict `pyright` and `mypy`,
+96% branch coverage, vulture, codespell, packaging checks, pip-audit, zizmor and actionlint, and
+a strict docs build. CPython 3.10 to 3.15 are supported (`scripts/matrix.sh`).

shakeout-0.1.0/docs/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" aria-label="shakeout">
+  <path d="M32 6 L54 44 H10 Z" fill="currentColor" opacity="0.18"/>
+  <path d="M32 6 L54 44 H10 Z" stroke="currentColor" stroke-width="4" stroke-linejoin="round"/>
+  <path d="M32 44 V58" stroke="currentColor" stroke-width="4" stroke-linecap="round"/>
+  <circle cx="19" cy="54" r="3" fill="currentColor" opacity="0.55"/>
+  <circle cx="46" cy="56" r="2.5" fill="currentColor" opacity="0.4"/>
+  <circle cx="40" cy="50" r="2" fill="currentColor" opacity="0.3"/>
+</svg>

shakeout-0.1.0/docs/concepts/how-it-works.md

@@ -0,0 +1,35 @@
+# How shaking works
+
+```text
+ resolve ─► parse ─► analyze ─► link ─► shake ─► emit
+ modules     AST     scopes,     cross-   reach-   chunks with
+ (no exec)           effects     module   ability  original lines
+```
+
+1. **Resolve.** Starting from the entry script, shakeout follows every `import`, including ones
+   inside functions, and locates modules the way Python would, without executing anything.
+   Modules under your source roots are bundled. The standard library and other packages are
+   external.
+2. **Parse and analyze.** Each module is split into top-level statements. For each one,
+   shakeout records the names it binds, the names it reads, using exact Python scoping rules,
+   the modules it may import, and whether running it has [side effects](side-effects.md).
+3. **Link.** References like `pkg.sub.func` are followed through imports and re-exports to the
+   statement that defines them.
+4. **Shake.** Starting from the entry point, every statement with side effects in an imported
+   module, and every export or keep, is marked live, then everything live code references.
+   A module that nothing live imports is dropped entirely.
+5. **Emit.** Kept statements are written with their original line numbers, and kept imports are
+   [rewritten](import-rewriting.md) to drop unused names. Removed names get a small
+   `__getattr__` that explains them if they are reached at runtime.
+
+## Per-module isolation
+
+Unlike JavaScript bundlers, shakeout doesn't merge modules into one namespace ("scope
+hoisting"). Every module keeps its own globals, `__name__`, import order and circular-import
+behavior. That costs a little size and buys exact semantics and honest tracebacks.
+
+## What is shaken
+
+The unit of removal is a top-level statement: a function, class, assignment or import.
+Methods inside a kept class stay. Whether an instance's method is called can't be decided
+statically.

shakeout-0.1.0/docs/concepts/import-rewriting.md

@@ -0,0 +1,28 @@
+# Import rewriting
+
+A kept `from m import a, b` fails at runtime if `b` no longer exists. Keeping `b` just for
+that would keep most of a library's public API alive. Instead, shakeout rewrites kept imports,
+like esbuild does:
+
+```python
+from lib import used, unused  # before
+from lib import used  # shakeout: was 'from lib import used, unused'   # after
+```
+
+If none of the names are used but the import is kept for its side effects, it becomes a plain
+import:
+
+```python
+import lib as _shakeout_import_1  # shakeout: was 'from lib import a, b'
+```
+
+The rewritten line occupies the same number of lines as the original, and it carries a comment
+saying what it was, so a traceback through it explains itself.
+
+## Not rewritten
+
+- Imports of modules outside the bundle: a missing name must still raise `ImportError`.
+- Imports in modules kept whole (for example because they call `globals()`).
+- Plain `import x`. It never requires attributes to exist, so only names of side-effect-free
+  bundled modules are dropped, and traceback text stays identical.
+- A `from pkg import sub` where `sub` is a submodule with side effects.

shakeout-0.1.0/docs/concepts/index.md

@@ -0,0 +1,7 @@
+# Concepts
+
+- [How shaking works](how-it-works.md): the pipeline from entry point to artifact.
+- [Side effects](side-effects.md): which statements may be removed, and why most can't.
+- [Import rewriting](import-rewriting.md): how kept imports shed unused names.
+- [Targets](targets.md): single file, zipapp, tree and Lambda.
+- [Soundness and testing](soundness.md): what shakeout guarantees and how that is checked.

shakeout-0.1.0/docs/concepts/side-effects.md

@@ -0,0 +1,47 @@
+# Side effects
+
+Importing a Python module runs it. A statement may only be removed if running it does nothing
+observable, which means it only creates bindings in its own module, and if nothing reachable uses
+those bindings.
+
+## Removable when unused
+
+| Statement | Condition |
+|---|---|
+| `def` / `async def` | No decorators, or only known-pure ones (`dataclass`, `lru_cache`, `property`, `contextmanager`, ...), and pure default values |
+| `class` | Pure decorators, no class keywords, a pure body, and bases that don't register subclasses |
+| `x = ...` | Plain name targets and a pure value: literals, names, operators, lambdas, and calls to known-pure constructors like `TypeVar`, `namedtuple`, `re.compile`, `frozenset`, `field` |
+| `import` | Every module it loads is side-effect free: the standard library, or bundled modules with no side effects |
+| `if TYPE_CHECKING:` | Always |
+
+## Always kept
+
+Calls at module level, loops, `try`, `with`, attribute or item stores (`config.X = 1`), augmented
+assignment, `del`, `__future__` imports, module docstrings, dunders like `__all__` and
+`__getattr__`, and anything marked `# shakeout: keep`.
+
+## Classes that register
+
+Defining a subclass runs `__init_subclass__` and metaclass code, which is how plugin registries
+work. A class is *registering* if it defines `__init_subclass__`, has a metaclass, or inherits from
+a registering class. Subclasses of registering classes are always kept. Bases imported from
+packages outside the bundle are assumed to register too, unless they are known to be safe
+(`Exception`, `Enum`, `Protocol`, `NamedTuple`, `ABC`, the `collections.abc` types, ...).
+`assume-pure-bases = true` trusts all unknown bases.
+
+## Effects travel through imports
+
+A module has side effects if it runs a side-effecting statement or imports a module that has
+them. An `import` of such a module is kept even when its names are unused, because removing it
+would skip those effects.
+
+## Assumptions
+
+These are documented so you can judge them:
+
+- Operators, attribute reads and subscripts on module-level values don't call user code with
+  side effects.
+- The known-pure callables don't call back into user code. Builtins that do, like `sorted(...,
+  key=f)` and `map`, are not on the list.
+- Importing standard-library modules has no observable effects, except for a short denylist
+  such as `this`, `antigravity` and `turtle`.

shakeout-0.1.0/docs/concepts/soundness.md

@@ -0,0 +1,27 @@
+# Soundness and testing
+
+**Sound** means: if the original program would run a piece of code, the bundle still contains it.
+A bundler that removes too much breaks programs silently, so shakeout's test suite exists
+mainly to make that impossible to miss.
+
+| Check | What it catches |
+|---|---|
+| Case catalog (126 multi-file programs) | Expected removals, plus byte-identical stdout, exit codes and traceback frames for every target, with and without shaking and minification |
+| Soundness oracle | Runs the *original* program under `sys.monitoring` and fails if any function that executed was removed, even if output happened to match |
+| `symtable` differential | Scope analysis against CPython's own symbol table on every standard-library file |
+| Minify equivalence | Minified standard-library sources compile to identical instructions on identical lines |
+| Fuzzing | Hypothesis generates multi-module programs with registries, plugins, cycles, local imports and `globals()`, and checks equivalence and soundness |
+| Real-world corpus | attrs, click, dateutil, idna, jinja2, packaging, rich, six and tomli, shaken and compared |
+| Mutation testing | Mutants of the effects rules, class analysis and reachability engine must be caught. The current kill rate is 100% |
+| Self-hosting | shakeout bundles itself and the bundle produces byte-identical output. Shaking shakeout from its API removes nothing |
+
+Every bug these found became a permanent regression case. The list is in the
+[design document](../project/design.md).
+
+## Known limits
+
+- Code reached only through strings (settings files, entry points, generated code) needs `keep`.
+- Data files next to modules are only shipped in vendored distributions. Reading `__file__` in
+  your own modules produces a warning.
+- Dropping a side-effect-free module can change the order in which other modules initialize.
+  This matters only for order-dependent circular imports.

shakeout-0.1.0/docs/concepts/targets.md

@@ -0,0 +1,31 @@
+# Targets
+
+| Target | Output | Runs as | Contains third-party code |
+|---|---|---|---|
+| `single` | `<entry>.py` (+ `<entry>.manifest.json`) | `python main.py`, or `import` it with `--export` | Only `include`d pure-Python packages |
+| `pyz` | `<entry>.pyz` | `python main.pyz` or `./main.pyz` | Yes, vendored |
+| `tree` | a directory, one file per module | `python dist/main.py` | Yes, vendored |
+| `lambda` | `<entry>.zip` and `package/` | AWS Lambda handler `<entry>.<export>` | Yes, vendored |
+
+## single
+
+A small runtime (about 200 lines) installs an in-memory importer and runs the entry in the real
+`__main__` namespace. The program sees exactly the globals it would see unbundled, and `pickle`
+of classes defined in the entry works. Each module is stored as chunks tagged with their original
+start line and padded back to the original line numbers when compiled.
+
+## tree
+
+Every module is written to its import path with removed statements replaced by blank lines. No
+runtime is involved: tracebacks name real files.
+
+## pyz
+
+A `tree` packed into a reproducible zipapp. Its `__main__.py` registers archived sources with
+`linecache` (CPython's zipimport only does this lazily for tracebacks and splits lines
+incorrectly when files contain form feeds) and runs the entry with `runpy`.
+
+## lambda
+
+A `tree` with vendored dependencies, zipped reproducibly (fixed timestamps, sorted entries). It
+requires `exports`, and the manifest lists the handler names.