Metadata-Version: 2.4
Name: mir-linter
Version: 0.1.0a1
Summary: Mitchell's Ineffable Rules (IR) Linter - A modular linter with customizable rules for SQL, Java, and XML.
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0

# Mitchell's Ineffable Rules (IR) Linter

A highly modular, extensible linting and auto-fixing utility for **SQL, Java, and XML** codebase assets. The linter can be run locally via `uv` / `python`, inside a containerized **Docker** execution loop, or integrated into your lifecycle as a **Git Pre-commit Hook**.

---

## Features

- **Extensible Rules Architecture**: Add language rules simply by adding Python rule modules under `mir/rules/<language>/`.
- **User Styling Guides**: Detailed style guides explaining each rule, its configuration parameters, auto-fixability, and clean vs. violating examples under `docs/`.
- **Precedence-Aware Configuration**: Merges CLI flags, environment variables, and YAML config file settings:
  $$\text{CLI arguments} > \text{Environment variables} > \text{Config file} > \text{Defaults}$$
- **Granular Disable Comments**:
  - **Single-line disable** (disables a rule for the next non-comment code line):
    - SQL: `-- IR-rule-name`
    - Java: `// IR-rule-name`
    - XML: `<!-- IR-rule-name -->`
  - **Block disable** (disables a rule for a range of lines):
    - SQL: `-- IR-start-rule-name` ... `-- IR-end-rule-name`
    - Java: `// IR-start-rule-name` ... `// IR-end-rule-name`
    - XML: `<!-- IR-start-rule-name -->` ... `<!-- IR-end-rule-name -->`
- **Execution Modes**:
  - `check`: Validates files and reports all errors (default).
  - `fix`: Applies automatic corrections to fixable rules directly to files.
  - `dry-run`: Runs checks and generates unified diffs showing proposed fixes without modifying the source.
  - `verbose`: Prints rule descriptions and the offending lines along with errors.

---

## Directory Structure

```text
.
├── docs/                       # Language-specific Style Guides
│   ├── sql.md                  # SQL style guide & rules
│   ├── java.md                 # Java style guide (placeholder)
│   └── xml.md                  # XML style guide (placeholder)
├── Dockerfile                  # Containerization
├── README.md                   # This instruction manual
├── requirements.txt            # Python dependencies (PyYAML)
├── pre-commit-hook.sh          # Shell hook executing linter via Docker
├── mir/
│   ├── main.py                 # Core CLI Entrypoint
│   ├── engine/                 # Core engine mechanics
│   │   ├── config.py           # Precedence-aware configuration loader
│   │   ├── disabler.py         # Parsing and handling disable comments
│   │   ├── rule_interface.py   # BaseRule & Violation class structures
│   │   ├── rules_loader.py     # Dynamic imports of language rules
│   │   └── runner.py           # Processing workflow (Check, Fix, Dry-Run)
│   └── rules/                  # Language specific rules
│       └── sql/
│           ├── line_length.py  # Checks lines exceeding maximum characters
│           └── keyword_case.py # Enforces and fixes uppercase SQL keywords
└── tests/                      # Suite of unit & integration tests
    ├── test_config.py          # Tests config parser
    ├── test_disabler.py        # Tests comment disabler logic
    ├── test_runner.py          # Tests CLI runner integration
    └── rules/                  # Rule specific tests
        └── sql/
            ├── test_line_length.py
            └── test_keyword_case.py
```

---

## Setup & Local Usage

Ensure you have [uv](https://github.com/astral-sh/uv) or `python` installed.

### 1. Running Tests
You can run the full test suite using `uv`:
```bash
uv run --with pyyaml python -m unittest discover -s tests -p "test_*.py"
```

### 2. Style Guides & Documentation

- **Custom Rules Guide**: Refer to the [Custom Rules Guide](docs/custom_rules.md) for details on writing your own custom linting rules, parameter interfaces, and execution validation.
- **Language Style Guides**: The other language-specific files in the `docs/` folder (such as `docs/sql.md`, `docs/java.md`, and `docs/xml.md`) are **automatically generated by the package** from code metadata. To compile and update these guides in sync with rule source definitions, run:

  ```bash
  # Generate style guides directly inside the 'docs/' directory
  uv run mir/main.py --help docs

  # Generate style guides inside a custom directory name
  uv run mir/main.py --help docs:my_rules_docs
  ```
  This scans all rule modules under `mir/rules/` and compiles the style guide markdown files directly.

### 2. Linting execution
```bash
# Check files (default path: current directory)
uv run mir/main.py

# Verbose check on a specific file path
uv run mir/main.py -v path/to/file.sql

# Safe auto-fixing rules on a directory (rewrites matching files)
uv run mir/main.py --fix path/to/file.sql

# Show dry-run diffs
uv run mir/main.py --dry-run path/to/file.sql
```

### 3. Rules CLI Documentation & Help
You can query and inspect the list of rules and details directly from the command line:
```bash
# List all rules across all languages
uv run mir/main.py --help rules

# List only SQL rules
uv run mir/main.py --help rules:sql

# Show detailed documentation & examples for a specific rule across all languages
uv run mir/main.py --help IR-line-length

# Show detailed documentation for a specific rule inside a specific language
uv run mir/main.py --help sql:IR-keyword-case
```

---

## Docker Usage

Build and execute the linter entirely inside a containerized sandbox.

### 1. Build the Docker Image
```bash
docker build -t mitchells-ineffable-rules:latest .
```

### 2. Lint Files via Docker
Mount your workspace volume into `/workspace` in the container:
```bash
# Basic check on the current directory
docker run --rm -v "$(pwd):/workspace" mitchells-ineffable-rules:latest .

# Run auto-fixes
docker run --rm -v "$(pwd):/workspace" mitchells-ineffable-rules:latest --fix .

# Verbose dry-run on a file
docker run --rm -v "$(pwd):/workspace" mitchells-ineffable-rules:latest --dry-run -v query.sql
```

---

## Git Pre-commit Hook Integration

Integrate the linter to block bad code from being committed:

1. Copy the hook script into your repository's hook directory:
   ```bash
   cp pre-commit-hook.sh .git/hooks/pre-commit
   ```
2. Make sure it is executable:
   ```bash
   chmod +x .git/hooks/pre-commit
   ```

When committing files, the hook automatically detects staged SQL, Java, and XML changes, running them through the Docker container before allowing the commit to succeed.

---

## Configuration

You can create an `.ir-config.yaml` file in the root of your project:

```yaml
# Rules to globally disable
disable:
  - IR-some-disabled-rule

# Global flags
verbose: true
fix: false

# External rule directories (to extend or replace built-in rulesets)
include_dirs:
  - /path/to/my/custom_rules

# Rule mode for common languages: "extend" (default, built-in + custom) or "replace" (custom only)
rule_mode: extend

# Individual rule configuration
rules:
  IR-line-length:
    max_length: 120
```

### Rule Configuration Fallbacks

To keep rules independent and decoupled, certain rules can dynamically inherit configuration parameters from other rules if they are not explicitly set. 

For example, the SQL Column Layout formatter (`IR-column-layout`) dynamically falls back to query its parameters from the canonical rule configurations:
- `max_length` is inherited from the Line Length rule (`IR-line-length`)
- `indent_size` is inherited from the Indentation rule (`IR-indent`)

You can override these parameters specifically for the dependent rule or set them once on the canonical rule:
```yaml
rules:
  # Sets line length limit to 80 (affects both IR-line-length and IR-column-layout fallback)
  IR-line-length:
    max_length: 80

  # Specifically overrides column layout to use 100 instead
  IR-column-layout:
    max_length: 100
```

### Order of Precedence

Configuration parameters are merged with the following priority hierarchy (highest overrides lowest):
1. **Command Line Arguments** (e.g. `--fix`, `--disable IR-line-length`, `--include-dir /path`, `--rule-mode replace`)
2. **Environment Variables** (e.g. `IR_FIX=true`, `IR_DISABLE=IR-line-length`, `IR_INCLUDE_DIRS=/path`, `IR_RULE_MODE=replace`)
3. **YAML Config File** (e.g. `disable: [IR-line-length]`, `include_dirs: [/path]`, `rule_mode: replace` inside `.ir-config.yaml`)

---

## Writing Custom Rules

You can write custom rules to run against your codebase, either placing them inside the built-in rules directory or in an external custom rules directory. For full details on class specifications, default parameters, and strict execution validation, refer to the [Custom Rules Guide](docs/custom_rules.md). 

### 1. Built-in Directory
Create your rule Python module under `mir/rules/<language>/my_rule_name.py`.

### 2. External Directory
1. Create a directory structure, e.g. `/my-custom-rules/<language>/my_rule_name.py`.
2. Provide the path to the linter via CLI (`--include-dir /my-custom-rules`), Env (`IR_INCLUDE_DIRS`), or config (`include_dirs: ["/my-custom-rules"]`).
3. Set the `--rule-mode` to specify whether custom rules should **extend** (default) or **replace** the built-in rule sets.

### Custom Rule Implementation Example
Each custom rule must subclass `BaseRule` (from `mir.engine.rule_interface`):

```python
from typing import List, Dict, Any
from mir.engine.rule_interface import BaseRule, Violation

class MyXmlRule(BaseRule):
    rule_id = "IR-xml-rule"
    description = "A custom description of my rule."
    category = "general"
    is_fixable = "yes"  # "yes", "no", or "sometimes"

    def check(self, content: str, file_path: str, rule_config: Dict[str, Any]) -> List[Violation]:
        violations = []
        # Implement check logic...
        # If a violation is found, append Violation(...) to list.
        return violations

    def fix(self, content: str, file_path: str, rule_config: Dict[str, Any]) -> str:
        # If is_fixable is "yes" or "sometimes", return the modified content string
        return content
```

---

## Publishing to PyPI

For instructions on building distribution archives, TestPyPI validation, and publishing to the live Python Package Index, refer to the [PyPI Publishing Guide](docs/publishing.md).

---

*This entire package was built using **Antigravity**, a powerful agentic AI coding assistant designed by the Google DeepMind team.*

*Total Cumulative Development Time: ~4.1 hours*
