Jev Lint

jev-lint

A linter whose rules are sentences. An ast-grep matcher decides which code is looked at; one sentence decides whether it is a problem; a model (Jev) answers the sentence for every match, batched per file. It finds what no parser can: a function whose body does something other than its name promises, a comment that became false, a test that would pass if the behaviour it names were broken.

Knowing which half you are working on is most of the job.

Non-negotiables

1. Never write a rule a compiler, type checker or conventional linter can decide. The model is good at code that contradicts a contract it declares about itself and measurably poor at defects needing knowledge of a specific API (that .sort() is lexicographic). Those belong to the existing tools.
2. Never ask for something the matched code cannot show. The most common way a rule fails, and it looks exactly like a threshold problem: every answer lands mid-scale and no cutoff separates. Check subject and state before touching the wording.
3. Never put a threshold in the sentence. The cutoff is threshold:; baking it into the question means every recalibration rewrites the question.
4. The API key lives in the environment (TYPESAFE_API_KEY), never in .jev-lint.yaml, which belongs in version control. apiKey: in the file is a hard error.
5. A finding is a candidate for a human, not a verdict. Measured on real code about one finding in five was wrong. Read each against the code.
6. Record any run you draw a conclusion from (--record r.json). jev-lint replay r.json re-scores it under new cutoffs with no API key, so a cutoff stays auditable.

Which task is this?

Running it

export TYPESAFE_API_KEY=...            # or TYPESAFEAI_API_KEY
npx -y jev-lint check src --dry-run    # plan and price. Makes NO request.
npx -y jev-lint check src              # judge whole files
npx -y jev-lint run fn-name-promises src        # one shipped rule; rust/<id> for one language
npx -y jev-lint run --file myrule.yml src       # a rule file of your own, and nothing else
npx -y jev-lint review --base main     # judge only what the diff touched
npx -y jev-lint commits --base main    # judge each commit's message against its diff,
                                       #   and each change against AGENTS.md (CLAUDE.md fallback)
npx -y jev-lint commits --staged       # the same, on what is about to be committed
npx -y jev-lint init                   # write .jev-lint.yaml: files, and every shipped rule on
npx -y jev-lint rules                  # what loaded, and every validation error

Run --dry-run first, always: it prints subject count, request count and the price without spending anything. Then review, not check, for anything routine — review mode keeps only matches whose subject overlaps a changed line, which is where findings concentrate and costs a fraction of a cent.

jev-lint review --base "$GITHUB_BASE_REF" --format github   # in CI
jev-lint init --pre-commit      # hook: review --staged + commits --staged, on every commit
jev-lint init --pre-push        # hook: commits @{upstream}..HEAD --fail-on error, before every push
jev-lint check src --retry 3                                 # decide on the mean of 3 passes
jev-lint check src --threshold typescript/fn-name-promises=0.8     # override one cutoff for one run
jev-lint check src -R my-rules.yml -R rules                  # rule sources, repeatable

Exit codes: 0 clean, 1 findings, 2 configuration error, 3 requests failed. Any finding exits 1 unless --fail-on <severity> raises the bar; --format github annotates warning unless the rule says severity: error, and no shipped rule does. The pre-commit hook init --pre-commit writes uses --fail-on error, so no finding blocks a commit until a rule has earned error; without a key in the environment it steps aside. It runs two questions about what is staged -- review --staged for the file rules, then commits --staged for subject: change rules, which is where git/diff-follows-instructions judges the diff against the repository's own AGENTS.md, or CLAUDE.md when absent. A failed request exits 3, and git fails a hook on any non-zero exit, so the shipped bodies let 3 through deliberately: being unable to commit while offline is how a hook gets deleted rather than fixed. Both bodies are tracked at .jev-lint/hooks/<name>, reviewable like any other file, with a shim in git's hooks directory that finds and runs them -- ../../docs/use-hooks.md. --staged reviews what the commit will contain: no untracked files, no unstaged edits, though a partially staged file is judged as it is on disk. When paths are configured or given, review scans only the changed files under them, never the whole tree.

Settings: .jev-lint.yaml (or jev-lint.yaml, .jevlint.yml, any spelling; two in one directory is an error), nearest one searching upwards, a flag beats it. languages: declares a grammar ast-grep does not have built in (a tree-sitter parser compiled to a dynamic library — see the reference; MoonBit is measured there). files: there lets jev-lint check take no argument; rules: picks the rules, ESLint-style — fn-name-promises: on, rust/fn-name-promises: off, comment-describes-block: { threshold: 0.7, severity: error } — from the shipped packs and the project's own .jev-lint/rules/; a config with no rules: runs nothing. Unknown keys are errors. A -R run inside a repository that has a config still merges that config — its rules:, its files: — so pass --no-config when testing a rule in isolation, and --cache none so no earlier verdict is reused (the cache is .jev-lint/baseline.json; -c <path> names another).