checkwash 0.1.49__tar.gz

checkwash-0.1.49/.gitattributes

@@ -0,0 +1,8 @@
+# Byte-stability matters to a tool that promises byte-identical verdicts:
+# every text file is committed and checked out with LF, on every OS.
+* text=auto eol=lf
+*.py text eol=lf
+*.gwcase text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf

checkwash-0.1.49/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,26 @@
+# The two templates above are the only two reports this project is really
+# asking for. Everything else it can find itself; those two it cannot.
+blank_issues_enabled: true
+contact_links:
+  - name: Check the known-failures page first
+    url: https://github.com/taipei49314/greenwash/blob/main/benchmarks/FAILURES.md
+    about: >-
+      Every bypass that is still open, every human commit greenwash blocks by
+      mistake, and every cheat a real agent got past it — one generated page.
+      If what you found is already there, you have confirmed a known hole
+      rather than found a new one, which is still worth saying, and the row
+      number makes it a two-line issue.
+  - name: What it is documented as unable to do
+    url: https://github.com/taipei49314/greenwash/blob/main/THREATMODEL.md
+    about: >-
+      Rewriting production so a weak test passes honestly is undecidable at
+      the diff layer and out of scope by design; a production file greenwash
+      cannot read suppresses escalation for the whole diff. Neither is a bug
+      report, and both are measured rather than waved away.
+  - name: What is frozen and what will change under you
+    url: https://github.com/taipei49314/greenwash/blob/main/docs/stability.md
+    about: >-
+      Before reporting that an upgrade started blocking something: detector
+      coverage grows on purpose, and growth can newly block. Whether that is a
+      closed bypass or a shipped false positive is exactly the distinction
+      worth an issue — the project has done both, in one day.

checkwash-0.1.49/.github/ISSUE_TEMPLATE/false-block.md

@@ -0,0 +1,26 @@
+---
+name: greenwash blocked honest work
+about: greenwash blocked a commit that did not tamper with anything (a false positive)
+title: "[false block] "
+labels: false-positive
+---
+
+**What the commit actually did**
+<!-- the honest change: fixed a bug, refactored a helper, bumped a dep, ... -->
+
+**The diff (or the relevant part)**
+```diff
+
+```
+
+**What greenwash blocked it with**
+<!-- paste `greenwash check --format json`, esp. the rule and escalators -->
+
+**Why it's a false positive**
+<!-- the oracle is not actually weaker because... -->
+
+---
+Every false positive we've fixed came from a real diff like this one. It'll
+become a negative fixture so it can never regress. Reporter credit lands
+in `benchmarks/FAILURES.md` (External credits) after the quarterly review
+in `docs/cheat-cadence.md`.

checkwash-0.1.49/.github/ISSUE_TEMPLATE/send-us-a-cheat.md

@@ -0,0 +1,36 @@
+---
+name: Send us a cheat greenwash missed
+about: A test-tampering diff that greenwash let through (a false negative)
+title: "[missed cheat] "
+labels: cheat-of-the-week, false-negative
+---
+
+**What the agent did instead of fixing the bug**
+<!-- one line: "widened the tolerance", "deleted the assertion", ... -->
+
+**The test file, before:**
+```python
+
+```
+
+**The test file, after:**
+```python
+
+```
+
+**The production file, if it matters (before / after):**
+```python
+
+```
+
+**What greenwash said**
+<!-- paste `greenwash check --format json` output, or just "verdict: pass" -->
+
+**Why this is tampering and not an honest fix**
+<!-- the bug is still there because... -->
+
+---
+By filing this you agree it can become a regression fixture in the public
+corpus. You'll be credited in the fixture header and, once triaged, in
+the External credits table of `benchmarks/FAILURES.md`. Incoming reports
+are reviewed quarterly — see `docs/cheat-cadence.md`.

checkwash-0.1.49/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]

checkwash-0.1.49/.github/workflows/ci.yml

@@ -0,0 +1,131 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        # The README claims byte-identical verdicts across 3.11-3.13, so all
+        # three are in the matrix. A claim whose gate does not cover it is
+        # exactly what this tool exists to catch.
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Tags are needed by the release-tag gate; a shallow checkout made
+          # that test silently return early (reader audit).
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest
+      - name: emit corpus findings (determinism artifact)
+        shell: bash
+        env:
+          PYTHONUTF8: "1"  # artifact bytes must not depend on runner locale
+        run: python tools/emit_corpus.py > corpus-findings.json
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: corpus-${{ matrix.os }}-py${{ matrix.python }}
+          path: corpus-findings.json
+
+  dogfood:
+    # greenwash runs on its own changes. The judge gets judged.
+    #
+    # This job used to be `if: github.event_name == 'pull_request'`, and this
+    # repository has never had a pull request — so across every run in its
+    # history it reported "skipped" and action/action.yml had still never been
+    # executed once, while the README told people to use it. A previous audit
+    # asked for the action to be dogfooded and the fix that shipped changed
+    # *how* the job invoked it without noticing the job never ran at all.
+    # Green because it did not run is the failure mode this project keeps
+    # repeating; on a push there is a perfectly good diff to check.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      # Exercise the published composite action itself, not just the CLI —
+      # otherwise action/action.yml ships untested (reader audit 2026-08-02).
+      - uses: ./action
+        with:
+          base: ${{ github.event.pull_request.base.sha || 'HEAD~1' }}
+
+  install-from-tag:
+    # What a *visitor* gets, not what the checkout has. dogfood runs ./action
+    # from the working tree, so a stale action.yml (or hook definition) on the
+    # advertised tag would pass every other gate while users installed an old
+    # integration layer (owner review 2026-08-04). This installs the exact
+    # command the README hands out and runs it.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: install the advertised tag from git, exactly as the README says
+        id: install_tag
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="v$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          if ! git rev-parse --verify "refs/tags/$tag" >/dev/null 2>&1; then
+            echo "PRE_TAG_CANDIDATE: $tag not cut yet — defer visitor install-from-tag"
+            echo "mode=pretag" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "mode=posttag" >> "$GITHUB_OUTPUT"
+          pip install "git+file://$PWD@$tag"
+      - name: the installed build must run, replay the demo, and gate this push
+        if: steps.install_tag.outputs.mode == 'posttag'
+        shell: bash
+        env:
+          PYTHONUTF8: "1"
+        run: |
+          set -euo pipefail
+          greenwash --version
+          greenwash demo > /dev/null
+          # The installed build gates this push exactly as dogfood does from
+          # the checkout — its exit code counts. The first draft of this step
+          # swallowed that exit code with a shell or-fallback, and greenwash
+          # blocked the diff: E6 read the CI change as a weakened test
+          # command. It was right, and this wording exists because the tool
+          # corrected its author.
+          greenwash check HEAD~1..HEAD --repo .
+
+  byte-compare:
+    # The cross-OS determinism gate: every OS/Python combination must emit
+    # byte-identical corpus findings (SPEC §8).
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: corpus
+      - name: all artifacts must be byte-identical
+        # Across every OS AND every Python version in the matrix. Verified
+        # locally 2026-07-31 on 3.11.15 / 3.12.13 / 3.13.14 (identical, sha
+        # 5bd75e8d…); this job keeps it true on Linux/macOS/Windows too.
+        run: |
+          sha256sum corpus/*/corpus-findings.json
+          count=$(sha256sum corpus/*/corpus-findings.json | awk '{print $1}' | sort -u | wc -l)
+          test "$count" = "1"

checkwash-0.1.49/.github/workflows/greenwash.yml

@@ -0,0 +1,18 @@
+# .github/workflows/greenwash.yml
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  greenwash:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - uses: taipei49314/greenwash/action@bda9f37e97f2bb9950413ceec9fee91f48985b67 # v0.1.48

checkwash-0.1.49/.github/workflows/release.yml

@@ -0,0 +1,127 @@
+name: release
+
+# Two triggers, both deliberate:
+#   workflow_dispatch — build the artifacts and look at them, publishing nothing
+#   release: published — attach the artifacts to a release a human just cut
+#
+# Nothing here fires on a push. Cutting a release is a decision, and this
+# project's own history is the argument for making it one: a tag once shipped
+# pointing two fixes behind main, and visitors read the fixed docs while
+# installing the unfixed engine.
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # only to attach assets to an already-published release
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+
+      - name: the version being built must match the tag, when there is one
+        if: github.event_name == 'release'
+        shell: bash
+        env:
+          PYTHONUTF8: "1"
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          version="v$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          test "$version" = "$RELEASE_TAG"
+
+      - name: build sdist and wheel
+        run: python -m build
+
+      - name: the sdist and wheel must be well-formed
+        run: twine check dist/*
+
+      # Zero runtime dependencies and one console entry point make a zipapp a
+      # real distribution channel, not a trick: one file, no install, no
+      # virtualenv, no network. `tests/test_zipapp.py` gates it on every push;
+      # this builds the artifact people actually download.
+      - name: build the single-file zipapp
+        shell: bash
+        env:
+          PYTHONUTF8: "1"
+        run: |
+          set -euo pipefail
+          python -m zipapp src -m "greenwash.zipapp_entry:run" -o dist/greenwash.pyz -c
+          python dist/greenwash.pyz --version
+          python dist/greenwash.pyz demo > /dev/null
+          python tools/qualify_zipapp.py dist/greenwash.pyz
+          ls -l dist/
+
+      - name: a fresh install of the wheel must run, replay the demo, and check a repo
+        shell: bash
+        env:
+          PYTHONUTF8: "1"
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/fresh
+          /tmp/fresh/bin/pip install --quiet dist/*.whl
+          /tmp/fresh/bin/pip freeze | tee /tmp/frozen.txt
+          # Zero runtime dependencies is a claim on the README, so the frozen
+          # environment must contain the checkwash distribution and nothing else.
+          test "$(grep -civ '^checkwash' /tmp/frozen.txt)" = "0"
+          /tmp/fresh/bin/greenwash --version
+          /tmp/fresh/bin/checkwash --version
+          /tmp/fresh/bin/greenwash demo > /dev/null
+          /tmp/fresh/bin/greenwash check HEAD~1..HEAD --repo .
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: attach the artifacts to the release
+        if: github.event_name == 'release'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$RELEASE_TAG" dist/* --clobber
+
+  pypi:
+    # Deliberately gated, on a repository *variable* rather than on the
+    # environment. The first version of this job was gated only by
+    # `environment: pypi` and a comment claiming it would be skipped until a
+    # human created that environment. That claim was false: GitHub creates an
+    # environment automatically the first time a job references one, so on the
+    # v0.1.13 release the job ran, found no trusted publisher registered on
+    # PyPI, and failed a release that was otherwise entirely fine (D-032).
+    #
+    # `vars.PYPI_ENABLED` is not auto-created by anything, so this is a gate
+    # that is actually closed. Publishing needs all three, in this order:
+    #   1. register greenwash as a trusted publisher on PyPI, for this
+    #      repository and this workflow;
+    #   2. set the repository variable PYPI_ENABLED to `true`;
+    #   3. keep the `pypi` environment for its deployment protection rules.
+    # No token is stored anywhere by anyone; trusted publishing exchanges a
+    # short-lived OIDC identity instead. Until (2), this job is skipped and
+    # the release is GitHub-only, which is what the README promises.
+    needs: build
+    if: github.event_name == 'release' && vars.PYPI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: the zipapp is a GitHub asset, not a PyPI one
+        run: rm -f dist/greenwash.pyz
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

checkwash-0.1.49/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.greenwash/session/

checkwash-0.1.49/.pre-commit-hooks.yaml

@@ -0,0 +1,14 @@
+# Consumers reference this repo in their .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/taipei49314/greenwash
+#       rev: <tag>
+#       hooks:
+#         - id: greenwash
+- id: greenwash
+  name: greenwash (oracle-tampering tripwire)
+  description: deterministic detector for diffs that weaken the test oracle
+  entry: greenwash check --format term
+  language: python
+  pass_filenames: false
+  always_run: true

checkwash-0.1.49/AGENTS.md

@@ -0,0 +1,21 @@
+# Collaboration protocol (humans and coding agents)
+
+The judge is immutable; the player runs free.
+
+## Agent-writable
+- Detector implementations and their `.gwcase` fixtures (labels reviewed by a human before merge).
+- Frontend syntax-coverage work, adapters, report rendering, packaging.
+
+## Agent-READ-ONLY (changes only by the human maintainer)
+- `SPEC.md`, `THREATMODEL.md`, `DECISIONS.md`
+- `tests/gates/**`
+- Escalation policy (`gating.py` severity table), strength lattice
+  (`ir/strength.py` values), alignment parameters.
+
+## Rules
+1. One round = one detector or one named defect. Atomic commit; the commit
+   message carries the gate output summary.
+2. Never modify an existing fixture's expected output. If you believe the
+   expectation is wrong, open an issue and stop.
+3. Read `STATE.md` first when taking over.
+4. Every PR runs greenwash on itself (dogfood, from M2).

checkwash-0.1.49/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to greenwash
+
+The most valuable thing you can send is a **cheat greenwash missed** or a
+**block it got wrong**. You do not need to write any code to do it.
+
+## Send us a cheat (no code required)
+
+Saw an agent make CI green by tampering with a test, and greenwash would have
+let it through? Open an issue with the before/after of the test file (and the
+production file if relevant). We turn it into a regression fixture, credit you
+in the fixture header, and it joins the corpus that every future release is
+measured against. This is how the detector's coverage grows — the moat is
+built by the people it protects.
+
+The same goes the other way: if greenwash **blocked a commit that was
+honest**, that is a false positive and we want it just as much. Every one we
+have fixed came from a real diff, and each is now a negative fixture.
+
+Issue templates for both are in `.github/ISSUE_TEMPLATE/`.
+Reports are reviewed quarterly (`docs/cheat-cadence.md`); a credited
+external row lands in `benchmarks/FAILURES.md`.
+
+## The one rule that is not negotiable
+
+Every measurement in this project is reproducible and every claim has a test.
+That is not a style preference; it is the reason anyone should trust a tool
+whose whole job is to catch dishonest shortcuts.
+
+- **No number ships without a harness.** Precision comes from
+  `greenwash sweep` over real history; recall from the decoy corpus
+  (`benchmarks/decoy/`). If you change a detector, re-run both and put the
+  numbers in the PR. "It looks right" is how the tool caught 0 of 12 real
+  cheats once — see `benchmarks/decoy/README.md`.
+- **Every detector ships positive and negative `.gwcase` fixtures.** The
+  coverage gate (`tests/test_detector_coverage.py`) enforces it. A detector
+  with no negative fixture is an unbounded false-positive risk.
+- **`SPEC.md`, `THREATMODEL.md`, and `tests/gates/` are the judge.** They are
+  changed deliberately by a human, with a `DECISIONS.md` entry, never as a
+  side effect of making a test pass. (greenwash exists to catch exactly that
+  move; the project holds itself to it.)
+
+## Adding a detector
+
+A detector is a pure function `f(IR) -> list[Finding]` at base severity
+`warn`; `gating.py` decides escalation. Register it in
+`src/greenwash/detectors/__init__.py`, and ship at least one positive and one
+negative fixture in `tests/cases/` in the same PR. Read `SPEC.md §4-§5` first
+so its rule ID and severity fit the frozen model.
+
+## Adding a language
+
+The IR (`SPEC.md`) is language-neutral by design. A new frontend that emits
+IR inherits every existing detector. v0.1 is Python-only; the frontend
+protocol is `src/greenwash/frontends/`.
+
+## Running the suite
+
+```bash
+pip install -e ".[dev]"
+pytest                      # 478 tests: fixtures, e2e, perf and coverage gates
+greenwash demo              # sanity: 8 real cheats blocked, offline
+greenwash bench --local     # in-clone reproduce; omit --local to require sweep clones
+```