codepact 0.3.0__py3-none-any.whl

codepact/__init__.py

@@ -0,0 +1,47 @@
+"""Lightweight runtime declarations for CodePact.
+
+Importing this module never loads the Rust inspector or executes analysis.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar, overload
+
+from .contracts import Resource
+
+T = TypeVar("T")
+
+
+def _is_identifier(value: str) -> bool:
+    try:
+        return value.isidentifier()
+    except AttributeError:
+        return False
+
+
+@overload
+def resource(*, closed_by: str) -> Callable[[type[T]], type[T]]: ...
+
+
+@overload
+def resource(cls: type[T], *, closed_by: str) -> type[T]: ...
+
+
+def resource(
+    cls: type[T] | None = None, *, closed_by: str
+) -> type[T] | Callable[[type[T]], type[T]]:
+    """Attach a declared lifecycle contract while preserving class identity."""
+    if not _is_identifier(closed_by):
+        raise ValueError("closed_by must be a method name")
+
+    def decorate(target: type[T]) -> type[T]:
+        existing = target.__dict__.get("__codepact_resource__")
+        contract = Resource(closed_by=closed_by)
+        if existing is not None and existing != contract:
+            raise ValueError("conflicting CodePact resource declarations")
+        setattr(target, "__codepact_resource__", contract)
+        return target
+
+    return decorate(cls) if cls is not None else decorate
+
+
+__all__ = ["resource", "Resource"]

codepact/contracts.py

@@ -0,0 +1,43 @@
+"""Typing metadata understood by the CodePact source inspector."""
+
+from dataclasses import dataclass
+from typing import Annotated, TypeAlias, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class Resource:
+    """Declared lifecycle metadata; it does not enforce runtime behavior."""
+
+    closed_by: str
+
+
+@dataclass(frozen=True, slots=True)
+class SharedBorrow:
+    """Intent to access a value through a shared borrow."""
+
+
+@dataclass(frozen=True, slots=True)
+class OwnedAccess:
+    """Intent to access or transfer an owned handle."""
+
+
+@dataclass(frozen=True, slots=True)
+class ExclusiveBorrow:
+    """Intent to access a value through an exclusive borrow."""
+
+
+Owned: TypeAlias = Annotated[T, OwnedAccess()]
+Borrowed: TypeAlias = Annotated[T, SharedBorrow()]
+BorrowedMut: TypeAlias = Annotated[T, ExclusiveBorrow()]
+
+__all__ = [
+    "Resource",
+    "SharedBorrow",
+    "OwnedAccess",
+    "ExclusiveBorrow",
+    "Owned",
+    "Borrowed",
+    "BorrowedMut",
+]

codepact/rust.py

@@ -0,0 +1,5 @@
+"""Explicit Rust-inspired annotation spellings for ordinary Python values."""
+
+from .contracts import Borrowed, BorrowedMut, Owned
+
+__all__ = ["Owned", "Borrowed", "BorrowedMut"]

codepact-0.3.0.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: codepact
+Version: 0.3.0
+Summary: Lightweight Python contract annotations for CodePact
+Author: CodePact contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: codepact-cli==0.3.0
+Description-Content-Type: text/markdown
+
+# CodePact
+
+CodePact catches conflicting resource declarations and supported lifecycle bugs such as use-after-close and missed cleanup in Python. Its analyzer reads source without importing or running application code.
+
+[![PyPI](https://img.shields.io/pypi/v/codepact.svg)](https://pypi.org/project/codepact/)
+[![CLI on PyPI](https://img.shields.io/pypi/v/codepact-cli.svg?label=CLI)](https://pypi.org/project/codepact-cli/)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](#compatibility)
+[![Quality](https://github.com/eddiethedean/codepact/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/eddiethedean/codepact/actions/workflows/quality.yml)
+[![Documentation](https://readthedocs.org/projects/typepact/badge/?version=latest)](https://typepact.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/eddiethedean/codepact/blob/main/LICENSE)
+
+Declare how resources close and how APIs intend to access them alongside ordinary Python types. CodePact 0.3.0 is a candidate that checks cleanup obligations across supported exits, in addition to use-after-close. It is not published yet. The previously published 0.1.0 and 0.2.0 releases used the TypePact name and package names. APIs, diagnostics, and the JSON schema remain provisional during 0.x.
+
+| Task | Command | Availability |
+| --- | --- | --- |
+| Inspect lifecycle and access declarations | `codepact inspect-contracts FILE...` | CodePact 0.3.0 candidate |
+| Check use-after-close and cleanup obligations | `codepact check --root DIR` | CodePact 0.3.0 candidate |
+
+Build the candidate from source using [installation](#install), then follow [contract inspection](#inspect-your-first-contract) or [lifecycle checking](#try-lifecycle-checking-from-source). See the [availability guide](docs/availability.md) for release status and the platform matrix.
+
+## Install
+
+CodePact 0.3.0 has passed its pre-tag qualification; the renamed Python packages and Rust crate have not been published yet. To try this candidate from a checkout:
+
+```sh
+git clone https://github.com/eddiethedean/codepact.git
+cd codepact
+uv sync --locked
+uv run --locked codepact --version
+```
+
+After the maintainer qualifies and publishes 0.3.0, install the helper and its matching CLI dependency with `uv add codepact==0.3.0` or `python -m pip install 'codepact==0.3.0'`.
+
+This installs two matching distributions:
+
+| Distribution | Contents |
+| --- | --- |
+| `codepact` | Pure Python declaration helpers, typing metadata, and `py.typed` |
+| `codepact-cli` | The native Rust `codepact` executable |
+
+`codepact` pins `codepact-cli` to the same version. Importing the Python helpers does not start the analyzer or download an executable. Prebuilt CLI wheels require no Rust compiler; building the CLI from source requires Rust 1.96 or newer and a linker.
+
+For the command alone after publication:
+
+```sh
+uv tool install codepact-cli==0.3.0
+codepact --version
+```
+
+## Inspect your first contract
+
+Save this as `connection.py`:
+
+```python
+from codepact import resource
+from codepact.rust import Borrowed, Owned
+
+
+@resource(closed_by="close")
+class Connection:
+    def close(self) -> None:
+        pass
+
+
+def read(conn: Borrowed[Connection]) -> str:
+    return "ready"
+
+
+def consume(conn: Owned[Connection]) -> None:
+    conn.close()
+```
+
+Inspect its declarations:
+
+```sh
+uv run codepact inspect-contracts connection.py
+```
+
+CodePact emits JSON containing these contract views:
+
+| Declaration | Base type | Lifecycle | Access intent |
+| --- | --- | --- | --- |
+| `Connection` | `connection.Connection` | Closed by `close` | Unspecified |
+| `read.conn` | `connection.Connection` | Closed by `close` | Shared |
+| `consume.conn` | `connection.Connection` | Closed by `close` | Owned |
+
+The `resource` decorator preserves the class identity and records lifecycle metadata. The inspector reads the file as text without importing it, evaluating annotations, or invoking decorators. In the historical TypePact 0.1.0 release, method bodies were not checked: declaring `closed_by="close"` did not establish that `close` releases anything.
+
+The inspector also rejects conflicting declarations. The
+[TP4002 example](docs/rules.md#example-conflicting-lifecycle-metadata) shows a
+resource alias that declares a different close method, the reported locations,
+and a valid repair. Use the `check` command below for lifecycle findings.
+
+See the complete [paired example](https://github.com/eddiethedean/codepact/blob/main/examples/contracts.py) and its [JSON snapshot](https://github.com/eddiethedean/codepact/blob/main/tests/snapshots/example-contracts.json).
+
+## Try lifecycle checking from source
+
+The TypePact 0.2.0 checker remains available from its historical tag. For the CodePact 0.3.0 candidate, use Rust 1.96+ and build the current checkout:
+
+```sh
+git clone https://github.com/eddiethedean/codepact.git
+cd codepact
+uv sync --locked
+uv run --locked codepact check --root examples
+```
+
+Record `git rev-parse HEAD` with candidate results.
+
+The [lifecycle example](https://github.com/eddiethedean/codepact/blob/main/examples/lifecycle.py) constructs a connection, passes it to a Borrowed helper, closes it, then calls the helper again. The final call produces a definite `TP1001`, includes the close location, and exits with status `1`. This example intentionally contains an error.
+
+The checker follows supported normal synchronous flow, local aliases, direct calls, and `if`/`else` joins. It also reports closing a `Borrowed` parameter as `TP2001`. Possible findings and incomplete coverage are visible warnings that can accompany exit `0`; read the report even when the command succeeds.
+
+Follow the [lifecycle tutorial](https://typepact.readthedocs.io/en/latest/lifecycle.html) for an isolated example, expected output, and a valid counterpart. The checker does not establish leak freedom, cleanup on every exit, general ownership safety, or that the declared close method releases a runtime resource. Release status and supported behavior are summarized in the [availability guide](docs/availability.md).
+
+## Annotation forms
+
+The access aliases use `typing.Annotated`, so ordinary Python type checkers retain the underlying type:
+
+| Alias from `codepact.rust` | Metadata from `codepact.contracts` | Intent |
+| --- | --- | --- |
+| `Borrowed[T]` | `Annotated[T, SharedBorrow()]` | Shared access |
+| `Owned[T]` | `Annotated[T, OwnedAccess()]` | Owned access |
+| `BorrowedMut[T]` | `Annotated[T, ExclusiveBorrow()]` | Exclusive access |
+
+For example, `Borrowed[Connection]` and `Annotated[Connection, SharedBorrow()]` produce the same shared-access facts. The aliases are also exported from `codepact.contracts`.
+
+You can attach lifecycle and access metadata to an alias of an existing class:
+
+```python
+from typing import Annotated
+
+from codepact.contracts import Resource, SharedBorrow
+
+
+ConnectionView = Annotated[
+    Connection,
+    Resource(closed_by="close"),
+    SharedBorrow(),
+]
+```
+
+Here, `Connection` is the class from the quick start. Metadata on an alias describes that view; it does not change every use of the underlying class. CodePact combines compatible lifecycle and access declarations and reports conflicting values with their source locations. These annotations express intent; they do not enforce ownership or borrowing at runtime.
+
+## Inspecting a project
+
+Choose a source target explicitly when needed. The default is Python 3.11:
+
+```sh
+uv run codepact inspect-contracts --python-version 3.13 connection.py
+```
+
+For imports between files, pass every module that should participate in resolution. For a project with a `src` directory:
+
+```sh
+uv run codepact inspect-contracts --root src src/models.py src/client.py
+```
+
+For `inspect-contracts`, `--root` determines logical paths and package-qualified module names without discovering files. Without it, each input file's stem supplies its module name. Absolute `from module import Class` imports and direct imports of supported assignment aliases resolve across supplied files. The `check` command instead scans `.py` files below its root; explicit filenames add inputs and do not restrict that scan.
+
+### Inspection output and exit codes
+
+JSON is the default output; `--json` is accepted explicitly. Each result includes:
+
+- `contracts`: normalized base symbols, lifecycle and access facts, source spans, and declaration provenance.
+- `diagnostics`: errors and unsupported-boundary findings, including related locations where applicable.
+- `coverage`: `complete-for-supported-subset` or `incomplete`, with reasons and work counts.
+- `schema_version: 0` and `assurance: "contract-inspection-only"`.
+
+Contract provenance is `declared-unverified`. Line and column numbers are one-based; columns count UTF-8 bytes.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Inspection completed with no declaration errors or incomplete coverage |
+| `1` | Declaration errors, syntax errors, or unsupported/unresolved constructs were reported |
+| `2` | An invocation, file access, input limit, or fatal execution error prevented inspection |
+
+A successful inspection establishes the recorded declarations within the supported subset. It does not prove resource safety.
+
+## Scope of the original 0.1 release
+
+The inspector supports module-level classes, literal CodePact resource decorators, simple assignment aliases, parameter and return annotations, and direct absolute imports among explicitly supplied modules. It resolves supported API imports by identity, respects local rebinding, and preserves the class and metadata captured by earlier aliases.
+
+Relevant unsupported constructs produce incomplete coverage. Current boundaries include:
+
+- String annotations and `from __future__ import annotations`.
+- Relative imports, star imports, import re-export chains, and supplied-module cycles.
+- Class inheritance and metaclass behavior, other class decorators, and decorated functions.
+- Computed contract expressions, dynamic decorator arguments, and eager named expressions that could rebind module names.
+- Module-level control flow and unsupported nested or generic declarations.
+
+The inspector has explicit source and work limits, including a 1,000,000-byte total source budget per request. See the [inspector guide](https://github.com/eddiethedean/codepact/blob/main/docs/inspector.md) for the detailed limits and Rust session API.
+
+The historical TypePact 0.2.0 release added bounded lifecycle flow checks. The CodePact 0.3.0 candidate adds cleanup obligations across supported exits. General ownership enforcement and precise alias analysis through fields and containers remain future work. The [release roadmap](https://github.com/eddiethedean/codepact/blob/main/ROADMAP.md) describes that progression.
+
+## Compatibility
+
+| Surface | Support |
+| --- | --- |
+| Python helper runtime | Python 3.11+; CI covers CPython 3.11–3.14 |
+| Analyzed Python source targets | 3.11, 3.12, and 3.13 |
+| Python typing | Inline types and `py.typed`; compatibility fixtures for mypy and Pyright |
+| Rust source builds | Rust 1.96+ |
+
+The release configuration defines eight native CLI wheel targets. The current
+candidate's build and install evidence is recorded in the
+[availability guide](docs/availability.md):
+
+| Platform | x86-64 | ARM64 |
+| --- | --- | --- |
+| Linux glibc | glibc 2.17+ | glibc 2.28+ |
+| Linux musl | musl 1.2+ | musl 1.2+ |
+| macOS | 10.13+ | 11.0+ |
+| Windows | Supported | Supported |
+
+The helper wheel is universal pure Python. CLI wheels contain a standalone executable and do not depend on a particular CPython ABI. Identifier validation follows the Unicode rules of the selected source target. See [compatibility](https://github.com/eddiethedean/codepact/blob/main/docs/planning/compatibility.md) and [distribution details](https://github.com/eddiethedean/codepact/blob/main/docs/planning/releases.md) for the complete policy.
+
+## Architecture
+
+The Python helpers supply declarations; the Rust engine performs inspection. Pinned Ruff parser and AST components provide structured syntax and source ranges. Salsa tracks parsing and module semantics so reusable sessions can retain unaffected work across edits.
+
+The Rust `codepact` crate exposes `inspect` for a single request and `AnalysisSession` for repeated updates, removal, reset, cancellation, and revision-tagged results. The candidate adds `check` and versioned `check_report` methods. CLI and library calls share the analyzer; the host application supplies the Rust API's source snapshot. See the [Rust API guide](https://typepact.readthedocs.io/en/latest/rust-api.html) and [analyzer design](https://github.com/eddiethedean/codepact/blob/main/docs/planning/analyzer-migration.md).
+
+## Development
+
+Use a source checkout with `uv`, Rust 1.96+, rustfmt, Clippy, and Make. Install the pinned dependency auditors, then run the full local gate:
+
+```sh
+uv sync --locked
+cargo install cargo-audit --version 0.22.2 --locked
+cargo install cargo-deny --version 0.20.2 --locked
+uv run --locked make check
+```
+
+`make check` covers Rust formatting, compilation, Clippy, tests, MSRV validation, dependency audits, strict Python typing and linting, identifier-table verification, package builds and clean installation checks, and the inspector's execution guard. GitHub Actions runs the Python checks on 3.11–3.14 alongside the Rust and dependency checks.
+
+Run the repository example from the checkout:
+
+```sh
+uv run --locked codepact inspect-contracts --root . examples/contracts.py
+```
+
+See [CONTRIBUTING.md](https://github.com/eddiethedean/codepact/blob/main/CONTRIBUTING.md) for focused check targets and contribution guidance.
+
+## Documentation
+
+- [Full documentation](https://typepact.readthedocs.io/en/latest/): installation, quick start, adoption guidance, APIs, CLI, output, examples, security, and support.
+- [Documentation source](https://github.com/eddiethedean/codepact/tree/main/docs): guides in the repository if the hosted site is unavailable.
+- [Release and capability availability](docs/availability.md): published versions, capabilities, and platform support.
+- [Inspector guide](https://github.com/eddiethedean/codepact/blob/main/docs/inspector.md): supported syntax, output, limits, and sessions.
+- [Release roadmap](https://github.com/eddiethedean/codepact/blob/main/ROADMAP.md): the planned 0.1–0.9 sequence.
+- [Product vision](https://github.com/eddiethedean/codepact/blob/main/docs/planning/vision.md): goals and intended use cases.
+- [Limitations](https://github.com/eddiethedean/codepact/blob/main/docs/planning/limitations.md): analysis and assurance boundaries.
+- [Planning index](https://github.com/eddiethedean/codepact/blob/main/docs/planning/README.md): architecture, decisions, and future feature specifications.
+
+## License
+
+CodePact is distributed under the [MIT license](https://github.com/eddiethedean/codepact/blob/main/LICENSE).

codepact-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+codepact/__init__.py,sha256=YbdVn_mPhKD5BE5jxUreivh_z5vQeRZ0vZaV9wIbaiU,1305
+codepact/contracts.py,sha256=JG_oAr-BKe3eQCNBesVnG_vRrZCAXwuEKkhB6OgAOJ4,974
+codepact/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codepact/rust.py,sha256=5vXUiak9pwpBoeXfDsWsG0T1zypRsK26N_1KMA1zTQw,179
+codepact-0.3.0.dist-info/METADATA,sha256=6Vl5aYuhsLIbaGY2UV9BPZ-17j8cMAB9U9qpD50lLYo,15609
+codepact-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+codepact-0.3.0.dist-info/licenses/LICENSE,sha256=nJMBezhW0j3KUlx1iwat9hNwf-Z-pUATMiuDQxD9FHo,1078
+codepact-0.3.0.dist-info/RECORD,,

codepact-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codepact-0.3.0.dist-info/licenses/LICENSE

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