Metadata-Version: 2.4
Name: airulelint
Version: 0.1.0
Summary: Lint AI agent configuration markdown files for structural problems.
Project-URL: Homepage, https://github.com/MakiDevelop/ailint
Project-URL: Repository, https://github.com/MakiDevelop/ailint
Author-email: Makito Chiba <makiakatsu@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,config,cursor,gemini,lint,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# ailint

Lint AI agent configuration files for structural problems that agents silently ignore.

## What it does

- Scans CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules for bloat, vague language, redundancy, dead references, and contradictions.
- Reports problems with file:line:column, severity, rule ID, and suggested fixes.
- Provides `--deep` mode for semantic contradiction analysis via the Claude CLI.

## Quick start

```bash
pip install airulelint
```

```bash
ailint                    # auto-detects config file in current directory
ailint CLAUDE.md          # specify a file
ailint --deep AGENTS.md   # add LLM-powered semantic analysis
```

## Example output

```
$ ailint CLAUDE.md

CLAUDE.md:3:20  warning [R002] Vague phrase 'try to' is hard to enforce.
  suggestion: Replace it with a concrete condition, threshold, or required action.
CLAUDE.md:27:1  warning [R005] Possible contradiction in section 'Task Execution': ...
  suggestion: Clarify the condition that decides whether action is automatic or requires confirmation.
CLAUDE.md:145:5 error   [R004] Referenced path does not exist: rules/deploy-sop.md
  suggestion: Fix the path, create the referenced file, or remove the stale reference.

✖ 3 problems (1 error, 2 warnings)
```

Clean file:

```
$ ailint CLAUDE.md

✔ No problems found
```

## Rules

| ID | Name | Default Severity | What it catches |
|----|------|-----------------|-----------------|
| R001 | bloat | warning / error | File >500 lines (warn) or >1000 (error). Sections >100 lines. |
| R002 | vague-language | warning | Unenforceable phrases: "try to", "when possible", "盡量", "適當", etc. Skips definition context (e.g. "forbidden: 大概"). |
| R003 | redundancy | warning | Sections with >70% TF-IDF cosine similarity. Skips parent-child pairs. |
| R004 | dead-reference | error | Local file paths that don't exist. Filters out version numbers, cloud IAM roles, and wildcards. |
| R005 | contradiction | warning | Keyword pairs that conflict: "always" vs "never", "直接做" vs "先確認", etc. |

## Deep mode

`ailint --deep` invokes the `claude` CLI to perform semantic contradiction detection beyond keyword matching. It finds contradictions that static rules miss — like "use barrel files" conflicting with "never use barrel exports" in the same config.

Requires [Claude Code](https://claude.ai/claude-code) installed and authenticated.

## Install

```bash
pip install airulelint          # standard
pipx install airulelint         # recommended on macOS with Homebrew Python
```

The PyPI package is `airulelint` — the CLI command it installs is `ailint`.

## CLI reference

```
usage: ailint [-h] [--deep] [--format {text,json,github}]
              [--severity {info,warning,error}] [--no-color] [--version]
              [path]

positional arguments:
  path           Path to config file (auto-detects if omitted)

options:
  --deep         LLM-powered semantic analysis (requires claude CLI)
  --format       Output format: text (default), json, github
  --severity     Minimum severity to report: info, warning, error
  --no-color     Disable ANSI colors
  --version      Show version
```

## The story

I spent months adding rules to my CLAUDE.md until it hit 3,550 lines. Then I analyzed which rules Claude actually followed — turns out, text rules have near-zero enforcement. I refactored to ~400 lines and moved everything else to hooks. This tool checks for the structural problems I found in my own file.

## Contributing

Issues and pull requests welcome. To run tests:

```bash
pip install -e ".[test]"
pytest
```

## License

MIT
