AX - AST-Based Code Consistency Checker

Keep your codebase consistent across multiple languages using pure algorithmic analysis

AX is an intelligent code consistency checker and fixer that helps maintain consistent coding patterns across your entire project. It uses pure AST-based analysis with advanced algorithms to identify inconsistencies, logical errors, security issues, and performance problems.

Features

• Cross-File Consistency Analysis: Learns patterns from your project and ensures consistency
• Multi-Language Support: Python, JavaScript, TypeScript, Java, Go, Rust, and more
• Pure AST Analysis: Uses abstract syntax tree parsing for reliable detection
• Auto-Fix Capabilities: Automatically fixes issues with configurable confidence thresholds
• Logical Error Detection: Finds bugs like missing operators, unreachable code, infinite loops
• Security Scanning: Detects hardcoded secrets, SQL injection risks, unsafe deserialization
• Performance Analysis: Identifies N+1 queries, inefficient loops, unnecessary conversions
• Interactive Fixes: Review and approve fixes with diff preview
• Project-Wide Learning: Automatically detects and enforces your team's coding patterns
• Fast and Efficient: Pure algorithmic approach with caching for speed

What AX Checks

Consistency Issues

• Naming conventions (snake_case vs camelCase)
• None/Null checking patterns (is None vs == None)
• Type hint usage consistency
• Error handling patterns (exceptions vs return values)
• Import styles
• String quote preferences
• Docstring conventions

Logical Errors

• Missing augmented operators (x = x + 1 vs x += 1)
• Incorrect comparisons
• Unreachable code after return/raise
• Infinite loops without break
• Loop variable modifications
• Missing return statements
• Unused variables
• Off-by-one errors

Security Issues

• Hardcoded secrets (API keys, passwords, tokens)
• SQL injection vulnerabilities
• Command injection risks
• Unsafe deserialization (pickle)
• Weak cryptography (MD5, SHA1)
• Unsafe eval/exec usage
• Missing file encoding

Performance Problems

• N+1 query patterns
• Inefficient loops (list comprehension opportunities)
• Repeated expensive computations
• Inefficient string concatenation
• Unnecessary type conversions
• Missing caching opportunities

Installation

For Users (PyPI)

pip install axcode

After installation, the ax command will be available globally.

For Development

# Clone the repository
git clone https://github.com/CAVELAB-HK/AX.git
cd AX

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Quick Start

1. Install

pip install axcode

2. Verify Installation

ax --help

3. Analyze and Fix Your Code

# Analyze and fix a single file
ax myfile.py

# Analyze and fix entire project
ax .

# Just analyze without fixing
ax myfile.py --analyze-only

# Auto-fix all high-confidence issues
ax myfile.py --auto

# Fix specific directory recursively
ax ./src --recursive

# Output results as JSON
ax myfile.py --json

4. Use in Your IDE (Optional)

Install the VS Code or Cursor extension for real-time feedback:

• VS Code: Search "AX Consistency" in the marketplace
• Cursor: See extensions documentation (if available)

Usage

CLI Commands

# Analyze and fix files
ax <file_or_directory>        # Analyze and fix interactively
ax <file> --auto              # Auto-fix high-confidence issues
ax <file> --analyze-only      # Just analyze without fixing
ax <file> --json              # Output results in JSON format

# Options
ax <directory> -r             # Recursive (default: true)
ax . --include "*.py"         # Include specific patterns
ax . --exclude "test_*.py"    # Exclude specific patterns

Python API

from pathlib import Path
from ax.core import AnalysisPipeline, FixExecutor

# Initialize pipeline
pipeline = AnalysisPipeline(use_cache=True)

# Analyze a file
project_files = list(Path('.').rglob('*.py'))
result = pipeline.analyze_file(Path('myfile.py'), project_files)

# Generate and apply fixes
issues = result['issues']
fixes = pipeline.generate_fixes(Path('myfile.py'), issues)

executor = FixExecutor()
fix_result = executor.execute_fixes(Path('myfile.py'), fixes, auto=False)

print(f"Found {result['issue_count']} issues")
print(f"Applied {len(fix_result.get('changes', []))} fixes")

Configuration File

Create .axconfig.toml in your project root:

[analysis]
enabled_strategies = [
    "naming",
    "type_hints",
    "imports",
    "docstrings",
    "error_handling",
    "logical_errors",
    "security",
    "performance"
]
auto_fix_threshold = 0.9
interactive_threshold = 0.6
ignore_patterns = [
    "__pycache__/*",
    "*.pyc",
    ".git/*",
    "venv/*",
    "node_modules/*"
]

[cache]
enabled = true
directory = ".ax_cache"

[output]
format = "terminal"
colors = true
verbose = false

Examples

Before AX

def processData(data):
    if data == None:
        return
    total = 0
    password = "secret123"
    for item in items:
        total = total + item
    return total

After AX Fix

def process_data(data):
    if data is None:
        return
    total = 0
    password = os.getenv('PASSWORD')
    for item in items:
        total += item
    return total

IDE Extensions

VS Code Extension

1. Install from marketplace: "AX Consistency"
2. Or install manually: code --install-extension extensions/vscode-ax/ax-consistency-1.0.0.vsix
3. Configure in settings (Cmd/Ctrl + ,):
   • ax.enabled: Enable/disable extension
   • ax.autoCheckOnSave: Check files on save
   • ax.autoFix: Automatically fix issues

Keyboard Shortcuts:

• Cmd/Ctrl + Shift + A: Analyze current file
• Cmd/Ctrl + Shift + F: Fix current file

Cursor Extension

See extensions/cursor-ax/INSTALL_CURSOR.md for installation instructions.

Architecture

AX uses a pure AST-based architecture:

1. AST Parsing: Uses abstract syntax tree parsing for reliable pattern detection
2. Pattern Learning: Learns dominant patterns from your project automatically
3. Strategy System: Pluggable strategies for different types of checks (naming, logical errors, security, performance)
4. Smart Caching: Caches results to avoid redundant analysis
5. Fix Generation: Generates fixes with confidence scores for safe automated fixes

Development

Project Structure

AX/
├── ax/                      # Core package
│   ├── cli/                # CLI interface
│   ├── core/               # Core analysis engine
│   │   ├── pipeline.py     # AST-based pipeline
│   │   ├── parser.py       # AST parser
│   │   ├── fix_executor.py # Fix application engine
│   │   └── pattern_learner.py  # Pattern detection
│   ├── strategies/         # Analysis strategies
│   │   ├── naming.py
│   │   ├── logical_errors.py
│   │   ├── security.py
│   │   └── performance.py
│   ├── models/            # Data models
│   └── utils/             # Utility functions
├── extensions/             # IDE extensions
│   ├── vscode-ax/         # VS Code extension
│   └── cursor-ax/         # Cursor extension
└── tests/                 # Test suite

Running Tests

pytest tests/

Building Extensions

# VS Code extension
cd extensions/vscode-ax
npm install
npm run compile
npm run package

# Cursor extension
cd extensions/cursor-ax
npm install
npm run compile

Publishing to PyPI

First Time Setup

1. Create accounts on PyPI and TestPyPI
2. Install build tools:

   pip install build twine
   

Publishing Process

# 1. Update version in pyproject.toml
# 2. Build distribution
python -m build

# 3. Test on TestPyPI (optional)
python -m twine upload --repository testpypi dist/*

# 4. Publish to PyPI
python -m twine upload dist/*

After Publishing

Users can install with:

pip install ax-consistency

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Troubleshooting

"AX CLI not found"

Make sure AX is installed and in your PATH:

pip install axcode
# Or for development:
pip install -e /path/to/AX

Extension Not Working

1. Check that AX CLI is installed: ax --version
2. Check extension settings in VS Code
3. Restart VS Code/Cursor
4. Check the extension output panel for errors

Analysis Too Slow

1. Enable caching in .axconfig.toml
2. Add ignore patterns for large dependencies
3. Use --include flag to focus on specific file patterns

License

MIT License - see LICENSE file for details

Authors

• CAVELAB-HK (contact@cavelab.dev)

Links

• GitHub: https://github.com/CAVELAB-HK/AX
• Issues: https://github.com/CAVELAB-HK/AX/issues
• Documentation: https://github.com/CAVELAB-HK/AX/wiki
• Discussions: https://github.com/CAVELAB-HK/AX/discussions

Contributing

Found a bug or have a feature request? Please open an issue on GitHub!

Acknowledgments

AX is built with:

• Python's built-in AST module for parsing
• Rich for beautiful terminal output
• Typer for CLI interface
• Advanced algorithmic analysis for reliable detection