Skip to content

Close the gaps the node block leaves open - #56

Merged
sehkone merged 1 commit into
mainfrom
sehkone/issue-55
Aug 14, 2026
Merged

Close the gaps the node block leaves open#56
sehkone merged 1 commit into
mainfrom
sehkone/issue-55

Conversation

@sehkone

@sehkone sehkone commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Closes #55.

blocks/node.md has not changed since it was written. The three repositories carrying it took it at adoption and no pass was ever made over their existing code, so an audit turned up not a repository that broke a rule but a set of places where the block does not say enough to decide the case in front of you.

What the audit found

A suppression read as compliance. The block forbids any flatly and separately allows a suppression carrying a comment, and never said whether the second reaches the first. All three consumers read that it does — 145 such suppressions, 14 in production, and not one of them bare:

// biome-ignore lint/suspicious/noExplicitAny: pg Pool minimal surface
customerPool: any,

Nine of the fourteen cite a connection handle whose type the dependency already exports. That is not a boundary where the type is unknown; it is a type someone chose not to write. Nothing in the block said so. The suppression rule also named only @ts-ignore and @ts-expect-error, so the biome-ignore every one of the 145 actually uses fell outside a rule plainly meant to reach it.

A ban with nowhere to go. NEVER use npx`` and nothing else — no spelling for a tool deliberately outside the dependency tree, and pnpm dlx nowhere in the block. Two consumers reach for `npx` in a scheduled workflow at four call sites. The prohibition was also unfounded as written: its neighbouring clause explains preferring the scripts, and that reason does not reach `npx`.

Nothing checked at all. as unknown as T appears 42 times in hand-written production code, 389 counting tests, and the block says nothing about it.

What changed

Six edits to blocks/node.md, all within the two sections it already has.

  • The npx ban is grounded in what npx does, and names both replacements — pnpm exec for a dependency, pnpm dlx <tool>@<version> for a one-off, at an exact version and never a dist-tag
  • Installs treat the lockfile as the authority, through pnpm install --frozen-lockfile in CI
  • The suppression rule covers any TypeScript or Biome diagnostic, and rules out @ts-ignore outright
  • A suppression is not a substitute for a type, and a comment recording the real type as inconvenient is not a reason — with what one does look like
  • The rule against any names the boundaries data arrives across
  • The double assertion is forbidden, binding hand-written code only

Grade

PATCH. Nothing is reversed or removed. Five of the six match what all three consumers already do, so this release changes no consumer code — @ts-ignore is at zero across all three, --frozen-lockfile is already universal, and the rest either ground an existing rule or settle a case the block never addressed. The double assertion is the one that creates follow-up work, and it creates it downstream.

Test plan

  • python3 scripts/lint_blocks.pyblocks OK
  • npx markdownlint-cli2 over the repository — 0 issues
  • No line in blocks/node.md exceeds 76 columns
  • Block names no repository, path, or product; pnpm and Biome are named because every consumer of this block is driven by both
  • Commit body wraps at 72; CHANGELOG.md entry carries no issue or pull request references

Follow-ups, not in this PR

One issue per repository once this releases: 13 production any sites in one consumer and 1 in another, 42 double assertions across the three, and the four npx call sites. The block's remaining thinness — no testing rules, no logging rule, no error-handling section, and no requirement to name the exact lint invocation CI runs — is noted in #55 and left for its own issues.

The block has not changed since it was written, and the three
repositories carrying it took it at adoption with no pass ever made
over their existing code. An audit found no repository that broke a
rule — it found places where the block does not say enough to decide
the case in front of you.

A suppression read as compliance. The block forbids `any` flatly and
separately allows a suppression carrying a comment, and never said
whether the second reaches the first. Every consumer read that it
does: 145 such suppressions, 14 in production code, none of them bare.
Nine of the fourteen cite a connection handle whose type the
dependency already exports, which is not a boundary where the type is
unknown but a type someone chose not to write. Nothing in the block
said so, so nothing stopped the fourteenth and nothing would stop the
fifteenth. The suppression rule also named only the type checker's own
directives, so the linter suppression every one of them actually uses
fell outside a rule plainly meant to reach it.

The ban on `npx` had nowhere to go. It never named what to use for a
tool deliberately outside the dependency tree, and two consumers reach
for `npx` in a scheduled workflow at four call sites — the outcome a
prohibition with no alternative tends to produce. It was unfounded as
written too: the neighbouring clause explains preferring the scripts,
and that reason does not reach `npx`. What is wrong with `npx` is that
an uninstalled name becomes a remote install rather than a failure.

The double assertion went unmentioned, and appears 42 times in
hand-written production code. It binds hand-written code only, since
generated output belongs to whatever emits it and an edit there is
undone on the next run.

Five of the six changes match what all three consumers already do, so
the release changes no consumer code. The double assertion is the one
that creates follow-up work, and it creates it downstream rather than
here. No rule is reversed or removed, so this is PATCH under the
grading in README.md.

Closes #55
@sehkone
sehkone merged commit 4f50ac8 into main Aug 14, 2026
1 check passed
@sehkone
sehkone deleted the sehkone/issue-55 branch August 14, 2026 04:39
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.

Close the gaps the node block leaves open

1 participant