Skip to content

feat(scripts): lint.lg — flag breadcrumb and devlog comments - #836

Draft
mparrett wants to merge 1 commit into
mainfrom
wt/lint-comments
Draft

feat(scripts): lint.lg — flag breadcrumb and devlog comments#836
mparrett wants to merge 1 commit into
mainfrom
wt/lint-comments

Conversation

@mparrett

@mparrett mparrett commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Requested in review on #735 — "We need a linter that checks for breadcrumbs and dev logs in comments" — and tracked as #835.

A devlog comment narrates the change instead of the code: the shape the code had earlier, what a reviewer asked for, what a later change will do to it. It reads as current, goes stale as soon as the change lands, and what it carries belongs in the PR body, a design doc, or the issue tracking the follow-up. There are some on main today; they are listed below.

What this adds

scripts/lint.lg, run the way the rest of the let-go tooling in scripts/ is run:

lg scripts/lint.lg [paths...]        # default: pkg scripts

It is written in let-go, alongside generate.lg, lgbdump.lg, and ir-stress.lg. Comments never reach the reader's form tree, so this is a raw-source pass over whole-line comments in .lg and .go, which also gives each finding an exact file:line instead of an enclosing-form anchor.

Report-only: it never edits source, and it always exits 0.

The phrase list

Deliberately small, and limited to wordings that can be true of the change but not of the code. "previously", "originally", and "for now" are left out because they read the same either way.

Matching is on whole words over normalized prose. Without that, this pr also matched "this process" and "this primitive": 49 findings over pkg/ collapsed to 13 once word boundaries were in and the over-firing no longer was dropped.

Comments carrying a licence header, a tool directive, or lint:ignore are skipped.

Verification

Against the review that prompted it, over the six files of #735 before and after that PR's comment cleanup:

findings
before the cleanup 4, including the header the review comment anchored on
after the cleanup 0

On the current tree it reports 13 across 564 files. Three are unambiguous — shipped code pointing at a pull request that merged long ago:

pkg/nrepl/server.go:297        same hazard this PR fixes for the CLI REPL
pkg/resolver/resolver.go:289   losing the source snippet and stack this PR restores
pkg/ir/lisp_lower_go_test.go   the miscompile this PR fixes

pkg/rt/core/ir/ops.lg:33 carries (moved from typeinfer.lg's infer-one arms), and pkg/rt/lang.go:412, pkg/cli/wasm.go:131, and pkg/vm/var_deref_bench_test.go:15 are the same shape.

I read 11 of the 13 closely: nine I would call real, two I would not. pkg/ir/spike_rpnvm_test.go:128 describes a transformation the pass performs at runtime rather than a change to the code, and cmd/lginterop/main.go:82 is about deps.edn's history rather than this file's.

Open questions

These are why it is a draft.

  • The phrase list is a starting point. You asked for the rule, so the wordings should be yours to set.
  • Report-only, or a gate? Nothing here is wired into the Makefile or CI.
  • Whether the findings above get fixed here or in a follow-up.

A devlog comment narrates the change instead of the code: the shape the code
had earlier, what a reviewer asked for, what a later change will do to it. It
reads as current, goes stale as soon as the change lands, and what it carries
belongs in the PR body, a design doc, or the issue tracking the follow-up.
Requested in review on #735 and tracked as #835.

Written in let-go, alongside generate.lg, lgbdump.lg and ir-stress.lg, and run
the same way: `lg scripts/lint.lg [paths...]`. Comments never reach the reader's
form tree, so this is a raw-source pass over whole-line comments in .lg and .go,
which also gives exact file:line rather than an enclosing-form anchor.

Matching is on whole words over normalized prose. Without that, "this pr" also
matched "this process" and "this primitive" — 49 findings over pkg/ collapsed to
13 once word boundaries and the over-firing "no longer" were dealt with.

The phrase list is deliberately small, and holds only wordings that can be true
of the change but not of the code. "previously", "originally" and "for now" are
left out because they read the same either way. Comments carrying a licence
header, a tool directive, or lint:ignore are skipped.

Validated against the review that prompted it: over the six files of #735 before
the comment cleanup it reports 4, including the header the reviewer anchored on,
and over the same files after the cleanup it reports 0. On the current tree it
reports 13 across 564 files, of which the three "this PR" references in shipped
code are unambiguous.

Report-only, and it always exits 0. Whether it becomes a gate is open on #835.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant