prefact

AI Cost Tracking

PyPI Version Python License AI Cost Human Time Model

🤖 LLM usage: $5.8500 (39 commits)
👤 Human dev: ~$1289 (12.9h @ $100/h, 30min dedup)

Generated on 2026-04-09 using openrouter/qwen/qwen3-coder-next

Automatic Python prefactoring toolkit — detect, fix, and validate common code issues introduced by LLMs and humans alike.

The Problem

When using LLMs for code generation, they often silently change import paths from absolute to deep relative:

# ❌ LLM introduces this
from ....llm.generator import generate_strategy
from ....loaders.yaml_loader import save_strategy_yaml

# ✅ You wanted this
from planfile.llm.generator import generate_strategy
from planfile.loaders.yaml_loader import save_strategy_yaml

prefact automatically detects, fixes, and validates such issues in a three-phase pipeline.

Features

Rule	ID	Auto-fix	Description
Relative → Absolute imports	`relative-imports`	✅	Converts `from ....x import y` to `from pkg.x import y`
Unused imports	`unused-imports`	✅	Removes imports never referenced in the module
Duplicate imports	`duplicate-imports`	✅	Removes the same name imported twice
Wildcard imports	`wildcard-imports`	🔍	Flags `from x import *`
Unsorted imports	`sorted-imports`	🔍	Flags import blocks not ordered stdlib→3rd-party→local
String concatenation	`string-concat`	🔍	Flags `"Hello " + name` → suggests f-strings
Missing return types	`missing-return-type`	🔍	Flags public functions without return type hints

✅ = auto-fix · 🔍 = scan-only (report)

Performance Improvements

Parallel Processing: Scans files in parallel when enabled
Smart Filtering: Automatically skips large files (>100KB) and empty files
Optimized Scanning: Excludes test directories and examples by default
Deduplication: Prevents duplicate tickets and TODO entries

Examples

The examples/ directory contains comprehensive examples for different use cases:

Example	Description
sample-project	Realistic project with all issues demonstrated
01-individual-rules	Each rule explained with before/after code
02-multiple-rules	Combining multiple rules for comprehensive cleanup
03-output-formats	Console vs JSON output examples
04-custom-rules	Writing your own prefactoring rules
05-ci-cd	GitHub Actions, GitLab CI, Azure DevOps configs
06-api-usage	Using prefact programmatically from Python

Quick Example

# Try the sample project
cd examples/sample-project
prefact scan --path . --config prefact.yaml
prefact fix --path . --config prefact.yaml

See examples/README.md for a detailed guide to all examples.

Installation

pip install -e .

# with dev dependencies (pytest)
pip install -e ".[dev]"

Quick Start

# Generate config file
prefact init

# List all available rules
prefact rules

# Scan only (no changes)
prefact scan --path ./my_project --package mypackage

# Fix + validate (with backups)
prefact fix --path ./my_project --package mypackage

# Dry-run (show what would change)
prefact fix --path ./my_project --package mypackage --dry-run

# Check a single file
prefact check ./my_project/src/mypackage/core/service.py --package mypackage

# JSON output for CI
prefact fix --path . --format json -o report.json

📚 Want to see prefact in action? Check out our comprehensive examples with real-world scenarios!

Pipeline Architecture

┌─────────┐      ┌─────────┐      ┌────────────┐
│  SCAN   │ ──→  │   FIX   │ ──→  │  VALIDATE  │
│         │      │         │      │            │
│ Detect  │      │ Apply   │      │ Syntax OK? │
│ issues  │      │ fixes   │      │ Regressions│
│ per rule│      │ + backup│      │ preserved? │
└─────────┘      └─────────┘      └────────────┘

Scan — each rule walks the AST / CST and emits Issue objects
Fix — rules with auto-fix transform the source (via libcst for formatting-safe changes)
Validate — post-fix checks: syntax valid, no regressions, import counts preserved

Configuration

Create prefact.yaml (auto-generated via prefact init):

package_name: planfile

include:
  - "**/*.py"

exclude:
  - "**/venv/**"
  - "**/build/**"
  - "**/tests/**"
  - "**/test*/**"
  - "**/examples/**"

tools:
  parallel: true
  cache: true
  performance:
    max_workers: 4

rules:
  relative-imports:
    enabled: true
    severity: warning
  unused-imports:
    enabled: true
    severity: info
  duplicate-imports:
    enabled: true
  wildcard-imports:
    enabled: true
    severity: error
  sorted-imports:
    enabled: false
  string-concat:
    enabled: true
  missing-return-type:
    enabled: false

Autonomous Mode

Prefact includes an autonomous mode that automatically:

Scans your project for issues
Generates TODO.md with all found issues
Creates tickets in planfile.yaml for tracking
Updates CHANGELOG.md with fixes

# Run full autonomous workflow
prefact -a

# Or skip tests/examples for faster runs
prefact -a --skip-tests --skip-examples

Performance Improvements

Recent updates have significantly improved performance:

Parallel Processing: Scans files using multiple workers (configurable)
Smart Filtering: Skips large files (>100KB) and files with minimal content
Optimized Exclusions: Automatically excludes test directories and examples
Deduplication: Prevents duplicate tickets and TODO entries across runs

Python API

from pathlib import Path
from prefact.config import Config
from prefact.engine import RefactoringEngine

config = Config(
    project_root=Path("./my_project"),
    package_name="planfile",
    dry_run=False,
    backup=True,
)

engine = RefactoringEngine(config)
result = engine.run()

print(f"Found {result.total_issues} issues")
print(f"Fixed {result.total_fixed}")
print(f"All valid: {result.all_valid}")

Writing Custom Rules

Extend BaseRule and use the @register decorator:

from prefact.rules import BaseRule, register
from prefact.models import Issue, Fix, ValidationResult

@register
class MyCustomRule(BaseRule):
    rule_id = "my-custom-rule"
    description = "Does something useful."

    def scan_file(self, path, source):
        # Return list[Issue]
        ...

    def fix(self, path, source, issues):
        # Return (fixed_source, list[Fix])
        ...

    def validate(self, path, original, fixed):
        # Return ValidationResult
        ...

CI/CD Integration

# GitHub Actions
- name: prefact check
  run: |
    pip install ./prefact
    prefact scan --path . --format json -o prefact-report.json
    prefact fix --path . --dry-run

Running Tests

pip install -e ".[dev]"
pytest -v

License

Licensed under Apache-2.0.

Author

Tom Sapletta

Download files

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

Source Distribution

prefact-0.1.36.tar.gz (107.6 kB view details)

Uploaded Apr 9, 2026 Source

Built Distribution

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.

prefact-0.1.36-py3-none-any.whl (134.3 kB view details)

Uploaded Apr 9, 2026 Python 3

File details

Details for the file prefact-0.1.36.tar.gz.

File metadata

Download URL: prefact-0.1.36.tar.gz
Upload date: Apr 9, 2026
Size: 107.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for prefact-0.1.36.tar.gz
Algorithm	Hash digest
SHA256	`1422b69765cc4e39513dcdd971520fb72af58917046f108868905e89831d7cf7`
MD5	`f4d32ac898e776922ff18c7923e0dfc9`
BLAKE2b-256	`ae983ead3706d6d4b5b586033d67ade593d3c6c3d734c411ac178a26b8bf3bc9`

See more details on using hashes here.

File details

Details for the file prefact-0.1.36-py3-none-any.whl.

File metadata

Download URL: prefact-0.1.36-py3-none-any.whl
Upload date: Apr 9, 2026
Size: 134.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for prefact-0.1.36-py3-none-any.whl
Algorithm	Hash digest
SHA256	`85b15b1a0cacf8a64dad64886cead53f0c3fa3918a78572208d5cdb50b3aaa13`
MD5	`ea594e0709852c9e51f907742699034b`
BLAKE2b-256	`9e867294418ee5da6e3807c885f178f1c199142c7bd6f86b0f99d08d13dc0ccc`