analint 0.0.1__tar.gz

analint-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+reviews/
+_apalache-out/

analint-0.0.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version is
+`0.x` the public API may change between minor releases.
+
+## [0.0.1] — 2026-06-21
+
+First public release. The engine and CLI are mature and covered by an extensive
+test suite; this release makes them installable and documents their scope.
+
+### Added
+
+- **DSL** for declaring system behaviour in Python: `Entity` with field
+  constraints, `Invariant`, `Action` (`pre` / `effect` / `post` / `emits`),
+  `Event`, `Lifecycle`, `Scenario`, `Flow`, parameterized actions
+  (`Param`), finite quantifiers/aggregates, `Scope` multiplicity, and `Spec` as
+  the top-level aggregate.
+- **Validator** with a single transition kernel shared by scenarios, flows, and
+  the explorer; structural validation; scenario execution; executable multi-step
+  flows.
+- **Bounded reachability engine**: BFS over a finite state graph with reachability
+  queries (`Reachable`, `Unreachable`, `AlwaysHolds`, `NoDeadEnd`, `DeadActions`),
+  state-diff witness/counterexample traces, and a deterministic
+  `analint.exploration/v1` artifact.
+- **CLI** `analint`: `check`, `show`, `affects`, `explore`, `trace`, with
+  `--what-if` hypothesis testing, terminal and JSON output, and meaningful exit
+  codes.
+- **MCP server** (`analint-mcp`, optional `mcp` extra) exposing the same surface
+  to AI agents.
+- **Examples** spanning business analytics, game/narrative rules, and two external
+  evidence models (GitHub branch protection, OAuth 2.0 auth-code + PKCE), plus a
+  project-sized Kubernetes ReplicaSet dogfood.
+
+### Scope and honesty
+
+- Verification is **bounded reachability** over a finite state space: it checks
+  safety and reachability and reports a three-valued verdict
+  (`PASS` / `FAIL` / `INCONCLUSIVE`), preferring `INCONCLUSIVE` / `NOT_CHECKED`
+  over a silent pass.
+- It deliberately does **not** model liveness or temporal "eventually"
+  properties. This is a scope boundary, not a defect.
+
+[0.0.1]: https://github.com/angru/analint/releases/tag/v0.0.1

analint-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to analint
+
+Thanks for your interest in analint. This is an early public release (`0.0.1`):
+issues, reproductions, and example specs are especially welcome.
+
+All new repository content — code, comments, docs, commit messages — is written in
+**English**. (Some historical research notes are in Russian; leave them as-is.)
+
+## Development setup
+
+analint uses [uv](https://docs.astral.sh/uv/) and targets **Python 3.12+**.
+
+```bash
+git clone https://github.com/angru/analint
+cd analint
+uv sync                      # create the env and install dev dependencies
+uv run analint examples/ecommerce/   # smoke test
+```
+
+## Running the checks
+
+```bash
+uv run pytest                # full test suite
+uv run ruff check .          # lint
+uv run ruff format --check . # formatting
+uv run ty check              # type check (src/)
+```
+
+A few specific things to know about the test suite:
+
+- `tests/test_characterization.py` is the behavioural regression oracle: a
+  committed golden snapshot (`tests/snapshots/examples.json`) of every example's
+  verdict, per-scenario results, and per-query graph hashes/traces. If you
+  **intentionally** change behaviour, regenerate it — never mechanically, always
+  after confirming the new snapshot is correct:
+
+  ```bash
+  UPDATE_SNAPSHOT=1 uv run pytest tests/test_characterization.py
+  ```
+
+  See `tests/snapshots/README.md` for the regen rule and expected deltas.
+- `tests/test_transition_conformance.py` is the fine-grained kernel gate. Agreed
+  semantics stay green; known target changes are `xfail(strict=True)`, so fixing
+  one produces an XPASS until its marker is deliberately removed.
+
+## Trying the CLI
+
+```bash
+uv run analint check .                      # validate the spec in the cwd
+uv run analint show action <id> -p <spec>   # inspect one action
+uv run analint affects <Entity.field> -p <spec>   # blast radius of a field
+uv run analint explore -p <spec>            # bounded reachability exploration
+uv run analint check . --what-if file.py    # test a hypothesis without editing files
+```
+
+Exit codes: `0` ok · `1` findings · `2` usage · `3` spec failed to load · `4`
+inconclusive (a query exhausted its exploration budget — it proved nothing). JSON
+output carries a three-valued `verdict` (`PASS`/`FAIL`/`INCONCLUSIVE`).
+
+## How the project works
+
+- **`ROADMAP.md` is the single source of truth** for status and priorities.
+  `research/` holds dated design rationale that the roadmap links to;
+  `AGENTS.md` is a detailed map of the codebase.
+- The project is **review-gated and fail-closed by design**: a verification
+  feature that hides a defect is the worst possible outcome here. Prefer
+  `INCONCLUSIVE` / `NOT_CHECKED` over a silent pass. When you add or change a
+  verification path, adversarially self-probe it — plant a defect the new path
+  should catch and confirm the overall verdict actually goes `FAIL`.
+- Keep changes semantically focused: one behavioural change per commit, with the
+  characterization snapshot updated deliberately in the same commit.
+
+## Pull requests
+
+1. Branch from `main`.
+2. Make the change; add or update tests and (if behaviour changed) the snapshot.
+3. Ensure `pytest`, `ruff`, and `ty` are green.
+4. Open a PR describing **what guarantee changed**, not just the diff.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

analint-0.0.1/LICENSE

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