feat(scripts): lint.lg — flag breadcrumb and devlog comments - #836
Draft
mparrett wants to merge 1 commit into
Draft
feat(scripts): lint.lg — flag breadcrumb and devlog comments#836mparrett wants to merge 1 commit into
mparrett wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
maintoday; they are listed below.What this adds
scripts/lint.lg, run the way the rest of the let-go tooling inscripts/is run:It is written in let-go, alongside
generate.lg,lgbdump.lg, andir-stress.lg. Comments never reach the reader's form tree, so this is a raw-source pass over whole-line comments in.lgand.go, which also gives each finding an exactfile:lineinstead 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 pralso matched "this process" and "this primitive": 49 findings overpkg/collapsed to 13 once word boundaries were in and the over-firingno longerwas dropped.Comments carrying a licence header, a tool directive, or
lint:ignoreare skipped.Verification
Against the review that prompted it, over the six files of #735 before and after that PR's comment cleanup:
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/rt/core/ir/ops.lg:33carries(moved from typeinfer.lg's infer-one arms), andpkg/rt/lang.go:412,pkg/cli/wasm.go:131, andpkg/vm/var_deref_bench_test.go:15are 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:128describes a transformation the pass performs at runtime rather than a change to the code, andcmd/lginterop/main.go:82is about deps.edn's history rather than this file's.Open questions
These are why it is a draft.