flint-check

name	flint-check
description	Scans code for potential violations using fast heuristics (regex, ruff). Use when asked to check code quality, find issues, lint code, or generate a violation checklist.
allowed-tools	Read, Glob, Grep, Bash
context	fork
agent	Explore

Flint Check - Heuristic Code Scanner

Scan code for potential violations using fast heuristics and generate a checklist.

When to Use

• User asks to "check code", "find issues", "lint", "review code quality"
• Before a PR or commit
• After generating code to verify quality

Process

1. Load rules from flint.yaml packs (default: rules/ directory)
2. Run heuristics:
   • Ruff: ruff check --output-format json [paths]
   • Regex: scan files for check patterns
   • Python rules: execute @rule decorated functions
3. Generate checklist grouped by rule

Output Format

# Flint Check: $ARGUMENTS

- [ ] Don't use mutable default arguments
  - [ ] utils.py:42 `def process(items=[]):` [!]

- [ ] Use pathlib instead of os.path
  - [ ] files.py:15 `os.path.join(a, b)` [!]
  - [ ] files.py:23 `os.path.exists(path)` [!]

- [ ] Avoid AI slop phrases
  - [ ] readme.py:5 `"""A game-changing feature"""`

Found N potential violations in M rules.

Markers:

• [!] = pattern match (high confidence violation)

Rule Loading

YAML rules (rules/*.yaml):

- description: Never use eval()
  severity: error
  check: "\\beval\\s*\\("
  fix: "Use ast.literal_eval() instead"

Python rules (rules/*.py):

from flint.decorators import rule, fix, violation

@rule(severity="error", paths="**/*.py")
def no_eval(ctx):
    '''Never use eval() with untrusted input.'''
    if "eval(" in ctx.line:
        return violation(ctx, hint="Use ast.literal_eval()")
    return None

@fix(no_eval)
def fix_eval(ctx):
    return ctx.line.replace("eval(", "ast.literal_eval(")

Markdown rules (rules/*.md):

---
severity: error
check: "\\beval\\s*\\("
fix: "Use ast.literal_eval()"
---
Never use eval() with untrusted input.

Scanning Strategy

1. Use Glob to find files matching rule paths (e.g., **/*.py)
2. Use Grep with check patterns
3. Read matched files to extract line context
4. Deduplicate violations (same file:line for same rule)

Important

• Use relative paths in output
• Truncate long snippets to ~60 chars
• Only show rules that have violations
• Group violations under their rule description
• Include fix hint when available for LLM guidance

Next Steps

After check, use flint-fix skill to apply fixes to confirmed violations.