adds bend-lint tool

[MattCozendey]

Add bend-lint, a standalone linter for Bend 2 with user-written rules

This moves the userland diagnostics work into a tool. Nothing in
bend2/ changes.

tools/bend-lint checks a file with bend's own checker, then runs rules on
it. A rule is a TS module or a Bend file. It reads the source text, the
checker's result for each term (type, scope, depth, quantity, uses), or
both, and returns findings with fixes. The CLI prints them in bend's error
layout, and --fix applies the safe fixes:

bun tools/bend-lint/src/lint.ts file.bend --rules my_rules.ts --rules my_rule.bend

How it gets the checker's results without changing bend: when bend-lint
loads bend2/bend.ts (Bun only), it wraps term_infer and term_check in
memory so they record what they return, and gives bend.ts an fs and path
whose real paths use "/", so imports also resolve on Windows. For rules
written in Bend, it exports RUNTIME_MAIN and js_sat from comp.ts, so a
rule is compiled once. The files on disk do not change, bend and the
gates never load this, and checking gives the same results.

It does not drift silently. Each patch anchor must match exactly once, a
self-check runs at load, and bend.pin holds the git blob hashes of
bend.ts and comp.ts. Any mismatch stops it with a DriftError. To bump:
BEND_LINT_UNPINNED=1 bun test tools/bend-lint, then --pin.

It intentionally does not add anything to bend's CLI, run in the gates,
serve LSP, or give codes to bend's own errors (they are all bend/check).
The only file outside tools/bend-lint is gates/repo.ts: three allow lines.

Validation:

• bun test tools/bend-lint (45 tests: patch anchors, span mapping, TS and
  Bend rules, CLI, and 12 tests from tests/ against drift), on Linux, WSL
  and Windows
• bunx tsc -p tools/bend-lint/tsconfig.json --noEmit (no errors in
  bend-lint; the two it reports in bend2/bend.ts are on main too)
• git diff --check

[nicolas-abril]

Thanks, this is careful work. The approach is sound for an opt-in tool, and it does what it says. On today's main the 48 tests pass and the branch merges cleanly. With no rules, a run costs about the same as bend --check-only (0.92 s vs 0.83 s on bench/checker/proofs_3200). A few things need fixing before it goes in, mostly around --fix and silent wrong results.

Reviewed at 48db83a. "Confirmed" below means reproduced on the branch; the rest are from reading the code.

Bugs

1. --fix can rewrite cached BendHub packages (lint.ts:571). It writes safe fixes to every source that isn't Base, including imported packages cached under ~/.bend/lib. bend only downloads a package when it's missing and never re-checks its hash, so every later bend run would silently use the edited package. Limit --fix to the root file, or at least skip BEND_LIB files.

2. --fix aborts on identical edits (lint.ts:571, lint.ts:342). Confirmed. Two findings that insert the same " " at the same comma count as "overlapping". The run prints only bend-lint: bend-lint: fixes are out of bounds or overlap (the prefix is doubled), exits 2, and shows no findings, because fixed is computed before printing. This happens naturally with one typed rule that doesn't skip fact.inst, since a template instance repeats the body's spans. Merge identical edits, and skip conflicting fixes rather than aborting.

3. Base facts leak into rules (lint.ts:251, lint.ts:253). Confirmed. The filter bok.tlds[def]?.b !== true misses constructor-field checks (their def is a constructor name, which isn't in tlds) and Base template instances. Base is also only seeded when the root file matches /^import Base\s*$/m. With import Base # comment, or with Base reached through another import, 129 of 137 facts had spans in base.bend. That contradicts "Base's own defs give no facts", and Base gets re-checked on every lint.

4. Another bend2 checkout can get this one's code (lint.ts:506). Confirmed. Bun.plugin is process-wide, the filter only checks that the folder is named bend2, and contents are looked up by file name alone. With bend-lint loaded, importing a different checkout's bend2/bend.ts in the same process returned this checkout's patched code (its own exports were missing, and the patch marker was present). That's silently wrong code, not a DriftError. Filter on the full resolved path, and look up contents by full path.

5. Drift that DriftError doesn't catch:

   • check() copies main.ts's private book_read/book_seed (lint.ts:245): the seeding, the PROOF.bend/LAWS.bend rule, the book_valid offset and the TODO count. It has already diverged: it seeds on /^import Base\s*$/m where main.ts uses /^import Base$/m. It also leaves out the unsafe/foreign verdict. On a sample of 412 files from tests/ and demos/, the 27 that rely on @unsafe or foreign code FAIL under bend --check-only but are "ok" under bend-lint, while the README says exit 1 means "the file does not check". Export a shared loader from bend2, or document the difference (or report it as a finding).
   • A future comp.ts export becomes a syntax error (patch.ts:133). The needs check accepts export function js_sat, but the tail then adds export { RUNTIME_MAIN, js_sat }. If comp.ts ever exports js_sat itself, loading fails with a duplicate-export SyntaxError instead of a DriftError.

6. Rule validation misses an undefined entry (lint.ts:297). rules.find returns the bad element itself, so an undefined entry (or a hole) passes validation and then crashes in rules.some(...) with a generic TypeError. Use findIndex.

7. Identical files break span mapping (lint.ts:217). mapper picks the source by line content and dir, not by the span's ns. Two byte-identical files, or an import-error span with no dir, give two candidates, and the run dies with a DriftError instead of reporting.

Performance

8. walk is quadratic (lint.ts:175). Confirmed. A recursive generator with yield* passes every node up through all its ancestors: O(nodes × depth). A 2,000-element list literal takes 408 ms and a 5,000-element one 2.56 s, with stack-overflow risk beyond that. An explicit stack would make it linear.

9. Facts don't scale to big books. With a needsTypes rule, proofs_3200 records 1.28M facts and peaks at 4.4 GB (vs 1.05 GB for the check), taking 1.86 s vs 0.92 s. Each fact keeps its type, context and book alive, which pins checker state the GC would otherwise free. A Bend rule over those facts reaches 6.7 GB and 4.3 s, because lint.js builds a Bend list of every fact up front. Letting a rule narrow what it gets (the root file only, certain term kinds) would help, as would handing facts to Bend rules incrementally.

10. Output is O(findings × file size) (lint.ts:379, lint.ts:364). render re-splits the whole file twice per fix, and position rebuilds the line table on every call (--json calls it for every finding and edit).

Process

11. The PR description is stale. It describes bend.pin, --pin and BEND_LINT_UNPINNED, which 00c86f4 removed; the README correctly says bend-lint "is not pinned". The test count is 48 now, not 45.

12. Nothing runs these tests. The gates never run the suite, so the next change to bend.ts's internals will only surface when someone next uses the tool. Adding its 0.6 s suite to gates/test.ts would catch it. Longer term, a small official hook in bend.ts (an optional book.see called from term_infer/term_check) would remove the source patching entirely, but that's Taelin's call.

13. It ships no rules. The only rules are the examples in the test file. If that's intended, say so; otherwise one or two real rules would make it useful out of the box.

I'd treat 1–5 as blockers. 8–10 can come later, and 12 is a decision.

🤖 Generated with Claude Code

[MattCozendey]

Thanks for the review, all 13 points are handled. Short version:

Blockers (1–5): all fixed

1. --fix editing packages: --fix now writes only the file you lint. It never touches imports or ~/.bend/lib.
2. Identical edits abort: identical edits now merge. Clashing fixes are skipped and counted, not fatal. The doubled prefix is gone, and findings always print.
3. Base facts leak: facts now come only from the linted file (filtered when recorded, then again by span). Base is seeded with main.ts's exact regex.
4. Other bend2 checkouts: the plugin matches the full resolved path and looks up contents by real path.
   5a. book_read copy / unsafe verdict: the seeding now matches main.ts. The README says plainly that bend-lint does not fail a file for @unsafe or foreign code.
   5b. comp.ts duplicate export: it adds the export only if comp.ts does not already have it.

Other bugs (6–7): fixed

6. undefined entries in rules are now caught.
7. Span mapping also uses ns, so identical files map correctly.

Performance (8–10)

8. walk: now uses an explicit stack, so it is linear.
9. Facts on huge books: not fixed yet. It is documented. Next step: rules ask for only the facts they need, and Bend rules get facts bit by bit.
10. Output: line tables are cached per file, so output is linear.

Process (11–13)

11. Stale description: updated. No more pin, and the test count is current.
12. Tests in gates: gates/test.ts now runs the bend-lint suite. The official book.see hook is Taelin's call, and the patch goes away if he adds it.
13. No rules: there are two real rules now, style/trailing-whitespace (safe fix) and style/line-length (max, default 100). Both are opt-in. There are also --fix-suggested and --fix-dangerously.

Tests: 48 → 64, all pass.

[MattCozendey]

Working on 9. Please don't merge yet.

[MattCozendey]

Follow-up on #9 (memory with facts): fixed.

Rules now say which facts they want. facts: { kinds: ["Var"] }, or by def or name. bend-lint drops every other fact as soon as the checker gives it to us, so they never pile up.
On proofs_3200 (one machine, peak memory):
No rules: 0.77 GB
All facts: 2.6 GB
Only Vars: 1.5 GB
Most rules need far fewer facts than that.
Bend rules get facts one at a time (Lint.fold_facts), not as one big list. Memory in use stays the same from the first fact to the last.
Bonus: scope: "program" lets a rule also see facts from imported files (never Base). It is opt-in, so a normal run costs the same.
Not done: each kept fact is still a full fact. A slimmer fact is possible if a real case needs it.

[nicolas-abril]

I pushed two commits on top with fixes from review:

f05a9e9d gates

• gates/test.ts is back to main. bend-lint is an external tool, so its suite shouldn't run in the test gate and block bend2 changes. It also launched lib.BUN (the minis' bun path) on the host with no error handler or timeout.
• gates/repo.ts is back to LF line endings. The only change is the 4 allow lines for tools/bend-lint.

e867ad32 bend-lint

• applyFixes: a fix that edits both the linted file and another file used to be half-applied (only the root edits were written). It's now skipped whole, and the CLI reports how many were skipped.
• --fix now applies fixes even when a finding is an error, e.g. format/layout set to error in the config. The run still prints FAIL and exits 1. The README is updated to match.
• seam: sources use the text bend.ts read during the check instead of reading the disk again afterwards, so saving a file mid-check no longer shows up as a DriftError.
• seam: when offline, latestTag uses the newest cached release without writing it to latest.json. Before, a stale tag was trusted for 24h.
• seam: only the latest checked Base book is kept, instead of one per base.bend text ever seen.
• seam: mapper splits each file's lines once, and only for files whose namespace and folder match. Before, it was quadratic in the number of imported files.

New tests cover the cross-file fix, --fix with an error, and the offline note. The bend-lint suite passes (111 tests).

Also, the PR description mentions a bend.pin file and a --pin command. Neither exists; the README says "We don't pin".