Aposlop

Apos, the Slopbreaker

Slop always rolls downhill. Aposlop helps to push back.

Aposlop is a fast command-line tool. It finds duplicate code and calculates cyclomatic complexity.

Aposlop supports Go, Rust, Python, TypeScript, and TSX. Aposlop uses Tree-sitter to parse each supported language.

Documentation: https://aposlop.ezygang.digital/

Source Code: https://github.com/EzyGang/aposlop

Issues: https://github.com/EzyGang/aposlop/issues

Table of Contents

• Why Aposlop?
• Installation
• Quick Start
• Core Features
  • Duplicate Detection
  • Cyclomatic Complexity
  • Language Support
  • Output Formats
  • Manual Exclusions
• Configuration
• CLI Quick Reference
• Contributing
• License

Why Aposlop?

Aposlop exists to find code slop from coding agents.

Coding agents can generate duplicate code and add complex control flow. These changes can enter a project faster than a reviewer can find them.

Text comparison does not find a duplicate after an agent renames identifiers or changes literals. A linter does not find repeated logic in different files or languages. A complexity limit does not identify repeated logic.

Aposlop uses exact, normalized, and verified near-miss duplicate detection. It also calculates cyclomatic complexity for each code block.

Aposlop is fast enough for an agent validation loop. You can configure thresholds for each language and file extension. You can also exclude paths or accept specific findings. These controls let a project accept known findings and continue development.

Installation

Install script on Linux or macOS

Install cosign. Then run the installer:

curl -fsSLo install.sh https://github.com/EzyGang/aposlop/releases/latest/download/install.sh
sh install.sh

Install script on Windows

Install cosign. Then run the installer:

Invoke-WebRequest https://github.com/EzyGang/aposlop/releases/latest/download/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Both scripts verify the archive checksum and Sigstore signatures.

Cargo

Install Aposlop from crates.io:

cargo install aposlop --locked

PyPI with uv

Install Aposlop as a global tool:

uv tool install aposlop

Run Aposlop without installing it:

uvx aposlop --help

Homebrew

Install Aposlop from the EzyGang Homebrew tap:

brew install EzyGang/tap/aposlop

From source

Install Aposlop from source. A stable Rust toolchain must support edition 2024.

git clone https://github.com/EzyGang/aposlop.git
cd aposlop
cargo install --path . --locked

Verify the installation:

aposlop --version
aposlop --help

Agent skill

Install the Aposlop skill for supported coding agents:

npx skills@latest add EzyGang/aposlop --skill aposlop

The skill teaches agents how to configure Aposlop, inspect findings, and add Aposlop to validation workflows. The skill does not install the Aposlop binary.

Update checks

Aposlop checks for a new GitHub release during interactive runs. It performs a network request at most once every 24 hours. It stores the latest result in the user cache directory. Non-interactive commands do not perform this check.

Set this environment variable to disable the check:

APOSLOP_NO_UPDATE_CHECK=1 aposlop .

Quick Start

Analyze the current directory:

aposlop .

Show the source for each duplicate:

aposlop . --terminal-output code

Run CI validation:

aposlop ci .

The ci command returns exit code 1 when a finding remains.

Write the complete report as JSON:

aposlop . --format json > aposlop-report.json

Read the full quick-start guide.

Core Features

Duplicate Detection

A block enters analysis when it meets the line and named-node limits.

Aposlop classifies block relations in this order:

1. Type-1 requires identical canonical syntax.
2. Type-2 allows different identifiers and literals.
3. Type-3 requires a Jaccard similarity at or above the configured threshold.

Aposlop reports each connected set of duplicate relations as one group. Two blocks do not match when either contains the other in the same file. A TypeScript block can match a TSX block.

Read the duplicate model.

Cyclomatic Complexity

Each valid block has an initial complexity score of 1. Aposlop adds one for each language-specific decision. Decisions include branches, loops, alternatives, exception paths, conditional expressions, and short-circuit operations.

A nested block has an independent score. Nested blocks include functions, closures, lambdas, field initializers, and static blocks.

A violation requires:

score > complexity_threshold

Read the complexity model.

Language Support

Aposlop ignores unsupported extensions. Aposlop follows standard ignore files such as .gitignore.

Read the language guides.

Output Formats

The terminal report is the default. It contains duplicate groups, complexity findings, diagnostics, and a summary.

aposlop . --format terminal

The JSON report contains the complete report and its schema version.

aposlop . --format json

The ci command shows only the status and finding counts.

aposlop ci .

Read the output guide.

Manual Exclusions

Aposlop assigns a deterministic five-character ID to each duplicate group or complexity finding.

Add a finding to the manual exclusions:

aposlop allow aB7_x

The command writes the ID to .aposlopignore. Delete the ID from that file to restore the finding. Aposlop reports valid IDs that match no current finding as unused ignores at the end of each report. Unused ignores do not change the process exit code.

Configuration

Aposlop reads <PATH>/.aposlop.toml. Aposlop uses built-in values when this file does not exist.

[core]
min_lines = 5
min_nodes = 30
exclude = ["tests/", "vendor/", "node_modules/", "target/"]
use_cache = true

[duplicates_detection]
type_1 = true
type_2 = true
type_3 = true
type_3_threshold = 0.85

[metrics]
calculate_complexity = true
complexity_threshold = 15

Each exclude value uses the same pattern syntax as one .gitignore line. A directory pattern such as tests/ matches that directory name at any depth. Patterns can use / for root anchoring and ** for recursive directory matching.

Language and extension tables can override the core values. Command-line values override all configuration-file values.

Read the configuration guide.

CLI Quick Reference

Read the complete CLI reference.

Contributing

Open a GitHub issue to discuss a large change. Then open a pull request.

Run these checks before you submit the pull request:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo run -- --help

License

You can use Aposlop under either license:

• MIT
• Apache License 2.0