chore(lint): add a sweep and a rule for planning tags in comments

Comments used to open with the identifier of the work item that produced
them. The identifiers point into notes that never ship, so a reader meets
something that looks like a reference and leads nowhere.

eslint-plugins/healthlog/planning-tags.js defines the shape once: a head
of tag codes and planning words before an em dash, optionally after a
release version. The version and any issue reference stay; the tag goes.
A line without a version must carry a code that is neither domain
vocabulary (B12, PM2.5, UTF-8) nor used in the file's code.

scripts/strip-planning-tags.mjs locates comments with the TypeScript
parser, rewrites only their text, and refuses any file whose
comment-free printout changes. The healthlog/no-planning-tags rule uses
the same matcher, with an autofix; it is enabled together with the sweep.
This commit is contained in:
Marc-André Bombeck committed 2026-10-20 08:52:23 +02:00
1 parent b50b5fcd21
commit 892a819060
5 files changed
+712

No files matched your search

+189
View File
@@ -0,0 +1,189 @@
#!/usr/bin/env node
/**
* Remove planning-note identifiers from the head of comment lines.
*
* node scripts/strip-planning-tags.mjs # report only, exit 1 on hits
* node scripts/strip-planning-tags.mjs --write # rewrite the files
* node scripts/strip-planning-tags.mjs --write src/lib/foo.ts …
*
* What counts as a tag is defined once, in
* `eslint-plugins/healthlog/planning-tags.js`; the `healthlog/no-planning-tags`
* rule uses the same matcher, so a tree this script leaves clean is a tree
* the rule accepts.
*
* Only comment text changes. Comments are located with the TypeScript parser
* rather than a regex, so string and template contents are never touched, and
* every rewritten file is re-parsed and printed with comments removed: if
* that printout differs from the original's in any way, the file is left
* alone and the run fails.
*/
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { createRequire } from "node:module";
import { extname } from "node:path";
const require = createRequire(import.meta.url);
const ts = require("typescript");
const {
matchPlanningTag,
commentLines,
} = require("../eslint-plugins/healthlog/planning-tags.js");
const EXTENSIONS = new Set([
".ts",
".tsx",
".mts",
".cts",
".js",
".jsx",
".mjs",
".cjs",
]);
const EXCLUDED_PREFIXES = [
"src/generated/",
"eslint-plugins/",
"node_modules/",
];
const args = process.argv.slice(2);
const write = args.includes("--write");
const explicit = args.filter((a) => !a.startsWith("--"));
const files = (
explicit.length > 0
? explicit
: execFileSync("git", ["ls-files"], { encoding: "utf8" }).split("\n")
).filter(
(f) =>
f &&
EXTENSIONS.has(extname(f)) &&
!EXCLUDED_PREFIXES.some((p) => f.startsWith(p)),
);
function scriptKind(file) {
switch (extname(file)) {
case ".tsx":
return ts.ScriptKind.TSX;
case ".jsx":
return ts.ScriptKind.JSX;
case ".js":
case ".mjs":
case ".cjs":
return ts.ScriptKind.JS;
default:
return ts.ScriptKind.TS;
}
}
function parse(file, text) {
return ts.createSourceFile(
file,
text,
ts.ScriptTarget.Latest,
true,
scriptKind(file),
);
}
/** Every comment range in the file, in source order, without duplicates. */
function commentRanges(sf) {
const text = sf.getFullText();
const seen = new Map();
const literalSpans = [];
const add = (ranges) => {
for (const r of ranges ?? []) seen.set(r.pos, r);
};
const visit = (node) => {
add(ts.getLeadingCommentRanges(text, node.pos));
add(ts.getTrailingCommentRanges(text, node.end));
if (
node.kind === ts.SyntaxKind.JsxText ||
ts.isStringLiteralLike(node) ||
node.kind === ts.SyntaxKind.TemplateHead ||
node.kind === ts.SyntaxKind.TemplateMiddle ||
node.kind === ts.SyntaxKind.TemplateTail ||
node.kind === ts.SyntaxKind.RegularExpressionLiteral
) {
literalSpans.push([node.getStart(sf), node.end]);
return;
}
for (const child of node.getChildren(sf)) visit(child);
};
visit(sf);
add(ts.getLeadingCommentRanges(text, sf.endOfFileToken.pos));
return [...seen.values()]
.filter((r) => !literalSpans.some(([s, e]) => r.pos >= s && r.pos < e))
.sort((a, b) => a.pos - b.pos);
}
function printWithoutComments(sf) {
return ts.createPrinter({ removeComments: true }).printFile(sf);
}
function escapeRegExp(s) {
return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
let filesChanged = 0;
let linesChanged = 0;
let tagsRemoved = 0;
let failures = 0;
for (const file of files) {
const original = readFileSync(file, "utf8");
const sf = parse(file, original);
const ranges = commentRanges(sf);
if (ranges.length === 0) continue;
let codeOnly = "";
let cursor = 0;
for (const r of ranges) {
codeOnly += original.slice(cursor, r.pos) + " ".repeat(r.end - r.pos);
cursor = r.end;
}
codeOnly += original.slice(cursor);
const usedInCode = (tag) =>
new RegExp(`(?<![A-Za-z0-9-])${escapeRegExp(tag)}(?![A-Za-z0-9-])`).test(
codeOnly,
);
const edits = [];
for (const r of ranges) {
const raw = original.slice(r.pos, r.end);
for (const line of commentLines(raw)) {
const hit = matchPlanningTag(line.text, usedInCode);
if (!hit) continue;
const start = r.pos + line.offset + line.prefix.length;
edits.push({
start,
end: start + line.text.length,
replacement: hit.replacement,
});
tagsRemoved += Math.max(hit.tags.length, 1);
if (!write) console.log(`${file}\t${line.text}\t${hit.replacement}`);
}
}
if (edits.length === 0) continue;
let next = original;
for (const e of edits.sort((a, b) => b.start - a.start)) {
next = next.slice(0, e.start) + e.replacement + next.slice(e.end);
}
if (printWithoutComments(parse(file, next)) !== printWithoutComments(sf)) {
console.error(
`${file}: rewrite would change code outside comments; left alone`,
);
failures++;
continue;
}
filesChanged++;
linesChanged += edits.length;
if (write) writeFileSync(file, next);
}
console.log(
`${write ? "rewrote" : "found"} ${linesChanged} comment lines (${tagsRemoved} tags) in ${filesChanged} files`,
);
if (failures > 0) process.exit(2);
if (!write && linesChanged > 0) process.exit(1);