From 484e5c8ca56afa5429a6cd7a260ac8444b4004ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Thu, 17 Sep 2026 13:23:32 +0000 Subject: [PATCH] :memo: Allow the floating-promise header in test files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents may add the fixed file-level typescript/no-floating-promises oxlint-disable header at the top of a `*.test.ts` file — the expectTypeOf() misidentification is a documented false positive (development/testing.md § Known issues) and the await/void workarounds collide with eslint/no-void. Every other suppression stays the human last resort it was. --- AGENTS.md | 4 ++-- CONTRIBUTING.md | 6 +++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7372e24..44fa8b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,10 +25,10 @@ first-action facts. Do not restate evolving prose here — it will drift. Don't silence the type system to force a green run. As an agent these are forbidden: - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error` -- `// oxlint-disable` / `// oxlint-disable-next-line` +- `// oxlint-disable` / `// oxlint-disable-next-line` — the sole exception is the fixed file-level `typescript/no-floating-promises` header at the top of a `*.test.ts` file, spelled exactly as [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) prescribes - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions) -Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it. +Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one, except the one fixed `*.test.ts` file-level header named there. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it. The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C `. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c62e64..2063fad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -151,7 +151,11 @@ reaches for by default: - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The trade-off must sit next to the code it silences. This is a _human_ last-resort convention; agents must not add these — see - [AGENTS.md § Never do](./AGENTS.md#never-do). (why: + [AGENTS.md § Never do](./AGENTS.md#never-do). The sole agent exception is the + fixed file-level header at the top of a `*.test.ts` file, spelled exactly: + `/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync +type-assertion library that the type-aware linter misidentifies as a promise +*/` — any other suppression stays human-last-resort. (why: [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code)) - **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (why: