chore: InputGuard v0.3.0 release — tested docs, integration recipes, measured FP benchmark, changelog

.github/workflows/ci.yml

@@ -2,20 +2,148 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, "release/**"]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
+  # The quality gate: lint, tests with a 90% branch-coverage floor, and
+  # strict typing across the full supported Python matrix (spec §8).
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        # 3.9 is the package floor (requires-python), 3.13 is current.
-        python-version: ["3.9", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e ".[dev]"
-      - run: pytest -q
+      - name: Install with dev tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check inputguard tests eval
+      - name: Run tests with 90% branch-coverage floor
+        # Latency asserts are excluded here and gate only in the dedicated
+        # benchmark job: coverage tracing roughly triples per-call cost
+        # (observed on run 35277175054 — debug p50 21.14 ms vs 6.59 ms
+        # untraced), so gating latency under coverage double-gates the same
+        # budgets under different conditions.
+        run: |
+          pytest -q --cov=inputguard --cov-branch --cov-fail-under=90 --strict \
+            --ignore=tests/test_benchmarks.py
+      - name: Strict typing (checks the shipped py.typed)
+        run: mypy --strict inputguard
+
+  # Latency budgets are gates, not notes: a regression here is a production
+  # failure mode (the v0.2 unbounded 3.8 s scan). Measured p50/p99 print to
+  # the job log; budgets and their derivation live in tests/test_benchmarks.py.
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install with dev tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Latency budgets (p50/p99 recorded)
+        run: pytest -v -s tests/test_benchmarks.py
+
+  # The zero-dependency promise, verified against the built artifact — not
+  # the source tree: wheel METADATA carries no Requires-Dist, a bare venv
+  # install pulls no third-party package, and the public API + CLI work from
+  # the installed wheel alone. The smoke steps run from a scratch directory
+  # so the repo's local `inputguard/` package can never shadow the wheel.
+  wheel-zero-dep:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+      - name: Wheel metadata declares no unconditional runtime dependencies
+        run: |
+          python - <<'PY'
+          import glob
+          import zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          meta_name = next(n for n in names if n.endswith(".dist-info/METADATA"))
+          meta = zipfile.ZipFile(wheel).read(meta_name).decode()
+          requires = [
+              line
+              for line in meta.splitlines()
+              if line.startswith("Requires-Dist:")
+          ]
+          unconditional = [
+              line for line in requires if 'extra == "' not in line
+          ]
+          assert not unconditional, (
+              "wheel METADATA declares unconditional runtime dependencies — "
+              f"the zero-dep promise is broken: {unconditional}"
+          )
+          extra_gated = len(requires)
+          print(
+              f"{wheel}: 0 unconditional runtime dependencies "
+              f"({extra_gated} extra-gated dev-only entries)"
+          )
+          PY
+      - name: Install wheel into a bare venv
+        run: |
+          python -m venv bare
+          ./bare/bin/pip install --upgrade pip
+          ./bare/bin/pip install dist/*.whl
+      - name: Public API works from the installed wheel
+        run: |
+          cd "$(mktemp -d)"
+          "$GITHUB_WORKSPACE/bare/bin/python" - <<'PY'
+          import json
+
+          import inputguard
+
+          assert inputguard.__version__
+          guard = inputguard.InputGuard()
+          result = guard.analyze("make this faster", domain="coding")
+          assert isinstance(result.clarity_score, int)
+          assert 0 <= result.clarity_score <= 100
+          payload = result.to_dict()
+          json.dumps(payload)
+          print(f"bare-venv analyze OK: {result.status} score={result.clarity_score}")
+          PY
+      - name: Bare venv contains no third-party packages
+        run: |
+          third_party=$(./bare/bin/pip list --format=freeze \
+            | cut -d= -f1 | tr '[:upper:]' '[:lower:]' \
+            | grep -v -E '^(inputguard|pip|setuptools)$' || true)
+          if [ -n "$third_party" ]; then
+            echo "Third-party packages present after wheel install: $third_party"
+            exit 1
+          fi
+          echo "bare venv holds only inputguard (+ venv tooling)"
+      - name: CLI works from the installed wheel
+        run: |
+          cd "$(mktemp -d)"
+          INPUTGUARD="$GITHUB_WORKSPACE/bare/bin/inputguard"
+          "$INPUTGUARD" analyze "make this faster" --format json
+          set +e
+          "$INPUTGUARD" analyze "make this faster" --min-score 85
+          code=$?
+          set -e
+          if [ "$code" -ne 1 ]; then
+            echo "expected exit 1 below the min-score floor, got $code"
+            exit 1
+          fi
+          echo "CLI exit codes OK (0 on analysis, 1 below the min-score floor)"

CHANGELOG.md

@@ -42,6 +42,45 @@ in `docs/false-positive-benchmark.md`.
   carrying a run of 3+ consecutive uncovered-script letters (mixed
   English+Han). English prompts with loanwords, URLs, or name collisions
   are pinned unchanged by tests.
+- CI as production gates (`.github/workflows/ci.yml`): a Python 3.9–3.13
+  matrix running ruff, pytest with a 90% branch-coverage floor
+  (`--cov-branch --cov-fail-under=90 --strict`, latency asserts excluded
+  from the traced pass), and mypy `--strict` (the shipped `py.typed` is
+  now actually checked); a dedicated untraced latency-benchmark job with
+  budgets measured on this codebase (10k-char build-intent p50 ≤ 65 ms
+  including the catch-all re-run path, debug and ready paths ≤ 25 ms; a
+  1.6 MB input bounded by the policy cap); and a zero-dependency wheel
+  gate that builds the wheel, installs it into a bare venv, and asserts
+  no third-party package is present.
+- `inputguard` CLI (`inputguard analyze`) via a console-script entry
+  point: argparse, `--format json` emitting the same `to_dict()`
+  contract, and CI-friendly exit codes (0 ok, 1 below `--min-score`,
+  2 usage error).
+- Packaging metadata: 3.13 classifier, Development Status → 4 - Beta,
+  project URLs, and the explicit dev extras / tool config
+  (`[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`).
+
+### Docs
+- README rewritten for the v0.3 surface — public exports (including the
+  extension API), Policy customization, custom rule/domain registration,
+  follow-up questions, multilingual degradation, and CLI usage — with the
+  v0.2 example-drift failure mode closed structurally: every README
+  example is executed by `tests/test_readme_examples.py`, the embedded
+  `to_dict()` JSON is regenerated from live analyzer output, and the
+  export list, rule tables, gap vocabulary, and CLI output are checked
+  against the registry.
+- Framework integration recipes: `docs/recipes/langchain.md` and
+  `docs/recipes/litellm.md`, copy-paste patterns over the `to_dict()`
+  serialization boundary. Framework packages stay out of core; the recipe
+  blocks are example-tested with framework stubs in
+  `tests/test_recipes.py`.
+- False-positive benchmark documentation refreshed from a measured run of
+  `eval/measure_fp.py` on this release state: 116/121 overall, FP 3.3% /
+  FN 0.8%, zero false positives on true negatives and degradation rows.
+  The labeling-guide boundary target is stated honestly: 4 of 6
+  fixture-style rows still flag (v0.2 baseline 6/6, target 0/6) through
+  the matcher's deliberate inflection tolerance — documented as an
+  eval-driven trade-off for a future release, not a label edit.
 
 ### Changed
 - All term matching now happens at word boundaries (`#6`) — detector and