pycoati

Audits Python test suites for mock smells and suspicious tests. Walks a project with tree-sitter, optionally runs pytest for collection, durations, and coverage, and emits a structured inventory: per-file and per-test counts, mock-API smells, and a per-test suspicion score.

Install

# From source (Rust)
cargo install --path .

# Or as a Python package (via maturin)
maturin develop

Usage

pycoati --help

`pycoati <PATH>`

Audit a project directory or a single .py file. Writes the inventory to stdout as JSON unless --output is given.

# Structured inventory to a file
pycoati . --output inventory.json

# Aligned-column terminal view
pycoati . --format pretty

# Static analysis only, no pytest subprocesses
pycoati . --static-only

Key flags: --format <json|pretty>, --output <PATH>, --tests-dir <PATH>, --static-only, --no-coverage, --top-suspicious <N>, --project-package <NAME>, --python <CMD>, --pytest-args <STR>, --member-cwd <root|member>. See pycoati --help for the full list.

Weights behind suspicion_score are documented in WEIGHTS.md.

`pycoati guide [PAGE]`

Prints the workflow instructions that ship inside the binary, aimed at a coding agent working through an audit. Because the pages are embedded at compile time, they always describe the inventory schema this exact build emits.

# Pick the page from the state of the current directory
pycoati guide

# Or ask for one by name
pycoati guide setup
pycoati guide analyze
pycoati guide remediate

Page	Contents
`setup`	Configuration surface, how to run the scan, where `inventory.json` lands.
`analyze`	Field reference for every key in the inventory, plus the anti-pattern taxonomy and its detection heuristics.
`remediate`	The remedy ladder, the human-approval gate, and the "do not" list.

With no argument, the page is chosen from the current directory: analyze when an inventory.json is present there, otherwise setup. remediate is never auto-selected — reach it via the analyze page's breadcrumb or by name.

The subcommand shadows a directory of the same name: if you have a ./guide directory to audit, write pycoati ./guide.

Each page ends with a single next: line, so an agent is always one command away from the right instructions. A --format pretty scan that finds candidates ends with the same breadcrumb; JSON output never carries it.

The page sources are plain markdown under docs/guide/, embedded via include_str!. tests/guide_schema_drift.rs asserts that every field name serde emits is documented on the analyze page, so a schema change cannot land without the guide being updated alongside it.

Development

# Pre-commit checks
cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test --all-features

# Full review (fmt, clippy, tests, audit, deny)
make review

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycoati-0.2.7.tar.gz (145.0 kB view details)

Uploaded Sep 6, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pycoati-0.2.7-py3-none-win_amd64.whl (1.5 MB view details)

Uploaded Sep 6, 2026 Python 3Windows x86-64

pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Sep 6, 2026 Python 3manylinux: glibc 2.28+ x86-64

pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded Sep 6, 2026 Python 3macOS 11.0+ ARM64

File details

Details for the file pycoati-0.2.7.tar.gz.

File metadata

Download URL: pycoati-0.2.7.tar.gz
Upload date: Sep 6, 2026
Size: 145.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pycoati-0.2.7.tar.gz
Algorithm	Hash digest
SHA256	`8479936109209afdf897576fab87b0a09b6d426815853db5f443583ba0d29d19`
MD5	`04b240d1f22b0e99b4d88bc97f166190`
BLAKE2b-256	`734832a8a15278bf6d9fd32ae649988196f80a3fe7713fc9a239e0defa284e3b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pycoati-0.2.7.tar.gz:

Publisher: release.yml on mojzis/pycoati

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pycoati-0.2.7.tar.gz
- Subject digest: 8479936109209afdf897576fab87b0a09b6d426815853db5f443583ba0d29d19
- Sigstore transparency entry: 2737415255
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: mojzis/pycoati@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Branch / Tag: refs/tags/v0.2.7
- Owner: https://github.com/mojzis
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Trigger Event: push

File details

Details for the file pycoati-0.2.7-py3-none-win_amd64.whl.

File metadata

Download URL: pycoati-0.2.7-py3-none-win_amd64.whl
Upload date: Sep 6, 2026
Size: 1.5 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pycoati-0.2.7-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`55923c3450026564925b2cde9784aae9bcf7642281c9662368dcfc6f903bc01f`
MD5	`bf492e59f7238836e493d99aac6071a0`
BLAKE2b-256	`0421c1b336047dd795cac09c1f95d7d57d04c66bc30fe4fa5afc51fbbe1804f3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pycoati-0.2.7-py3-none-win_amd64.whl:

Publisher: release.yml on mojzis/pycoati

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pycoati-0.2.7-py3-none-win_amd64.whl
- Subject digest: 55923c3450026564925b2cde9784aae9bcf7642281c9662368dcfc6f903bc01f
- Sigstore transparency entry: 2737415433
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: mojzis/pycoati@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Branch / Tag: refs/tags/v0.2.7
- Owner: https://github.com/mojzis
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Trigger Event: push

File details

Details for the file pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl.

File metadata

Download URL: pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl
Upload date: Sep 6, 2026
Size: 1.6 MB
Tags: Python 3, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`83dcf7fee42e6b57720e9866526798a4a5f33053584e712818f151e593d523d2`
MD5	`9e99cd8b8f78e5ad5956afb4ef0a3f72`
BLAKE2b-256	`5f56a5ac29ba05decede07697cf016c3de438205a1223dae2df424f46d223745`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on mojzis/pycoati

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pycoati-0.2.7-py3-none-manylinux_2_28_x86_64.whl
- Subject digest: 83dcf7fee42e6b57720e9866526798a4a5f33053584e712818f151e593d523d2
- Sigstore transparency entry: 2737415498
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: mojzis/pycoati@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Branch / Tag: refs/tags/v0.2.7
- Owner: https://github.com/mojzis
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Trigger Event: push

File details

Details for the file pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl
Upload date: Sep 6, 2026
Size: 1.4 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`9599833af88090e77025131a9903abcec274aadfe445cb8ef27c29e50b32fa68`
MD5	`9b5d29e5ad07ee71cf56f81cfbd8ed8b`
BLAKE2b-256	`9277428eb4adaa1e975d81bca60b18b373ec867301a643e5cde76eef8364aa60`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on mojzis/pycoati

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pycoati-0.2.7-py3-none-macosx_11_0_arm64.whl
- Subject digest: 9599833af88090e77025131a9903abcec274aadfe445cb8ef27c29e50b32fa68
- Sigstore transparency entry: 2737415370
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: mojzis/pycoati@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Branch / Tag: refs/tags/v0.2.7
- Owner: https://github.com/mojzis
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53d8542de2009ddba3ec81b851df16c5dde3ccd3
- Trigger Event: push