Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

145 KB
Raw Blame

The ok oxlint rules

Custom lint rules for this workspace. Each rule is a module under rules/, composed into the single ok plugin by index.mjs and switched on in oxlint.config.ts as ok/<rule-name>. A rule that only applies to a subset of files carries its globs in scope.mjs rather than in config — see Scope it, if it is not workspace-wide below.

Rules surface as lint errors during pnpm run lint:oxlint (i.e. pnpm lint and pnpm check) and as inline editor squiggles via the oxc LSP.

One plugin holding every rule is deliberate: oxlint walks the AST once and dispatches every registered visitor, so rules amortize. Measured on this tree, 12 synthetic probe rules added 0.17s and all 24 real rules cost nothing detectable against a no-rule baseline. The GritQL plugins these replaced cost about 3.3s each because every plugin re-traversed.

Convention

All custom lint enforcement uses oxlint JS-plugin rules — PRECEDENTS.md #42. Add a module under rules/ + a fixture-file test. The fixture-file test is non-negotiable: it preserves the mutation-self-test property by asserting the exact position of every diagnostic, filtered by the rule's own code, on a fixture pairing positive cases with negative cases.

Rule modules carry no prose comments. Most are .mjs files and a few are .ts files, and the no-comments policy applies to both — unlike the .grit files they replaced, which sat outside it and carried long rationale headers. That rationale lives here instead, in the rule's section below. When you write a rule, budget for writing its README section in the same change; there is nowhere else for the reasoning to go.

A rule can be TypeScript. oxlint loads a .ts rule module under the pinned Node, which strips its types, so index.mjs imports it by its full .ts path. Type it with a type-only import of oxlint's own rule typings, as no-empty-jsx-expression.ts does. Its fixture test is then <rule>.uncached.test.ts. pnpm run typecheck:lint-plugins checks the .ts rules and tests with lint-plugins/ok-rules/tsconfig.json, and turbo run typecheck runs it.

Diagnostic messages name the fix and link the docs. Every message has two load-bearing pieces: (a) a noun-phrase or action verb-phrase that names what to do to fix the violation (the fix-noun — readers see this and know the next move without leaving the editor); (b) a trailing See <docs-URL> pointing at the rule's section in this README so the message stays self-documenting. Process metadata (decision markers like D19:, spec-section refs) does NOT belong in the diagnostic — it rots the same way it rots in source comments. The fixture test asserts both pieces are present (substring match for the fix-noun + URL regex) so the convention survives drift.

Rules

A scoped rule's section carries an Included: line transcribed by hand from its scope entry in scope.mjs. Nothing generates or drift-checks the two, so scope.mjs is what the linter reads and the line is a copy that can fall behind it. Most scoped sections restate those globs again in their surrounding prose, which is a second copy on top of the first. require-utf8-multipart-parser is the one written the other way round on purpose: its prose argues the rationale and leaves the globs to that line alone. That is the intended shape for new sections; converting the remaining ones is deferred rather than forgotten.

microcopy-ellipsis

Flags U+2026 (…) in two JSX surfaces:

  • JSX text children — <span>Loading…</span>
  • JSX attribute string values for placeholder | label | title | aria-label | description | tooltip

The codebase reserves … for two cases only:

  1. macOS native menu items (rendered via Menu.buildFromTemplate in packages/desktop/src/main/menu.ts). Native-OS convention for "opens a new surface" (Apple/Windows/GTK HIG).
  2. Truncation indicators — where … literally means "I cut text here" (graph labels, breadcrumb collapse, search snippets, sha256 prefixes, token-prefix elisions).

The rule does NOT catch:

  • Object-literal menu templates ({ label: 'Settings…' }) — naturally skipped because they're not JSX, which is correct (Electron menus belong to case #1).
  • … in plain .ts files — naturally skipped because they're not JSX (graph-label-utils, suggest-links, etc. — these are all case #2 truncation utilities).
  • … in CLI strings (process.stderr.write('Cloning…')) — uncaught gap; review discipline covers the small CLI surface.
  • … in JSX expression-child string literals (<span>{'Loading…'}</span>) — uncaught gap; zero occurrences in the codebase today (developers write <span>Loading…</span> directly). If a realistic case emerges, add a jsx_expression pattern matching string literal children rather than retrofit ad-hoc.

Rule: lint-plugins/ok-rules/rules/microcopy-ellipsis.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/microcopy-ellipsis.fixture.tsx. Test: lint-plugins/ok-rules/tests/microcopy-ellipsis.uncached.test.mjs.

no-loosely-typed-webcontents-ipc

IPC discipline enforcement. Forbids direct electron IPC primitives (webContents.send, ipcMain.handle/on, ipcRenderer.invoke/on/once) outside the typed-wrapper files. Consumers must route through createInvoker / createHandler / sendToRenderer from packages/desktop/src/shared/ipc-*.ts. See PRECEDENTS.md #14 for the IPC discipline rationale.

Rule: lint-plugins/ok-rules/rules/no-loosely-typed-webcontents-ipc.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-loosely-typed-webcontents-ipc.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-loosely-typed-webcontents-ipc.uncached.test.mjs.

no-raw-html-interactive-element

UI primitives discipline. Forbids raw JSX <button>, <input>, <textarea>, <select> inside production .tsx under packages/{app,desktop,plugin}/src/**. Consumers must use the shadcn primitives (Button, Input, Textarea, Select) from @/components/ui/*; if the primitive isn't installed yet, add it via pnpm dlx shadcn@latest add <name> from packages/app first. The rule catches the PR #937 failure mode: contributors (including Codex / Claude Code / human reviewers) introducing raw <button> JSX while a shadcn <Button> from @/components/ui/button was already imported in the same file.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{app,desktop,plugin}/src/**/*.tsx. Exemptions are the leading-! globs in that same entry:

  • !packages/app/src/editor/** — ProseMirror NodeViews + editor chrome legitimately render raw HTML for measurement / PM-managed DOM. The exemption matches the existing a11y/useSemanticElements suppressions scattered through the editor subtree.
  • !packages/app/src/components/ui/** — these files ARE the shadcn primitive wrappers; they MUST render raw HTML by definition.
  • !**/*.test.tsx + !**/*.dom.test.tsx + !**/*.test-helper.tsx — test fixtures and shared test doubles aren't user-facing UI.

Pre-rule backlog (ratchet pattern). Files that pre-date the rule and use raw <button> / <input> / <textarea> carry a file-level // oxlint-disable ok/no-raw-html-interactive-element -- pre-rule backlog — ... comment at the top of the file. The comment list across the codebase IS the visible migration backlog — review treats each oxlint-disable file header as a backlog marker, not a free pass. Drain by migrating the file to shadcn primitives, then deleting the suppression header (the rule starts firing again immediately, so a partial migration that misses a raw <button> fails the gate). Reference migration: packages/app/src/components/NavigatorApp.tsx (three raw <button> → shadcn <Button variant="ghost|outline|link">).

The rule does NOT catch:

  • PascalCase composite components whose name starts with Button / Input (e.g. <ButtonGroup>, <InputGroup>) — pattern scopes to lowercase JSX tag names only.
  • Raw HTML in .ts files (e.g. dangerouslySetInnerHTML strings, template literals).
  • Raw <a> used as an action — anchor-as-button is governed by Biome's built-in a11y/useSemanticElements + the codebase's existing button-vs-anchor conventions.
  • Other interactive primitives (<dialog>, <details>, <summary>) where the team hasn't yet committed to a shadcn-only contract.

Scope (RULE_SCOPES['no-raw-html-interactive-element'] in scope.mjs). UI primitives discipline (see PR #937 retrospective). Scoped to packages/{app,desktop,plugin}/src//*.tsx — production UI surfaces. Exemptions: - packages/app/src/editor/ — ProseMirror NodeViews + chrome legitimately render raw HTML for measurement / PM-managed DOM (matches the existing a11y/useSemanticElements suppressions in editor/). - packages/app/src/components/ui/* — these ARE the shadcn primitive wrappers; they must render raw HTML by definition. - *.test.tsx / *.dom.test.tsx / *.test-helper.tsx — test fixtures and shared test doubles aren't user-facing UI. Pre-rule backlog (files outside the exemptions that pre-date the rule) is annotated via // oxlint-disable ok/no-raw-html-interactive-element -- at the top of each offender file — the comment list is the visible migration backlog. New files cannot opt out: PR review treats the suppression header as a backlog marker, not a free pass.

Included: packages/app/src/**/*.tsx, packages/desktop/src/**/*.tsx, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-raw-html-interactive-element.fixture.tsx. Excluded: packages/app/src/editor/**, packages/app/src/components/ui/**, **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.tsx.

Rule: lint-plugins/ok-rules/rules/no-raw-html-interactive-element.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-raw-html-interactive-element.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-raw-html-interactive-element.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-themeless-pierre-diff

@pierre/diffs render contract. Every <MultiFileDiff> construction site under packages/app/src/**/*.tsx (both the self-closing and the child-bearing JSX form) must pass an explicit theme and must set diffStyle: 'unified'. new UnresolvedFile(...) is covered by the theme half only — the constructor surfaces take no diffStyle.

The theme check reads the options object, not the whole prop list, so a theme token elsewhere on the element (data-theme="dark", a title string, a variable named theme passed to an unrelated prop) cannot suppress the diagnostic. The fixture pins that with a decoy case.

Both halves are load-bearing. Pierre ships its own palette, so a themeless renderer paints in Pierre's colours instead of the app's and stops tracking the user's light/dark selection. And diffStyle: 'split' renders the two sides as separate DOM subtrees, so the change-stepper's DOM-order adjacency grouping counts roughly 2x the real groups — the displayed denominator desyncs from the anchors the stepper can actually reach.

This rule replaces a readFileSync + regex meta-test that asserted the same invariant over source text. That test violated the AGENTS.md rule against asserting raw source text for props ("Source guards need proof runtime coverage is impossible" — it wasn't), and it carried a tautological self-test that ran a regex over its own string literals. The per-component half of its intent now lives in runtime assertions in ActivityPanelDiffView.dom.test.tsx (pre[data-diff-type="single"] for unified; the injected :host token block for theme). Lint is the right layer for the codebase-wide "no call site omits it" half — PRECEDENTS.md #42.

The rule does NOT catch:

  • a @pierre/diffs constructor other than UnresolvedFile — new File(...), or any aliased import such as File as PierreFile in ConflictFilePreview.tsx. the rule matches the identifier as written, so a rename defeats it
  • a renamed MultiFileDiff import, for the same reason
  • a theme reaching the renderer through a spread or a variable (options={{ ...baseOptions }}, options={opts}) — the check reads the object literal, and there is no occurrence today

Runtime complement: packages/app/src/components/ActivityPanelDiffView.dom.test.tsx asserts the rendered result on the one surface this migration adds — pre[data-diff-type="single"] for unified, and the injected :host token block for theme.

Scope (RULE_SCOPES['no-themeless-pierre-diff'] in scope.mjs). @pierre/diffs render contract. Every construction site passes an explicit theme and renders unified. Scoped to production .tsx under packages/app/src; the fixture is opted in so its deliberate violations are what the rule's fixture test counts.

Included: packages/app/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-themeless-pierre-diff.fixture.tsx. Excluded: **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.tsx.

Rule: lint-plugins/ok-rules/rules/no-themeless-pierre-diff.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-themeless-pierre-diff.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-themeless-pierre-diff.uncached.test.mjs.

no-resolved-value-theme-source

1-way theme contract. Forbids resolving the user-intent theme value at the bridge.setThemeSource(...) call site. The contract is 1-way: pass the unresolved CRDT value ('system' | 'light' | 'dark') verbatim. 'system' delegates appearance tracking to macOS via nativeTheme; resolving at the call site (via matchMedia or a prefersDark ? 'dark' : 'light' ternary) loses tracking. See PRECEDENTS.md #40(a) for the renderer-state↔main-state contract.

Detection patterns (call expressions only — type-declarations are naturally excluded):

  • setThemeSource($arg) where $arg contains matchMedia (any form)
  • setThemeSource($arg) where $arg contains both 'light' and 'dark' string literals (likely a ternary, either order)
  • Matches both bare-call and member-call shapes (obj.setThemeSource(...))

Rule: lint-plugins/ok-rules/rules/no-resolved-value-theme-source.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-resolved-value-theme-source.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-resolved-value-theme-source.uncached.test.mjs.

no-split-suggestion-dispatch

One-transaction suggestion insertion (PRECEDENTS.md #58). Inside a @tiptap/suggestion Suggestion({ ... }) config, a trigger-range delete dispatched on its own (separate from the content insert) opens a re-entrant-dispatch window: anything fired synchronously during the delete's own updateState (a plugin appendTransaction, a view/NodeView update, the y-prosemirror binding reacting to the delete) can remap the selection onto an adjacent selectable: true node, and the follow-up insert then silently REPLACES that node. The fix is one chain (.deleteRange(range).insertContent(...).run()) or an applySlashCommandItem-style boundary (packages/app/src/editor/slash-command/apply-item.ts) for items needing post-commit work.

Detection patterns (scoped to Suggestion($config) call sites, so delete-only surfaces outside suggestion configs — e.g. a mention chip's remove button — never fire):

  • a chain whose .run() receiver is the deleteRange(...) call itself (....deleteRange(range).run() — a compliant atomic chain always continues past the delete before .run())
  • $editor.commands.deleteRange($range) — the commands.* form dispatches immediately, always a standalone delete transaction

Unscoped (workspace-wide, like microcopy-ellipsis — it carries no RULE_SCOPES entry and sits in UNSCOPED_RULES): the pattern self-scopes to Suggestion(...) calls, and a future suggestion surface in any package must be covered without a scope-table edit.

The rule does NOT catch:

  • a split whose delete chain carries a non-content step after deleteRange and before .run() (e.g. .deleteRange(r).focus().run()) — the .run() receiver is then not the deleteRange call
  • a second dispatch made inside a delegated item body (item.command(editor) running its own editor.chain().run()) — lint can't see through delegation
  • raw view.dispatch(tr.delete(...)) inside a Suggestion config — no occurrence today

Runtime complement: packages/app/src/editor/extensions/suggestion-atomicity.dom.test.tsx + slash-command-atomicity.dom.test.tsx drive every registered suggestion surface through a real Enter and assert exactly one doc-changing transaction — they catch the delegated-dispatch shapes the lint can't.

Rule: lint-plugins/ok-rules/rules/no-split-suggestion-dispatch.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-split-suggestion-dispatch.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-split-suggestion-dispatch.uncached.test.mjs.

no-unportaled-editor-content

H6 cross-doc DOM bleed contract. @tiptap/react's PureEditorContent.componentDidMount runs element.append(...editor.view.dom.parentNode.childNodes) — a sibling-vacuum primitive. When view.dom shares a parent with another editor's view.dom (e.g., V2 cache parked nodes, cross-Activity reconciliation transitions), the vacuum drags foreign content into the active wrapper. The structural fix is to render every <EditorContent> via React.createPortal into a per-Activity exclusively-owned DOM target, so view.dom's parent only ever contains THIS editor's nodes.

The rule flags every JSX usage of <EditorContent> — both self-closing and child-bearing forms — and asks the author to suppress at the canonical portaled site (where the createPortal call lives) with // oxlint-disable-next-line ok/no-unportaled-editor-content -- <reason>. Adding a non-portaled <EditorContent> anywhere else in the codebase becomes a lint error, gated at editor-save / pnpm lint time.

Canonical sanctioned shape (TiptapEditor.tsx):

createPortal(
  <EditorContent editor={editor} className="..." />,
  portalTarget,
);

Rule: lint-plugins/ok-rules/rules/no-unportaled-editor-content.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-unportaled-editor-content.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-unportaled-editor-content.uncached.test.mjs. See PRECEDENTS.md #44 for the H6 cross-doc DOM bleed contract and PRECEDENTS.md #42 for the custom-rule convention.

no-app-core-barrel-import

Open Knowledge app production source imports core through package subpaths, never through the bare @inkeep/open-knowledge-core barrel. The barrel re-exports every core facility, so one bare import puts all of it into the editor's first-page module graph and into the graph each app test loads. Core exports one subpath per module the app uses (@inkeep/open-knowledge-core/<module>, the module path relative to packages/core/src without its extension or a terminal /index, declared in packages/core/package.json exports), and every entry builds into the same emitted runtime, so a subpath and the barrel hand out identical bindings. The fix for a diagnostic is to import each binding from the subpath of the module that exports it; packages/core/src/index.ts shows which module that is.

When that module has no subpath yet, register one in four places. Add its exports block in packages/core/package.json, with the @inkeep/source, development, types and default conditions in that order. Add its entry to the shared map in packages/core/tsdown.config.ts, keyed by the flat dist file name its default target names, so both build passes emit it; core's build fails in verify:exports when a declared target is missing. Import it and add its row to MODULE_SUBPATHS in packages/core/tests/contract/module-subpaths.test.ts, whose key test fails when a new exports key is missing from that map. Re-export its types from packages/core/tests/contract/subpath-types/consumer.ts, which core's typecheck compiles against source and its check:dts compiles against the emitted declarations.

The rule matches module specifiers, not text. It compares each specifier with any ?query or #hash suffix removed, because a bundler resolves @inkeep/open-knowledge-core?v=1 to the same barrel, so a suffix cannot slip one past the rule; that includes ?raw of the bare barrel, whose remedy is a subpath too. It fires at the specifier of a static import of any shape (value, import type, mixed, namespace, default, side-effect), a TypeScript import x = require(...), a named, type, star or star-as re-export, a typeof import(...) or import(...).Name type, a dynamic import() whose argument is a string or a template literal with no expressions, and a call to the require builtin with such an argument. It does NOT fire on a declared subpath, on a sibling package whose name shares the prefix (@inkeep/open-knowledge, @inkeep/open-knowledge-server, a longer @inkeep/open-knowledge-core-* name), on the barrel name inside an ordinary string, template or comment, on a computed import() argument, or on a member call such as loader.require(...). Those last two are deliberate holes: the specifier is not knowable from the syntax. Two more are known limitations: the comparison is case-sensitive, so a case variant such as @Inkeep/open-knowledge-core does not fire, and a computed specifier built from a variable or a template with expressions does not either.

Other packages (docs, its generator, md-conformance, server, CLI, desktop) keep the barrel, and so do app tests: a test that imports the barrel loads it into its own graph only, and a test mock has to follow the module production imports, which the barrel no longer is. The scope therefore covers app source by extension pattern, so a file added in a new directory is covered without an edit here, and subtracts every suffix the shared test-only classifier isTestOnlySourceFile recognizes. The self-test fails if that classifier gains a suffix this scope does not exclude. The dev-server adapter packages/app/src/server/hocuspocus-plugin.ts is production source and is in scope.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, packages/app/src/**/*.mts, packages/app/src/**/*.cts, packages/app/src/**/*.js, packages/app/src/**/*.jsx, packages/app/src/**/*.mjs, packages/app/src/**/*.cjs, lint-plugins/ok-rules/__fixtures__/no-app-core-barrel-import.fixture.tsx. Excluded: **/*.test.ts, **/*.test.tsx, **/*.test-helper.ts, **/*.test-helper.tsx, **/*.type-tests.ts, **/*.type-tests.tsx, **/*.e2e.ts.

Beyond the fixture positions, the self-test copies the repository's own oxlint.config.ts, the lint-plugins directory and the files its modules read into a temporary directory outside the repository, plants a bare import in a production-shaped file and a test-only sibling under that copy's packages/app/src, and expects exactly one diagnostic, on the production file; the subpath form of the same import must lint clean. The copy keeps the probe files out of the shared source tree, where a concurrent test collection, lint or typecheck would read them.

Rule: lint-plugins/ok-rules/rules/no-app-core-barrel-import.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-app-core-barrel-import.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-app-core-barrel-import.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-uninstall-forbidden-import

"Connects to nothing" first-hop feedback. The self-uninstall window's survey and completion screens render after ok uninstall --yes has stopped the local Hocuspocus server and removed ~/.ok, so the uninstall entry must never reach the editor, the CRDT stack, the provider pool, or the server bootstrap — and must eager-load (no dynamic import()) so those screens paint from memory once teardown is under way.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/app/src/uninstall/** (test files exempt — a dom test legitimately does await import('./main') to prove the entry paints). Two diagnostics:

  • A static import (import … from, import type … from, import * as … from, or side-effect import) whose source is an editor / CRDT / provider-pool / Hocuspocus-server specifier (@/editor/*, @inkeep/open-knowledge-server, @hocuspocus/*, yjs, y-protocols, y-prosemirror, y-codemirror.next, y-indexeddb, @tiptap/y-tiptap, @tiptap/extension-collaboration*). @inkeep/open-knowledge-core (shared types + constants) is deliberately allowed.
  • Any dynamic import().

This rule is shallow, first-hop feedback only. The authoritative gate is the transitive-module-graph test at packages/desktop/tests/unit/uninstall-module-graph.test.ts, which builds the entry alone and checks its whole loaded-module set — so it also catches a forbidden module reached indirectly through a shared @/lib / @/components/ui module, and re-export (export … from) edges a first-hop rule cannot express.

Scope (RULE_SCOPES['no-uninstall-forbidden-import'] in scope.mjs). "Connects to nothing" first-hop feedback. The self-uninstall window's survey/completion screens render after ok uninstall --yes stops the local Hocuspocus server and removes ~/.ok, so the uninstall entry must never import the editor / CRDT / provider-pool / Hocuspocus-server surface, and must eager-load (no dynamic import). This is SHALLOW first-hop feedback; the authoritative gate is the transitive-graph test at packages/desktop/tests/unit/uninstall-module-graph.test.ts, which also catches indirect and re-export pull-ins a first-hop rule can't express. @inkeep/open-knowledge-core (shared types + constants) is allowed. Test files are excluded: the invariant is about the SHIPPED entry graph, and a dom test legitimately does await import('./main') to prove the entry paints (a dynamic import the eager-load rule would otherwise flag).

Included: packages/app/src/uninstall/**/*.ts, packages/app/src/uninstall/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-uninstall-forbidden-import.fixture.tsx. Excluded: packages/app/src/uninstall/**/*.test.ts, packages/app/src/uninstall/**/*.test.tsx, packages/app/src/uninstall/**/*.dom.test.tsx.

Rule: lint-plugins/ok-rules/rules/no-uninstall-forbidden-import.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-uninstall-forbidden-import.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-uninstall-forbidden-import.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

path-conditional-map-driven-origin

Observer A origin discipline. Inside packages/server/src/server-observers.ts, every Y.Doc.transact() call MUST pass the sanctioned origin OBSERVER_SYNC_ORIGIN as its second argument (doc.transact(fn, OBSERVER_SYNC_ORIGIN)). Bare doc.transact(fn) - or a wrong origin - routes the write to openknowledge-service and breaks per-session UndoManager attribution (the trackedOrigins Set-identity match skips the transaction).

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/server/src/server-observers.ts. Other server files routing through session.dc.document.transact(fn, session.origin) are out of scope - that contract is enforced by paired-write-enforcement.test.ts.

The rule checks the argument position (the second argument node), not whether the call subtree contains the identifier somewhere. It matches every transact(...) call, then excludes the two sanctioned shapes (transact($_, OBSERVER_SYNC_ORIGIN) and the 3-arg transact($_, OBSERVER_SYNC_ORIGIN, $...)). A callback body that mentions OBSERVER_SYNC_ORIGIN for an unrelated reason therefore neither clears a bare/wrong call nor trips a correct one - the prior contains-based shape was falsely cleared by such a mention.

The rule does NOT catch:

  • Transact calls outside server-observers.ts (scoped to the one observer-dispatch file)
  • An origin passed in a position other than the second argument (the contract is second-argument placement; no real call site does otherwise)

Scope (RULE_SCOPES['path-conditional-map-driven-origin'] in scope.mjs). Observer A origin discipline. Scoped to the one file that owns the observer-cross-CRDT transact spine. Inside this file every doc.transact(fn, origin) must pass OBSERVER_SYNC_ORIGIN as the second argument; bare doc.transact(fn) (or a wrong origin) routes the write to openknowledge-service and breaks per-session UndoManager attribution. Other server files routing through session.dc.document.transact(fn, session.origin) are out of scope - that contract is enforced by paired-write-enforcement.test.ts.

Included: packages/server/src/server-observers.ts, lint-plugins/ok-rules/__fixtures__/path-conditional-map-driven-origin.fixture.tsx.

Rule: lint-plugins/ok-rules/rules/path-conditional-map-driven-origin.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/path-conditional-map-driven-origin.fixture.tsx. Test: lint-plugins/ok-rules/tests/path-conditional-map-driven-origin.uncached.test.mjs.

cst-pm-handler-todo-stub

Codemod handler TODO-stub grep. Flags handler files under packages/md-conformance/src/substrates/*/handlers/ that still contain the codemod's stub body (throw new Error("TODO: implement <substrate>:<dir>/<key>")), so a codemod stub that survives to lint time is caught.

This is a TODO-stub grep, NOT an exhaustiveness check. Whether a substrate covers every PM node type (the node-set traversal over packages/core/schema-snapshot.json) is a separate concern owned by a suite-self-consistency gate. The compile-time backstop for missing methods is the TypeScript handlers-table type check against ICstEngine.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to the per-substrate handlers/ subtrees (see the rule's RULE_SCOPES entry in scope.mjs). The codemod implementation, harness tests, and oracles are out of scope (they legitimately produce strings containing "TODO: implement" in their own contexts).

The rule does NOT catch:

  • Missing handler FILES (file-presence is out of the rule's scope; TypeScript + codemod coverage handle this)
  • Whether the handler set is complete per the PM schema (a separate node-set traversal, deferred to the suite-self-consistency gate)
  • Error subclasses (only matches new Error(...))
  • Non-anchored "TODO" mentions (regex requires the message to start with TODO: implement)

Scope (RULE_SCOPES['cst-pm-handler-todo-stub'] in scope.mjs). Handler TODO-stub grep: scaffolded handlers are seeded with throw new Error("TODO: implement …"), and this rule flags any stub that survives to lint time so an unfinished handler can't pass review. It is NOT an exhaustiveness check — type checks are the compile-time backstop for missing methods. Scoped narrowly to the handlers/ subtrees so harness tests and oracles (which legitimately produce "TODO: implement" strings in their own contexts) are out of scope.

Included: packages/md-conformance/src/substrates/*/handlers/**/*.ts, lint-plugins/ok-rules/__fixtures__/cst-pm-handler-todo-stub.fixture.tsx.

Rule: lint-plugins/ok-rules/rules/cst-pm-handler-todo-stub.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/cst-pm-handler-todo-stub.fixture.tsx. Test: lint-plugins/ok-rules/tests/cst-pm-handler-todo-stub.uncached.test.mjs.

class-proof-registration-discipline

Class-proof DSL contract enforcement. Two arms, short-circuiting — Pattern A wins when both apply, so a call missing options reports once, not twice:

  • Pattern A (missing args): flags defineClassProof(name, opts) when opts doesn't contain both predicate: and proof: property assignments.
  • Pattern B (outside canonical dir): flags any defineClassProof(...) call. The scope entry excludes packages/md-conformance/src/class-proofs/proofs/**, so this fires only on registrations outside the sanctioned location.

Inside the canonical proofs/ dir, neither pattern fires — TypeScript's ClassProofOptions<M> signature backstops the missing-args check, and any defineClassProof call there is in the sanctioned location.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to all .ts/.tsx/.mts files EXCEPT the canonical class-proofs/proofs/** dir and *.test.ts/*.test.tsx/*.test.mts (test files that exercise the DSL are exempt — dsl.test.ts legitimately calls defineClassProof outside the canonical dir).

The rule does NOT catch:

  • Missing-args violations inside the canonical proofs/ dir (TypeScript catches those)
  • Functions with similar names (myDefineClassProofVariant) — pattern matches the exact function name
  • Type references to defineClassProof — pattern scopes to call expressions

Scope (RULE_SCOPES['class-proof-registration-discipline'] in scope.mjs). Class-proof DSL registration discipline: registrations MUST live in the canonical proofs/ dir (one manifest as the single source of truth) and EVERY registration MUST pass predicate + proof options. The scope entry EXCLUDES the canonical dir — inside it, the TypeScript signature is the missing-args backstop; outside it, every defineClassProof(...) call fires exactly once: with the missing-options diagnostic when predicate or proof is absent, otherwise with the wrong-location diagnostic.

Included: **/*.ts, **/*.tsx, **/*.mts, lint-plugins/ok-rules/__fixtures__/class-proof-registration-discipline.fixture.tsx. Excluded: **/node_modules/**, **/dist/**, **/*.test.ts, **/*.test.tsx, **/*.test.mts, packages/md-conformance/src/class-proofs/proofs/**.

Rule: lint-plugins/ok-rules/rules/class-proof-registration-discipline.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/class-proof-registration-discipline.fixture.tsx. Test: lint-plugins/ok-rules/tests/class-proof-registration-discipline.uncached.test.mjs.

playwright-prefer-to-have-count

Flags expect(await locator.count()) — the one-shot count snapshot that never retries. Under CI CPU contention the DOM settles a few frames after the read, so the assertion flakes while the auto-retrying web-first form await expect(locator).toHaveCount(n) passes deterministically (the no-retry read was one of the hidden-flake shapes in the 2026-06 e2e CI audit). The pattern matches the probe sub-expression regardless of the matcher that follows (.toBe, .toEqual, .toBeGreaterThanOrEqual, ...). Upstream precedent: eslint-plugin-playwright prefer-to-have-count.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/app/tests/{stress,a11y}/**/*.e2e.ts (the two dirs tests/integration/e2e-stop-rules.test.ts source-scans) + the fixture. Not workspace-wide: outside Playwright specs, .count() is usually not a Locator and the web-first rewrite does not apply.

The rule does NOT catch:

  • expect.soft(await locator.count()) — different callee node shape; zero occurrences today.
  • A count read assigned to a variable and asserted later (const n = await loc.count(); expect(n).toBe(2)) — two statements; the rule cannot correlate them. Add an e2e-stop-rules source-scan rule if the split form ever recurs.
  • oxlint JS-plugin diagnostics are diagnostic-only — the toHaveCount rewrite is named in the message but not auto-applied.

Scope (RULE_SCOPES['playwright-prefer-to-have-count'] in scope.mjs). One-shot expect(await locator.count()) reads never retry and are the canonical hidden-flake assertion shape (2026-06 e2e audit). Scoped to the browser e2e suites (the stress and a11y dirs the e2e-stop-rules source-scan also covers) + the rule's own fixture. Not workspace-wide: outside Playwright specs, .count() is usually not a Locator and the web-first rewrite does not apply.

Included: packages/app/tests/stress/**/*.e2e.ts, packages/app/tests/a11y/**/*.e2e.ts, lint-plugins/ok-rules/__fixtures__/playwright-prefer-to-have-count.fixture.tsx.

Rule: lint-plugins/ok-rules/rules/playwright-prefer-to-have-count.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/playwright-prefer-to-have-count.fixture.tsx. Test: lint-plugins/ok-rules/tests/playwright-prefer-to-have-count.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-roundtrip-identity-oracle

Forbids the byte-fidelity round-trip oracle in public-mirrored tests. Asserting that re-serializing a freshly-parsed document yields back the same input — serialize(parse(x)) (or the MarkdownManager method form m.serialize(m.parse(x))) compared equal to that same x via .toBe / .toEqual / .toStrictEqual or === — is the engine's byte-identity correctness oracle, exercised by its own fidelity suite. A public test should pin a specific expected output instead; this rule keeps a new public test from reintroducing the general oracle.

Identity, not contract. The rule fires only when the parse input and the expected value are the same expression — the receiver-identity check ($x … $x) enforces textual equality. That is what separates the oracle from the assertions that must stay public and green:

  • A contract test pins a fixed expected literal (expect(serialize(parse('# H'))).toBe('# H\n')) — the expected differs from the input, so it does not fire.
  • The Bridge-invariant comparator normalizeBridge(a) === normalizeBridge(b) (precedent #38, the documented public contract) contains no serialize(parse(...)) and is never flagged.
  • The normalizing-construct detector serialize(parse(x)) !== x uses !==, a different operator, and is never flagged.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to the public-mirrored test surface (packages/**/*.test.ts, *.test.tsx, *.e2e.ts). The internal suites that legitimately own the oracle are excluded as negative globs (see the rule's RULE_SCOPES entry in scope.mjs); on this surface it is forbidden.

The rule does NOT catch:

  • Round-trip identity through a helper (mdRoundTrip(x), normalize(...)) or an intermediate variable (const out = serialize(parse(x)); expect(out).toBe(x)) — the pattern matches the inline call shape, not helper bodies or cross-statement data flow. Those forms live in the path-excluded fidelity suite, covered by exclusion.
  • Equality through matchers other than toBe / toEqual / toStrictEqual, or operators other than === (e.g. a custom assertByteIdentical helper).
  • Any oracle whose two sides are not the same inline expression (e.g. a round-trip compared to a different variable).

Scope (RULE_SCOPES['no-roundtrip-identity-oracle'] in scope.mjs). Byte-fidelity round-trip oracle ban. serialize(parse(x)) (or the MarkdownManager method form) asserted equal to the same x is the engine's byte-identity correctness oracle; it is owned by internal suites excluded from this rule's scope entry, so a test on this surface can't reintroduce it. The fixture is in scope so its planted oracle drives the fixture-file test; the Bridge-invariant comparator normalizeBridge(a) === normalizeBridge(b) (precedent #38) is the public contract and is left untouched by the rule, not by this scope.

Included: packages/**/*.test.ts, packages/**/*.test.tsx, packages/**/*.e2e.ts, lint-plugins/ok-rules/__fixtures__/no-roundtrip-identity-oracle.fixture.tsx. Excluded: packages/md-conformance/**, packages/app/tests/fidelity/**, packages/core/src/markdown/**/*.test.ts, packages/core/src/bridge/**/*.test.ts, **/*.private.*.

Rule: lint-plugins/ok-rules/rules/no-roundtrip-identity-oracle.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-roundtrip-identity-oracle.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-roundtrip-identity-oracle.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention and PRECEDENTS.md #38 for the Bridge-invariant contract.

no-hand-rolled-branch-validation

Branch-name admissibility has one owner in packages/server: isValidBranchName (packages/core/src/schemas/api/share.ts), declared the single source of truth for the seven-rule contract by the commit "reject colon + .. in branch names; unify validation across 3 surfaces". Testing a regex against a branch value re-implements that contract locally, where it drifts silently.

That drift is not hypothetical. That commit migrated three surfaces and left /api/history on its own allow-list regex; the two definitions disagreed for three and a half months until the Timeline was reported rendering "History unavailable" for any worktree branch containing a +. The regex rejected twenty-one printable-ASCII characters real git check-ref-format accepts (!"#$%&'()+,;<=>@]`{|} — the route test samples twelve of them), every non-ASCII character, and any leading underscore.

The rule fires on a regex literal .test(<branch>) or .exec(<branch>), or on <branch>.match(<regex>), where <branch> is an identifier or member whose name reads as a branch (branch, branchName, refName, targetBranch, ...). It is deliberately regex-only: string methods such as branch.startsWith('detached-') select by naming convention rather than validate, and the footprint audit found that shape to be the only false positive under a broader predicate.

The contract is a safety allow-list, not git check-ref-format. It is deliberately stricter where injection is the risk — a leading - is git-legal but rejected, and so is any of the 19 non-ASCII codepoints JS /\s/ treats as whitespace (U+00A0, U+1680, U+2000–U+200A, U+2028, U+2029, U+202F, U+205F, U+3000, U+FEFF), every one of which git check-ref-format accepts and git branch will create — and deliberately looser where it is not: feat/a..b, x.lock, .hidden, feat//x, a trailing /, and the characters ~, ^, ?, *, [, \ and the sequence @{ all pass the contract and fail git check-ref-format. That is safe at /api/history, where a branch only ever interpolates into a for-each-ref pattern* — with one caveat, on what gets iterated rather than what matches. for-each-ref truncates a pattern at the first glob-special byte (`, ?, [, `) and walks that prefix, so a branch starting with one turns refs/checkpoints/<branch>/ into a walk of refs/checkpoints/ before the filter reduces it to the empty result the match argument predicts. Measured on 30,000 loose refs that is 0.42s against 0.00s for a literal, and ~0.01s once pack-refs has run, which is the steady state git gc --auto keeps; a glob later in the segment does not widen at all. A call site that feeds a branch to a git rev needs its own additional check. Delegating to the contract does not by itself make a call site git-correct.

Where the contract is applied, and where it deliberately is not. It runs on every branch value that arrives over the wire, in two shapes. Directly, at the two GET query parameters: /api/history's (http/history-routes.ts:102) and /api/git/branch-info's (http/git-routes.ts:121). Inside the request schema, at every POST body's branch field — CheckoutRequestSchema and ShareTargetStatusRequestSchema through the shared refineBranchName helper (packages/core/src/schemas/api/share.ts:166), and LocalOpCloneRequestSchema through a bare .refine(isValidBranchName, ...) (packages/core/src/schemas/api/_envelope.ts:171). The refinement on the schema, not a hand-written call in the handler, is the idiom for a new route. Outside packages/server the contract also gates packages/core's share-URL serialize and decode (sharing/share-url.ts:178, :296) and the desktop worktree checkout (packages/desktop/src/main/worktree-service.ts:139).

Being on that list is not the same as being git-correct, and /api/git/branch-info is the standing example. computeBranchInfo interpolates its contract-validated branch into four git revisions — rev-parse --verify refs/heads/${targetBranch}, rev-parse --verify origin/${targetBranch}, cat-file -e origin/${targetBranch}:${path} (git-branch-info.ts:83-99) and diff --name-only HEAD..${targetRef} (git-dirty.ts:17) — while the contract admits ~, ^ and @{. By the paragraph above, that route still needs the additional check the contract does not supply; it has not got one yet.

/api/history also guards the value it falls back to when no parameter is sent — the local checkout's HEAD — so a checkout named with one of the 19 whitespace codepoints listed above gets a 400 there and a dead Timeline. That residual is known, not an oversight. /api/history/:sha takes no branch parameter, so its branch is only ever the checkout's own and it is left unguarded; the two handlers deliberately differ.

Nowhere else is a branch value contract-checked. HEAD reaches the checkpoint and WIP machinery through getCurrentBranch?.() ?? 'main' across packages/server/src — grep that expression for the live set rather than trusting a census here, which nothing pins — and guarding at the origin would silently re-namespace a user's checkpoints under main.

Two different exclusions, for two different reasons. packages/core is out of scope because it is the definition. docs/src/lib/share-splash.ts is out of scope for a weaker reason: it holds isValidShareBranch, a live re-implementation of the same seven rules, added after single ownership was declared. It is behaviourally faithful today, and docs/src/lib/share-splash.test.ts now pins that with an agreement test that drives a shared corpus through the public buildSplashViewModel seam and compares each verdict against isValidBranchName. The corpus is a sample, not a per-rule matrix: it pins the sampled verdicts, and an amendment outside it still needs the clone updated by hand. One rule is not merely unsampled but unreachable through that seam: an empty branch yields a four-segment path, which parseGitHubBlobUrl rejects on segment count (share-splash.ts:328) before it ever reaches the predicate, so the clone's own empty-string rule stays unpinned there. Converging it outright would pull the @inkeep/open-knowledge-core barrel into the docs client bundle — the module is reachable from 'use client' components and core declares no sideEffects — so it would first need the predicate extracted behind a narrow subpath export, which this change does not do.

What it does not catch: the regex must be a literal at the call site. A hoisted const BRANCH_RE = /.../; BRANCH_RE.test(branch), or new RegExp(...).test(branch), evades it — matching those needs dataflow analysis this rule does not attempt. No such shape validates a branch anywhere in packages/server/src today — every new RegExp site there was read during the footprint audit and none takes a branch value — so the rule's in-scope footprint is complete as written; the boundary is recorded so a future reader does not over-trust it.

Nor does it catch branch.search(<regex>), which answers with an index rather than a verdict and has no call site in packages/server/src today.

Nor does it catch a branch value held in a differently-named local. BRANCH_IDENTIFIER_RE matches branch and refName and any <x>Branch, each with an optional Name / Ref suffix; it does not match branchValue, headRef or branch_name. Widening the name predicate further trades recall against false positives on non-admissibility regexes over branch-shaped locals.

Validating something that is not a branch name, or enforcing a rule the contract deliberately omits? Suppress with a reason:

// oxlint-disable-next-line ok/no-hand-rolled-branch-validation -- <reason>

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/server/src/**/*.ts, with !**/*.test.ts + !**/*.test-helper.ts excluded.

Included: packages/server/src/**/*.ts, lint-plugins/ok-rules/__fixtures__/no-hand-rolled-branch-validation.fixture.tsx. Excluded: **/*.test.ts, **/*.test-helper.ts.

Rule: lint-plugins/ok-rules/rules/no-hand-rolled-branch-validation.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-hand-rolled-branch-validation.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-hand-rolled-branch-validation.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-hand-rolled-spinner

Flags animate-spin in any className / *ClassName attribute value. Loading spinners come from the Spinner primitive so reduced-motion support and the accessible name are inherited rather than remembered per call site.

animate-spin applied by hand keeps spinning through prefers-reduced-motion (a vestibular trigger) and carries no role or label unless the author adds them. Spinner bakes in motion-reduce:animate-none, role="status", and a localized aria-label. Pass icon when the glyph shape carries meaning (RefreshCw for syncing, Undo2 for reverting), and aria-hidden="true" when a wrapper or enclosing control already names the loading state.

Suppress a legitimately non-Spinner spin (a decorative flourish, a non-loading rotation) with // oxlint-disable-next-line ok/no-hand-rolled-spinner -- <reason> on the line above the class attribute; the attribute must be on its own line for the suppression to attach.

Unscoped, like the other rules in UNSCOPED_RULES — it applies wherever a class string can appear.

The \b delimiter is asymmetric in a way that is easy to misread: animate-spinner does NOT fire (the trailing boundary fails against a word character) but animate-spin-slow DOES (- is a boundary). That is the retired pattern's behaviour, kept deliberately — a slowed hand-rolled spin is still hand-rolled — and both halves are pinned in the fixture.

Rule: lint-plugins/ok-rules/rules/no-hand-rolled-spinner.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-hand-rolled-spinner.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-hand-rolled-spinner.uncached.test.mjs.

no-inline-tolerance-class

Forbids a public-mirrored test from writing a bridge normalization-class value inline as a string literal. BRIDGE_TOLERANCE_CLASSES (packages/core/src/bridge/normalize.ts) is the bridge normalizer's catalog of byte-difference equivalence classes it tolerates. A public test should assert observable normalizeBridge equivalence between inputs rather than hard-coding one of those class labels inline — the label is an internal classification detail, and pinning it inline both couples the test to that detail and re-declares the catalog outside the modules that own it. check-mirror-test-policy Check B already blocks a public test from importing the catalog symbol; this rule closes the complementary gap where a test re-encodes a class value inline (expect(applied).toBe('jsx-container-boundary-blank'), an array of class names), past the import check.

Identity, not substring. The or {} matches a string-literal node whose value is exactly a catalog member, so the names that appear legitimately on the public surface as prose are not flagged:

  • A class name inside a longer test-title sentence (test('… (block-separator-collapse class)', …)) — a different node value, so it does not fire.
  • A class name embedded in a docName with a prefix ('fr34-doc-start-thematic') — likewise a substring, not the whole value.
  • A class name in a comment — the rule matches the string-literal node, not trivia.

The match is quote-style independent (a single-quoted pattern matches the double-quoted form Biome emits). The four universal text-encoding classes — bom, crlf, trailing-whitespace, trailing-newline — are deliberately NOT matched: they are normalizations every text tool performs, not distinctive classes, and the public floor telemetry runtime (tolerance-telemetry.ts) surfaces them, so public tests legitimately assert that runtime emits class: 'crlf' for a CRLF input. The 12 markdown-fidelity classes plus those 4 universal classes partition the catalog exactly, and the fixture test's drift canary pins that partition — a class added to BRIDGE_TOLERANCE_CLASSES reddens until it is classified into one bucket.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to the public-mirrored test surface (packages/**/*.test.ts, *.test.tsx, *.e2e.ts), with the catalog-owning internal suites excluded as negative globs (see the rule's RULE_SCOPES entry in scope.mjs), so the catalog stays usable there but the inline form is forbidden on this surface.

The rule does NOT catch:

  • A class name built by concatenation or template interpolation ('doc-start-' + 'thematic') — neither operand is the whole value.
  • A class name in a template literal — the pattern matches string-literal nodes, not template content.

Scope (RULE_SCOPES['no-inline-tolerance-class'] in scope.mjs). Inline bridge normalization-class value ban. BRIDGE_TOLERANCE_CLASSES (packages/core/src/bridge/normalize.ts) is the bridge normalizer's class catalog; importing it into a test on this surface is blocked by check-mirror-test-policy Check B, and this rule blocks the complementary inline re-encoding. The catalog is owned by internal suites excluded from this rule's scope entry, so scoped() returns an empty visitor for them and the rule body never runs there; the inline form cannot come back through a new test on that surface. The fixture is in scope so its planted literals drive the fixture-file test.

Included: packages/**/*.test.ts, packages/**/*.test.tsx, packages/**/*.e2e.ts, lint-plugins/ok-rules/__fixtures__/no-inline-tolerance-class.fixture.tsx. Excluded: packages/md-conformance/**, packages/app/tests/fidelity/**, packages/core/src/markdown/**/*.test.ts, packages/core/src/bridge/**/*.test.ts, **/*.private.*.

Rule: lint-plugins/ok-rules/rules/no-inline-tolerance-class.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-inline-tolerance-class.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-inline-tolerance-class.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

require-windowshide-on-spawn

Windows console-flash prevention. Every hand-rolled node:child_process process-spawn (spawn / spawnSync / execSync / execFile / execFileSync, plus the repo aliases nodeSpawn and execFileAsync) must hide the Windows console it would otherwise pop — either by wrapping its options in withHiddenWindowsConsole(...) (from @inkeep/open-knowledge-server, the preferred form shared with the server package) or by an inline windowsHide: true.

Why. On Windows, windowsHide defaults to false. When a console-LESS parent — the OK server auto-started by an MCP host with stdio: 'ignore', or spawned detached — spawns a console-subsystem binary like git.exe, Windows creates a new console window that flashes on screen and vanishes, once per spawn. During an editing / agent-write session the per-edit git reads produce a steady stream of these. Hiding the console fixes it. The flag is a no-op on both macOS and Linux (neither allocates a console for child processes), so it is applied uniformly regardless of the command's target platform.

simple-git already sets windowsHide: true internally, so git routed through it (shadow repo, share, conflicts) is out of scope by nature — this rule governs only the hand-rolled call sites that bypass it.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{server,cli,desktop}/src/**/*.ts (the packages that spawn processes at runtime on Windows), with !**/*.test.ts + !**/*.test-helper.ts excluded.

Opting out (macOS/Linux-only spawns). For a spawn that only ever runs on macOS and/or Linux — codesign, sw_vers, an open(1) launch — hiding a console is meaningless. Either add the flag anyway (a harmless no-op that keeps the rule uniform) or suppress that one call with a reason:

// oxlint-disable-next-line ok/require-windowshide-on-spawn -- macOS-only (never spawned on Windows)
const r = spawnSync('codesign', [...], { ... });

Reference opt-out in the tree: packages/cli/src/commands/diagnose-health-checks/macos-codesig.ts. Same-named wrapper false positives (a local const spawn = deps.spawnDetached ?? …, or an injected spawn param) use the same suppression with a "not node:child_process" reason.

The rule does NOT catch: bare exec(...) (the identifier is too commonly shadowed); member calls (deps.spawn(...) — a different AST, so the real impl behind the injection is the enforced site); a windowsHide / withHiddenWindowsConsole written inside a spawn's callback body (would spuriously satisfy the check — no realistic occurrence).

Scope (RULE_SCOPES['require-windowshide-on-spawn'] in scope.mjs). Windows console-flash prevention: every hand-rolled child_process spawn in the runtime-spawning packages must hide the Windows console (via withHiddenWindowsConsole(...) or windowsHide: true), else a console-less parent (MCP-spawned/detached OK server) flashes a terminal window per spawn on Windows. Scoped to the server, CLI, and desktop packages that spawn processes on Windows. Tests excluded. simple-git sets the flag internally, so git routed through it is out of scope by nature.

Included: packages/server/src/**/*.ts, packages/cli/src/**/*.ts, packages/desktop/src/**/*.ts, lint-plugins/ok-rules/__fixtures__/require-windowshide-on-spawn.fixture.tsx. Excluded: **/*.test.ts, **/*.test-helper.ts.

Rule: lint-plugins/ok-rules/rules/require-windowshide-on-spawn.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/require-windowshide-on-spawn.fixture.tsx. Test: lint-plugins/ok-rules/tests/require-windowshide-on-spawn.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

require-utf8-multipart-parser

Multipart filename charset correctness. busboy(...) may only be constructed inside packages/server/src/multipart.ts; every other multipart body is parsed through its createMultipartParser(req, limits) factory, which hardcodes defParamCharset: 'utf8'.

Why. busboy defaults defParamCharset to latin1 — an inheritance from Content-Disposition's original MIME/email definition, not from the multipart/form-data rules. RFC 7578 governs this surface instead. It issues no receiver mandate — section 5.1.3 is explicit that a parser cannot assume any particular charset was used — so the default is ours to choose, and UTF-8 is the only defensible choice: section 4.2 records that "the encoding used for the file names is typically UTF-8", and the sender-side form-charset ladder in section 5.1.2 terminates at UTF-8. Browsers and Node/undici both put the name on the wire as raw UTF-8 bytes in the plain filename= parameter, so at the default every multi-byte sequence is read back as one mojibake code point per byte: café.png arrives as café.png, 会議メモ.pdf loses essentially all of its information. The damage lands at the transport-decode boundary, before any sanitizer or storage layer sees it, and it is not invertible there — the mojibake is indistinguishable from a filename the user legitimately owns.

The omission is invisible in review: busboy({ headers, limits }) reads as complete unless you happen to know the default. It shipped at two construction sites for exactly that reason, the second copied from the first along with its limits shape, which is why this is a mechanical gate rather than a review convention.

Presence match, not absence match. The sibling require-windowshide-on-spawn rule is shaped as "the call must contain windowsHide", because there the option's only correct value is true. That shape is too weak here: "the call must contain defParamCharset:" is satisfied by defParamCharset: 'latin1', which passes lint and reintroduces the bug. The factory takes no charset parameter, so routing through it removes the value hole entirely and reduces this rule to a plain presence check on the constructor. Both the wrong-value and the right-value-wrong-place cases are pinned as must-fire fixtures.

Scoped (see scope.mjs) repo-wide rather than per-package: server owns the only busboy dependency today, and that is exactly the state a new dependency elsewhere would change, silently. The sanctioned construction site and the test families are excluded. The Included: / Excluded: line below carries both halves, transcribed from scope.mjs, which is the entry the linter actually reads; this prose argues why the scope is shaped that way rather than restating it. The test exclusion is deliberate rather than copied: packages/server/src/http/local-api-dispatch.test.ts drives its own parser inside a synthetic /api/upload-lite handler that counts bytes and never decodes a non-ASCII name.

Opting out. There is no legitimate second construction site. A caller that needs different parser options (preservePath, highWaterMark, …) should widen the factory — that keeps the charset decision in one place, and forces the path-traversal reasoning preservePath demands rather than letting it be set in passing. If you genuinely must construct in place, suppress the one call with a reason:

// oxlint-disable-next-line ok/require-utf8-multipart-parser -- <reason>
const bb = busboy({ headers, defParamCharset: 'utf8' });

The rule does NOT catch: member calls (parsers.busboy(...) — a different AST); a call through a renamed binding (import bb from 'busboy'; bb(...)). Both are defeatable on purpose rather than by accident. A ReturnType<typeof busboy> type annotation is not a call expression and correctly does not fire; it is pinned as a negative fixture so a future pattern change cannot silently start flagging type positions. The behavioural backstop for all of these is packages/app/tests/integration/api-error-envelope/upload-filename-charset.test.ts, which asserts the decode end to end over real HTTP through both endpoints.

Scope (RULE_SCOPES['require-utf8-multipart-parser'] in scope.mjs). Multipart filename charset: busboy may only be constructed inside multipart.ts, whose factory hardcodes defParamCharset: 'utf8'. busboy defaults that option to latin1, which mojibakes every non-ASCII filename at the transport-decode boundary, irreversibly and invisibly in review. Repo-wide rather than server-scoped: server owns the only busboy dependency today, and that is exactly the state a new dependency in another package would change, silently. The factory itself is excluded so it can make the one sanctioned call. Tests are excluded deliberately, not by copy: http/local-api-dispatch.test.ts drives its own parser in a synthetic /api/upload-lite handler that counts bytes and never decodes a non-ASCII name. The .mts extension in the include list matches one file today, docs/vitest.real-source.config.mts, and is carried mainly as forward coverage: this gate exists because the defect spread by copy-paste, so an extension it cannot see is a hole by construction. The sibling class-proof-registration-discipline entry carries the same extension: its predicate is a CallExpression visitor and its scope already reaches ordinary TypeScript, so nothing about that rule argues for excluding .mts.

Included: **/*.ts, **/*.tsx, **/*.mts, lint-plugins/ok-rules/__fixtures__/require-utf8-multipart-parser.fixture.tsx. Excluded: **/node_modules/**, **/dist/**, **/*.test.ts, **/*.test.tsx, **/*.test.mts, **/*.test-helper.ts, packages/server/src/multipart.ts.

Rule: lint-plugins/ok-rules/rules/require-utf8-multipart-parser.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/require-utf8-multipart-parser.fixture.tsx. Test: lint-plugins/ok-rules/tests/require-utf8-multipart-parser.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-blind-agent-host-fanout

Scope discipline for user-global Agent Skill installs. Bans the skills CLI npm specs (skills@~1.5.0 and its caret / exact / latest variants) and the bare '--agent' argv token anywhere under packages/{server,cli}/src/**.

Why. installUserSkill used to shell out to npx -y skills@~1.5.0 add <dir> --agent '*' -g -y --copy. --agent '*' makes that CLI skip its own host detection and target every host in its registry (~75 and growing), so a single ok init wrote 110 directories across 54 tool-config homes in a real $HOME — 51 of them for tools the reporter had never installed (issue #820). OK's user-global skills are behavioural instructions autonomous software reads and acts on, so writing one into a tool's config dir is a scope-of-consent decision, not cosmetic clutter.

Nothing about the dependency was load-bearing: OK passed a local path (no source resolution), forced --copy (no symlinks), and the CLI writes no lockfile or state at global scope. It contributed a directory table that OK already maintains in core for project scope — while costing a floating-range npx -y fetch-and-execute at init time and third-party telemetry OK never opted out of. The install now writes directly, gated on detectUserSkillHosts, whose host set derives from HOSTS_WITH_USER_SKILL_DIR in packages/core/src/constants/editors.ts.

The rule bans the ingredients rather than the assembled command line, because the argv was built as an array of literals that no single AST node spans.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{server,cli}/src/**/*.ts. Tests are deliberately in scope (unlike the sibling spawn rule): a test that reintroduces the invocation reintroduces the fan-out, and the suite asserts the writer's behavior through the filesystem, never through argv.

The rule does NOT catch a spec assembled by concatenation or interpolation (`skills@${range}`), or the flag reaching a subprocess through a variable — the rule matches the string-literal node. Both are defeatable-on-purpose rather than accidental; the behavioural backstop is packages/server/src/skill-install.test.ts, whose "never creates a dotdir for a host that is not installed" case asserts the real filesystem outcome.

Adding a host that needs a different install mechanism? Add it to HOSTS_WITH_USER_SKILL_DIR and let the detection gate cover it — don't suppress this rule.

Scope (RULE_SCOPES['no-blind-agent-host-fanout'] in scope.mjs). Scope discipline for user-global Agent Skill installs (issue #820). OK writes these dirs itself, gated on detectUserSkillHosts; shelling out to the skills CLI with --agent '*' bypasses host detection and creates config dirs for tools the user never installed. Scoped to server + cli (where the user-global install lives). Tests are NOT excluded — a test reintroducing the invocation is as load-bearing as production code, and the suite asserts through the filesystem, never through argv.

Included: packages/server/src/**/*.ts, packages/cli/src/**/*.ts, lint-plugins/ok-rules/__fixtures__/no-blind-agent-host-fanout.fixture.tsx.

Rule: lint-plugins/ok-rules/rules/no-blind-agent-host-fanout.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-blind-agent-host-fanout.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-blind-agent-host-fanout.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-unwrapped-user-facing-string

Localization discipline. Makes a hardcoded user-facing string a build-visible defect rather than a convention someone has to remember — the gap that let the app accumulate residual English while the en catalog grew past 2,800 entries. Four surfaces:

  • Toast arguments — toast.error('…'), toast.success('…'), any toast.<method> whose first argument is a string literal.
  • JSX text children — <span>No documents match your search</span>.
  • UI-facing attributes — aria-label, placeholder, title, alt with a string-literal value.
  • UI-facing object properties — { label: 'Delete table' }, { description: 'Link to a page or external URL' }. Same six names as the attribute branch plus label and description.

The wrapped forms — <Trans>…</Trans>, t`…` from useLingui() / @lingui/core/macro — are not literals in the positions above and never fire.

Why object position needed its own branch. { title: '…' } renders the same words title="…" renders, but the attribute branch cannot see it, and that shape was where the residual English actually was: a sweep found 50 of them (menu items, picker entries, hover-preview panels, user-shown error envelopes) against zero the other three branches could reach. The name scope is what keeps it usable — the same measurement that produced the JSX prose test applies here, since an unscoped literal rule fires on every className, data-testid, and identifier in the tree. With the six names and the prose test, the branch found 1 hit in packages/app/src after the migration landed, and that one is a deliberate non-copy label carrying a biome-ignore.

Implementation note. The object-property branch visits Property nodes directly and keys on the property name, so the branch is written as the code snippet `$name: $value`. That binds to JS object-literal pairs only: a TypeScript member such as label: 'left' | 'right' inside a type or interface is a different node and is structurally out of reach, which is what keeps string-literal union types from firing.

Where a msg descriptor is the fix instead of t. When the object is module scope — a const array of menu items, a severity table, a language list — a t call in it resolves once at import and then keeps whatever language was active then, however correctly it is wrapped. I18nProvider re-renders context consumers, not the whole tree, so nothing corrects it later. Hold a msg descriptor in the object and resolve it with t(descriptor) at render, in a component that calls useLingui(); that hook call is also what subscribes the component to the locale change. BlockTypeSelector.tsx and editor/utils/severity.ts are the reference shapes.

The prose test, and why the branches differ. The two JSX branches require two letter-words separated by whitespace; the toast branch takes any literal. That asymmetry is measured, not stylistic: a toast argument is unambiguously user-facing, whereas raw JSX text in this codebase is overwhelmingly not prose. Firing on every JSX literal produced 53 hits across the product tree of which zero were genuine copy — keyboard-shortcut tokens (Ctrl+Shift+N), code identifiers (open-knowledge), sample paths (notes / release-plan.md), and brand marks (OpenKnowledge). With the prose test the same sweep produced 4 hits, all real (two aria-labels and one banner sentence in ConflictsSection.tsx, one toast in FileTree.tsx), which is the signal-to-noise ratio that makes a lint rule worth obeying. Note the two-word test also excludes tokens joined by punctuation, since notes / release-plan.md has no letter–space–letter run.

<Brand> icon is exempt in-pattern: it is the accessible name of a third-party mark, and translating it renames the product.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{app,desktop,plugin}/src/**, .ts as well as .tsx — the toast branch's dominant shape is a plain lib/ helper, not a component. Exemptions as negative !-globs: !packages/app/src/editor/** (ProseMirror/CodeMirror-managed views, whose placeholder and title strings are editor affordances), !packages/app/src/components/ui/** (shadcn primitive wrappers — attribute strings there are prop plumbing), !packages/desktop/src/main/** (the Electron main process — see below), and !**/*.test.ts / !**/*.test.tsx / !**/*.dom.test.tsx.

packages/desktop/src/main/** is excluded because lingui extract reads packages/app/src only, so a t macro written there reaches no catalog; main's one translated surface, the native menus, goes through main-i18n.ts, which looks its labels up by hash against the renderer's compiled catalogs. The object-property branch fires on 20 of main's dialog.showMessageBox templates and OTel metric descriptions, and asking for a fix that does not exist is how a rule earns a blanket suppression. Main's four sibling dirs (preload / renderer / shared / utility) stay in scope.

The rule does NOT catch:

  • Single-word JSX copy — <Button>Save</Button>. The known cost of the prose test; nothing statically separates Save from Discord. The backstop is the Simplified-Chinese coverage sweep, where residual English is unmissable against Han script.
  • Object properties outside the six scoped names — { message: 'Server returned…' }, { error: '…' }, { detail: '…' }. Measured rather than assumed: those three names are dominated by log lines and developer diagnostics ({ detail: 'copilot is terminal-only; launch via requestTerminalLaunch' }), so scoping them in would make the rule's first act a demand to translate something no reader ever sees. The user-shown members of that set were wrapped by hand.
  • Module-const strings — const TOAST = '…'. Not a property; a separate shape, and one where a t at module scope would be a freeze rather than a fix.
  • A ternary or call in property position — { error: e instanceof Error ? e.message : 'Unknown error' }. the rule matches the whole node's text, so the value has to be a literal; a value that merely contains one would also match { label: cn('a b') }.
  • A JSX expression-child string literal — <span>{'Loading'}</span>, or an attribute written aria-label={'…'}. The value node opens with {, which is what distinguishes a literal from a wrapped macro.
  • Template literals anywhere, including a toast description.
  • The CLI command surface — packages/cli/src/**, deliberately never localized.

Scope (RULE_SCOPES['no-unwrapped-user-facing-string'] in scope.mjs). Localization discipline — a shipped hardcoded string is a build-visible defect, not a convention someone has to remember. Scoped to packages/{app,desktop,plugin}/src, .ts included: the toast branch's dominant shape is a plain lib/ helper, not a component. Exemptions: - packages/app/src/editor/** — ProseMirror/CodeMirror-managed views, whose placeholder and title strings are editor affordances rather than chrome copy (matches the no-raw-html-interactive-element exemption). - packages/app/src/components/ui/** — shadcn primitive wrappers; their attribute strings are prop plumbing, not copy. - packages/desktop/src/main/** — the Electron main process. lingui extract reads packages/app/src only, so a t macro here reaches no catalog; main's one translated surface (the native menus) goes through main-i18n.ts, which looks labels up by hash against the renderer's compiled catalogs. Firing on its dialog templates would ask for a fix that does not exist. The other four sibling dirs (preload / renderer / shared / utility) stay in scope. - *.test.ts / *.test.tsx / *.dom.test.tsx — test fixtures aren't user-facing.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, packages/desktop/src/**/*.ts, packages/desktop/src/**/*.tsx, packages/plugin/src/**/*.ts, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-unwrapped-user-facing-string.fixture.tsx. Excluded: packages/app/src/editor/**, packages/app/src/components/ui/**, packages/desktop/src/main/**, **/*.test.ts, **/*.test.tsx, **/*.dom.test.tsx.

Rule: lint-plugins/ok-rules/rules/no-unwrapped-user-facing-string.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-unwrapped-user-facing-string.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-unwrapped-user-facing-string.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-physical-direction-utility

Reading-direction discipline. Chrome layout takes its side from the reading direction, never from a hardcoded left or right, so that adding a right-to-left locale is a catalog change rather than a chrome-wide retrofit. The rule flags physical margin, padding, and inset Tailwind utilities — ml-/mr-, pl-/pr-, left-/right- — and asks for ms-/me-, ps-/pe-, start-/end- instead. In a left-to-right locale the two compile to the same used value, so draining the backlog is a visual no-op today and correct later.

It matches class strings, not stylesheets. That is where this codebase's physical properties live: the sweep that produced this rule found 148 of them in className values against 31 CSS declarations, and 24 of those 31 style the editor or the rendered document rather than the chrome. One jsx_attribute branch covers both spellings, because the bound node is the whole initializer clause — a plain className="ml-2 flex" and a multi-line className={cn('…', cond && 'pr-1.5')} are the same node to the pattern. The name is matched as *lassName, so component APIs that forward a second class string (containerClassName, overflowClassName) are in scope under their own names.

Two shapes look physical and are not, and both are measured rather than assumed:

  • inset-x-* is already logical. Tailwind v4 compiles inset-x-0 to inset-inline: 0. It is absent from the pattern for that reason, not as a carve-out.
  • left-1/2 is the centering anchor. It exists to be cancelled by the -translate-x-1/2 beside it, and at 50% the offset is symmetric, so it centers correctly in both directions; start-1/2 would flip the anchor while the translate kept pulling the same way. The pattern requires a delimiter after a numeric value, which leaves every fractional inset alone — all 10 left-1/2 sites in the tree carry that translate.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{app,desktop,plugin}/src/**/*.tsx. .tsx only: the single branch matches a JSX attribute, so a .ts glob would be dead scope rather than extra coverage. Exemptions as negative !-globs: !packages/app/src/editor/** (ProseMirror and CodeMirror own their DOM and take per-string direction from the text rather than from the chrome), !packages/app/src/components/ui/** (shadcn primitives are regenerated by shadcn add, so an edit there is overwritten on the next pull), and !**/*.test.tsx / !**/*.dom.test.tsx.

Pre-rule backlog (ratchet pattern). The 66 files that pre-date the rule carry a file-level // oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — … header, same contract as no-raw-html-interactive-element: the comment list across the codebase IS the visible backlog, and review treats each header as a backlog marker rather than a free pass. Drain a file by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting the header — the rule starts firing again immediately, so a partial pass that misses one utility fails the gate. 66 of the 375 chrome files in scope carry a header (127 utilities in total), so the rule is live on the other 309 today.

The rule does NOT catch:

  • Class strings outside a class prop — { containerClassName: 'bottom-3 left-3' } as an object-literal property, or a module-level const ROW = 'ml-2 flex'. Five sites in the tree: four object-literal properties in GraphLegend.tsx, one const in editor-tabs-chrome.ts. A hand fix, not a rule — the name predicate keys on a JSX attribute, and widening it to every string-valued property is the false-positive surface the negative cases below the fixture's group 6 exist to bound.
  • Fractional insets — left-1/3 alongside the left-1/2 the exclusion is aimed at. One site, and separating them costs more regex than it buys.
  • CSS declarations — margin-left: in globals.css (25 sites) or inside a unsafeCSS template literal (6, all in the file-tree and skill-cluster shadow styles). A language css plugin would reach the stylesheet — verified working in Biome 2.4.15 — but not the template literals, and 24 of the 25 stylesheet sites style the editor or the rendered document, surfaces this rule exempts anyway. One chrome site remains: .tabs-strip-add.
  • Physical border-*, rounded-*, and text-left/text-right — real direction hazards, outside this rule's margin/padding/inset scope.

Scope (RULE_SCOPES['no-physical-direction-utility'] in scope.mjs). Reading-direction discipline. The rule's only branch matches a JSX attribute, so the scope is .tsx alone — a .ts glob would be dead scope, not extra coverage. Exemptions: - packages/app/src/editor/** — ProseMirror/CodeMirror own their DOM and take per-string direction from the text rather than from the chrome (matches the no-raw-html-interactive-element exemption). - packages/app/src/components/ui/** — shadcn primitives are regenerated by shadcn add, so an edit here is overwritten on the next pull. - *.test.tsx / *.dom.test.tsx — fixtures aren't rendered chrome.

Included: packages/app/src/**/*.tsx, packages/desktop/src/**/*.tsx, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-physical-direction-utility.fixture.tsx. Excluded: packages/app/src/editor/**, packages/app/src/components/ui/**, **/*.test.tsx, **/*.dom.test.tsx.

Rule: lint-plugins/ok-rules/rules/no-physical-direction-utility.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-physical-direction-utility.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-physical-direction-utility.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-raw-route-hash-construction

Sole route-hash builder. packages/app/src/lib/doc-hash.ts owns the #/ route prefix. Every other file in the app asks it for a hash — hashFromDocName, hashFromFolderPath, hashFromAssetPath or encodeShareTargetForHash — rather than joining a name onto the prefix itself.

Why. A doc or folder name reaches the router through window.location.hash, and the WHATWG fragment percent-encode set does not include #, ? or %. A hash built by hand therefore hands those characters to docNameFromHash as routing syntax: it reads the text before the first one, so a leading # yields null and the app opens a New Tab instead of the document, while a # mid-name resolves silently to a truncation. The rule is structural rather than a set of fixes because the prefix is trivially easy to spell, so hand-built copies accumulate faster than they are found, and each one fails silently: the link is still built, it just points somewhere else.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/app/src/**/*.{ts,tsx}, with !packages/app/src/lib/doc-hash.ts (the sanctioned builder) and !**/*.test.{ts,tsx} (tests write expected hashes as literals) excluded. packages/server builds preview URLs through its own encodeDocName and is out of scope.

Reading a hash is untouched: hash.startsWith('#/'), hash === '#/' and the bare '#/' content-root sentinel are comparisons, not constructions, and the fixture pins that they stay legal.

The rule matches a node's own source text, so a comment, JSX text or a regex literal spelling the shape cannot trigger it — the fixture pins all three. The rule does NOT catch: the prefix behind a named constant (const P = '#/'; P + name), which needs dataflow and has no occurrence today; name + '#/', the prefix on the right of a concatenation, which does not build a route hash; a helper that takes the prefix as a parameter; and the read side, where editor/internal-link-helpers.ts still carries a hand-rolled parser — a different rule.

Scope (RULE_SCOPES['no-raw-route-hash-construction'] in scope.mjs). Sole route-hash builder. lib/doc-hash.ts owns the #/ prefix; every other file in the app asks it for a hash. Building one by hand emits the doc name unescaped, and the browser leaves #, ? and % alone in a fragment, so the parser reads them as routing syntax and the navigation lands somewhere else. Excluded: lib/doc-hash.ts itself (the sanctioned site) and tests, which build expected hashes as literals. packages/server has its own encodeDocName for preview URLs and is out of scope.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-raw-route-hash-construction.fixture.tsx. Excluded: packages/app/src/lib/doc-hash.ts, **/*.test.ts, **/*.test.tsx.

Rule: lint-plugins/ok-rules/rules/no-raw-route-hash-construction.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-raw-route-hash-construction.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-raw-route-hash-construction.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-demoted-dialog-confirm

Dialog-footer emphasis hierarchy. A confirmation dialog's footer holds two actions, and the confirm has to outrank the dismiss. secondary is the one Button variant that draws no border and whose fill is imperceptible: bg-secondary sits within roughly 1.1:1 of the dialog surface in both light and dark, so the button reads as flat text rather than an action. ghost, link and link-muted are flat at rest too, so secondary is not the only variant that could lose the contest with the outline Cancel standing beside it. The rule stays narrow to secondary because those three are not plausible footer confirms: ghost and link-muted are text-muted-foreground by definition, and link is underline-on-hover text. Nobody reaches for them intending a primary action, so flagging them would report a shape that does not occur rather than an inversion someone authored by accident. Every remaining variant either fills with a contrasting color or draws a border. A footer authored that way inverts the hierarchy: the escape action reads as the primary one, and the actual primary CTA reads as de-emphasized text. The rule flags a DialogFooter or AlertDialogFooter containing variant="secondary" and asks for default (or destructive, when the action is irreversible removal).

The typographic treatment comes from the footer, not the variant. DialogFooter and AlertDialogFooter carry [&_button]: and [&_[data-slot=button]]: pairs of font-mono uppercase, so every footer action is drawn in the footer's typeface whatever variant it takes. Nothing needs hand-adding at a call site, and a className="font-mono uppercase" on a footer button is redundant rather than load-bearing. default, destructive and outline-mono also bake the pair into their variant strings — that is what dresses them outside a footer, so do not delete it on the strength of this paragraph.

Why two selectors rather than one. Neither predicate covers every footer shape on its own, so the rule is their union:

Footer action button element [data-slot=button]
plain <Button> yes yes
<Button asChild> rendering an <a> no yes
AlertDialogCancel / AlertDialogAction yes no
DialogClose asChild wrapping a Button yes no

Radix's Slot lets the child's data-slot win, so the three wrapper primitives stamp their own slot name and fall out of a slot-only selector; <Button asChild> rendering an anchor is not a <button> element and falls out of a tag-only one. Keying on both covers all five. Keep the descendant combinator: ShareBranchSwitchDialog wraps three footer buttons in a <div>, which a child-scoped variant would miss.

Two consequences worth knowing before you fight them:

  • The footer outranks the button. The compiled rule is .…\:font-mono button { … } at specificity (0,1,1); a class on the button itself is (0,1,0) and loses, and tailwind-merge cannot arbitrate because the two declarations sit on different elements. Opting one footer button out of the treatment therefore needs the important modifier — font-sans! / normal-case! — not a plain utility.
  • A footer action that is neither a <button> nor a Button styles itself. The bare <a> in InstallInClaudeDesktopDialog's footer is the one live instance, and it carries its own font-mono tracking-wide uppercase. That is deliberate: the footer dresses the design system's buttons, and a hand-rolled action carries its own treatment. Promoting such a link to <Button asChild> brings it under the rule.

Historically the two sites this rule was written against had reached for variant="secondary" plus a hand-added className="font-mono uppercase", which recovered the footer's typography while leaving the confirm without a perceptible fill. That is what makes the inversion easy to author by accident: the footer still looks like a footer. The canonical shape omits the prop entirely and lets defaultVariants supply default, matching every other confirm dialog in the tree.

Matched as one whole JSX element. The rule visits the footer element and tests its full source text, because a footer holds two or more children and the confirm can sit at any position among them. Testing the whole element text matches the entire node text, so the leading tag name anchors the match to footers themselves rather than to any ancestor that happens to contain one.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/{app,desktop,plugin}/src/**/*.tsx. .tsx only: the single branch matches a JSX element, so a .ts glob would be dead scope rather than extra coverage. Exemptions as negative !-globs: !packages/app/src/components/ui/** (the dialog and button primitives themselves, regenerated by shadcn add), and !**/*.test.tsx / !**/*.dom.test.tsx (a test that renders the demoted shape on purpose is pinning the regression, not shipping it).

The rule does NOT catch:

  • Indirect composition. A confirm passed into the footer as a prop, or rendered by a shared sub-component, sits outside the footer element's text. The ceiling is deliberate: it keeps the rule to one structural predicate rather than a type-aware analysis.
  • The other direction. A footer whose dismiss is over-emphasized (a default Cancel next to a default confirm) is a hierarchy problem this rule has no predicate for, since both buttons carry a fill.
  • Non-footer emphasis inversions. A CardFooter or toolbar pairing a muted primary action with a prominent secondary one. secondary outside a dialog footer is a legitimate choice, which is why the scope is the footer element.

Suppress a footer that genuinely wants a muted tertiary control alongside a properly-weighted confirm with an inline // oxlint-disable-next-line ok/no-demoted-dialog-confirm -- <reason>.

Scope (RULE_SCOPES['no-demoted-dialog-confirm'] in scope.mjs). Dialog-footer emphasis hierarchy. secondary is the one Button variant whose fill is low enough in contrast to lose the emphasis contest with the outline dismiss standing beside it — a footer authored that way reads with its hierarchy inverted. The rule's only branch matches a JSX element, so the scope is .tsx alone; a .ts glob would be dead scope, not extra coverage. Exemptions: - packages/app/src/components/ui/** — the dialog and button primitives themselves, regenerated by shadcn add (matches the no-physical-direction-utility exemption). - *.test.tsx / *.dom.test.tsx — fixtures aren't rendered chrome, and a test that renders the demoted shape on purpose is pinning the regression, not shipping it.

Included: packages/app/src/**/*.tsx, packages/desktop/src/**/*.tsx, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-demoted-dialog-confirm.fixture.tsx. Excluded: packages/app/src/components/ui/**, **/*.test.tsx, **/*.dom.test.tsx.

Rule: lint-plugins/ok-rules/rules/no-demoted-dialog-confirm.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-demoted-dialog-confirm.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-demoted-dialog-confirm.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-blocking-error-box

Desktop error reporting. No code under packages/desktop/src calls showErrorBox on Electron's dialog, or on anything shaped like it. Errors are shown with showErrorDialog from packages/desktop/src/main/error-dialog.ts, an async showMessageBox attached to a parent window.

Why. dialog.showErrorBox is synchronous and takes no parent window. On Linux it runs gtk_dialog_run, which holds the main thread in a nested GTK loop until someone presses its button. With no parent, the window manager can stack the dialog behind the window it is reporting on, and the dialog has no taskbar entry, so nothing on screen shows it is still open. In PRD-9099 that left the Project Navigator on "Opening …" indefinitely: the ok:project:open reply could not leave the main process. SIGTERM was ignored as well, because both Chromium's shutdown task and the app's Node signal handler wait for the main loop. showMessageBox with a parent stays above that window, and the main loop keeps running while it is open.

Scoped (see the rule's RULE_SCOPES entry in scope.mjs) to packages/desktop/src/**/*.ts, the only package that runs in Electron's main process. **/*.test.ts and **/*.test-helper.ts are excluded, because tests stub the method by name.

The rule matches a call of a non-computed .showErrorBox member, whatever the receiver: dialog, electron.dialog, or an injected dialog host. It does NOT catch a bare showErrorBox(...) identifier, a computed dialog['showErrorBox'](...), or a reference taken without calling it (const f = dialog.showErrorBox). Those shapes have no realistic occurrence.

Opting out. There is no sanctioned use after app is ready. Before ready, Electron prints the error box to stderr on Linux instead of showing it, so even an early-boot error needs a different reporting path.

Rule: lint-plugins/ok-rules/rules/no-blocking-error-box.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-blocking-error-box.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-blocking-error-box.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-unconverted-git-pathspec

Git pathspec discipline. Fires on a hand-written '--' string literal in an array literal, or as a direct argument of a .raw(...) varargs call, anywhere under packages/{core,server,cli,desktop}/src/** — unless the argv's leading non-flag token is one of the five verbs whose -- operands are not pathspecs. The array branch consults no git token of any kind; see the over-catch note below. The tail after the separator is built with pathspecArgs(paths) from packages/core/src/git-pathspec.ts, which emits the separator and the :(literal) conversion together.

Why. git parses a pathspec argument position as a pattern language, and -- does not disable that parsing: it stops option parsing only. A filesystem path handed over bare is therefore reinterpreted whenever its first path segment carries a metacharacter. PRD-8638 is what that costs: a doc named :colon.md fatals the push cycle, a doc named :!bang.md reads as exclusion magic and is silently subtracted from the set it was meant to join, and a wildcard-named skill directory makes ls-files --error-unmatch report an untracked file as tracked. Thirty-six pathspecArgs call sites across fourteen files now carry the conversion. That count is post-fix call sites, not pre-fix -- literals: the two differ because one sync-engine.ts staging loop collapsed two pre-fix literals into a single call, and four shadow-repo.ts / persistence.ts sites had no -- to count in the first place. Every converted site that did carry a -- already had it, which is what made the omission look handled. The pattern is not a regression: three of those sites are present verbatim in the initial Copybara mirror-import commit 6bd7d8ba7d.

Prior art in the dependency. [email protected] ships a pathspec(...) helper (@simple-git/[email protected]), and its suffixPathsPlugin — registered unconditionally in gitInstanceFactory — already routes marked arguments, and everything after a '--', into the command suffix and re-emits exactly one separator. The separator half of pathspecArgs's contract is therefore something simple-git already guarantees for every sg.raw(...) site here. The helper adds no magic word, so pathspec(':colon.md') still reaches git bare: the :(literal) half, which is the half PRD-8638 is about, is not available from it. pathspecArgs is also package-agnostic, covering the two converted sites the plugin never sees — rename-log.ts's spawn and git-exclude.ts's execFileSync. The rule deliberately does not treat pathspec(...) as a non-violation, because accepting it would wave through an unconverted operand. (Same check as the require-windowshide-on-spawn note above, which records what simple-git already covers.)

A fail-closed allowlist, not suppressions. Five verbs take -- operands that genuinely are not pathspecs, and the rule carries them in NON_PATHSPEC_VERBS rather than asking the production files that use them to suppress it: hash-object takes file arguments, clone takes a URL and a directory, worktree add takes a commit-ish, mv takes literal source and destination paths (verified against real git 2.49.0: git mv -- ':(literal):colon.md' moved.md reports fatal: bad source, source=:(literal):colon.md, destination=moved.md, so converting that operand would break the case-only rename it implements), and update-index takes literal file names (verified against real git 2.50.1: with lit.md staged, git update-index --force-remove -- ':(literal)lit.md' exits 0 and leaves lit.md in the index, and git update-index --force-remove -- 'sub/*' leaves sub/tracked.md in the index, so neither the magic word nor a wildcard is parsed). That verification covers --force-remove, the only update-index mode that passes a -- separator here (the other four call sites are --add --cacheinfo, which carry no separator, so the rule never inspects them); the allowlist entry is nevertheless verb-wide, and update-index --again does parse its -- operands as pathspecs (verified against real git 2.50.1: with sub/tracked.md and other.md both staged ahead of HEAD and then modified again, git update-index --again -- 'sub/*' refreshes sub/tracked.md and leaves other.md at its earlier blob, so the wildcard matched). Nothing calls --again today, so nothing is unprotected; an author who adds one needs pathspecArgs for its operands and will not be reminded by this rule. update-index still needs the separator, which is why it is on this list rather than off the rule's radar: without it, a staged path named -foo.md.tmp.<uuid> reports error: unknown switch 'f'-class option parsing instead of being removed. This README treats an oxlint-disable header as a backlog marker, so a permanent legitimate use is a semantic mismatch there. The verb is resolved positionally — the first token that is not a flag, skipping the value of a -c / -C pair, so clone is still recognised behind a -c core.symlinks=false prefix — rather than by membership anywhere in the argv, so a path operand or a commit message that happens to read mv cannot exempt the argv it sits in. Each argv array is judged on its own: an array of argvs is not flattened into one bag, so one allowlisted row cannot disarm its siblings. The polarity is deliberate: a verb the rule has never seen fires rather than silently passing, so a new git surface is opted in by a reviewer rather than by omission.

Scope (RULE_SCOPES['no-unconverted-git-pathspec'] in scope.mjs). The four packages that build git argvs today. git-pathspec.ts is excluded because it is the one sanctioned emitter of the separator. Tests and test helpers are excluded per the no-raw-html-interactive-element precedent: fixture code that seeds a hostile filename deliberately passes a correct :(literal) pathspec by hand, and that is the control proving git can do the right thing, not a production argv.

Included: packages/core/src/**/*.ts, packages/server/src/**/*.ts, packages/cli/src/**/*.ts, packages/desktop/src/**/*.ts, lint-plugins/ok-rules/__fixtures__/no-unconverted-git-pathspec.fixture.tsx. Excluded: packages/core/src/git-pathspec.ts, **/*.test.ts, **/*.test-helper.ts.

The rule does NOT catch:

  • A pathspec operand passed with no -- at all. sg.raw('add', contentRoot) is the shape four positions in shadow-repo.ts and persistence.ts used, and the predicate is keyed on the separator, so it is structurally invisible. That shape is also invisible to a '--' source grep, which is how it survived the original enumeration. The same blindness covers simple-git's typed path-taking methods — .add / .rm / .checkout / .mv take a pathspec operand with no separator to key on. The only production instance today is the benign constant git.add('.') at packages/cli/src/commands/share/publish.ts.
  • GIT_LITERAL_PATHSPECS / --literal-pathspecs. Under that setting git takes the string :(literal)x as a filename and matches nothing, so it is mutually exclusive with everything this rule steers callers toward. Nothing detects it; adopting it would silently break every converted operand in the tree. An operator who already exports it can restore magic parsing per invocation with git --no-literal-pathspecs (shipped in git 1.8.2, so it predates this project's MIN_GIT_VERSION floor rather than being bounded by it) or GIT_LITERAL_PATHSPECS=0.
  • A separator assembled at runtime — a variable, a template literal, or a concatenation holding --. No single node carries the value. Defeatable on purpose rather than by accident.
  • A varargs '--' passed to anything other than .raw. simple-git's raw is the only varargs git API in the tree; a new one would need adding to the predicate.
  • Whether the operand was already converted. The rule enforces the boundary, not the spelling — double conversion is closed at compile time instead, by toPathspec's parameter type and pathspecArgs's branded return type both rejecting an already-converted argument. That closure is pinned inside the typecheck program by packages/core/src/git-pathspec.type-tests.ts; a *.test.ts file cannot carry the pin, because every package tsconfig excludes tests from the program and an unevaluated @ts-expect-error reds nothing.

It also over-catches, in the same direction. The array branch fires on any array literal in those packages holding a bare '--', git argv or not, so const seps = ['--', '==']; draws a diagnostic whose message names pathspecArgs. That is the price of the polarity above: a predicate narrow enough to prove an array is a git argv would also let an unrecognised git surface through.

The behavioural backstop is packages/server/src/git-pathspec-name-invariance.test.ts and its CLI sibling, which drive real git over hostile filenames end to end.

Rule: lint-plugins/ok-rules/rules/no-unconverted-git-pathspec.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-unconverted-git-pathspec.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-unconverted-git-pathspec.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-sentinel-signal-target

Owned-process signalling. process.kill(target, signal) — and the desktop test-support reaper seam signalOwnedGroup / signalOwnedPids / reapOwnedTree when no sender is injected (that seam is not in this tree yet; the rule covers it ahead of time so the gate is in place the day it lands) — never receive a target that is (a) a literal 0, 1 or -1, (b) a ?? <n> / || <n> fallback to a number, or (c) a parse of text — Number(...), parseInt(...), parseFloat(...), or the Number. spellings of the latter two. A signal-0 liveness probe (process.kill(pid, 0)) sends nothing and is exempt, whatever the target.

Why. On POSIX, kill(0, sig) signals the caller's whole process group, kill(-1, sig) every process the user owns, and kill(-pid, sig) a group. On 2026-09-20 and 21 a desktop unit test killed every process on a developer's Mac three times, Terminal included: it called signalOwnedGroup(1, 'SIGKILL') to prove a guard refused it, a mutation loop had weakened the guard to pid > 0, and process.kill(-1, …) went through. The mutation loop was killed before its own revert step, so the mutant stayed on disk and every later run of the suite repeated the kill. The same sentinel shape was already live on main: process.kill(pid ?? 0, 'SIGKILL') in a test reaper, and process.kill(Number(readFileSync(pidFile)), 'SIGKILL') in a finally — an empty pidfile parses to 0. Both shipped green: nothing in pnpm lint or pnpm check looked at what a kill was fed. Canonical prose: the "Never signal a pid you did not spawn" STOP rule in the workspace AGENTS.md; this rule encodes its decidable subset.

Sanctioned shapes. Every shape in this list works on this head and needs no seam; only the injected sender below waits on one.

  • Signal the handle you spawned — child.kill(signal).
  • Or a pid you took from that handle — child.pid, wrapped or negated for its group, only while the handle has not reported exit, checked in the same turn as the signal. Negation reaches a group only if you spawned it detached, since -pid addresses the group whose pgid is that pid and an ordinary child leads none; on a non-detached child it raises ESRCH, which a catch {} around the kill turns into a surviving process.
  • Or that group after the handle reports exit, only while its lifeline holds it. The maintainers' gate tooling, which the public mirror does not carry, starts each gate step under a guard that forks a lifeline watcher into the step's process group before it runs the step. While that watcher, a live member, holds the group, no other group can take its pgid, so the step's supervisor may still signal -child.pid after the step's first process exits. Once the lifeline has closed or been released, the group is no longer a target.
  • The lifeline's own kill -s KILL 0. That watcher ends the group it belongs to with kill -s KILL 0 when its supervisor's end of the lifeline closes. It is the only signal to a literal 0 the STOP rule allows, and these two are its only acts beyond signalling a handle before it exits.
  • Negation is not laundering. -<expr> is judged by exactly the same tests as <expr>, so a negated ?? <n> fallback fires just as the bare fallback does, and only a pid already taken from a handle survives the minus sign.
  • Filter a nullable pid out of a list instead of substituting a sentinel.
  • A pid parsed from a file or a ps row is not a signal target, because isValidLockPid() checks its range, not its owner. Stop that process through its owner, or report it. The one sanctioned exception is a server.lock pid at the two sites that stop a server through its lock, runStop (packages/cli/src/commands/stop.ts) and the desktop's terminateServerByPid (packages/desktop/src/main/window-manager.ts). Each signals only after assessLockHolder (packages/server/src/process-identity.ts) reads the pid's current holder as the process that wrote the lock, immediately before every signal, and refuses otherwise; a reused pid is never signalled. A new site that stops a server through its lock routes through one of these two rather than adding its own kill.

The reaper seam is what is absent. signalOwnedGroup, signalOwnedPids, reapOwnedTree and recordingSignalSender have no definition on this head, so the seam's own sanctioned shape — an injected sender — is the one thing you cannot write here yet. Once the seam lands, a guard test that must feed it a sentinel passes recordingSignalSender().send — not the recorder itself — in the sender slot, which is the third argument to signalOwnedGroup and signalOwnedPids but the fourth to reapOwnedTree, and asserts the recorded calls. The rule stops firing only when a real sender value occupies that slot: passing undefined or void 0 explicitly injects nothing and still fires, and passing process.kill itself is no escape either.

The rule does NOT catch:

  • A sentinel held in a variable (const target = 1; process.kill(target, …)) or a ps-parsed pid that reaches a kill through an untyped variable — data flow the untyped AST cannot see, left to the STOP rule and review.
  • A guard weakened inside the seam — that is what the seam's injected sender exists for, since the mutant then fails a test instead of the host.
  • Whether a pid taken from a handle is signalled while that handle is still unreaped: a handle's pid, negated or not, passes whatever the child's state (fixture n2, n3, n12); lifecycle is data flow the AST cannot see, left to the STOP rule and review until a seam that takes held, unreaped handles lands on main.
  • Anything oxlint.config.ts excludes from selection — ignorePatterns drops /reports/** and /specs/** before any rule sees them, and naming such a file positionally on the command line does not override it. Those two trees hold 164 executable .ts/.mjs/.js files, 4 of which call process.kill today; they are the local spike-harness class of script this incident came from, and no oxlint rule reaches them. See §3 of the authoring guide for the measurement.

Unscoped (workspace-wide in the scope table's sense — it carries no RULE_SCOPES entry and sits in UNSCOPED_RULES in scope.mjs, so nothing here narrows it; selection still excludes the trees named just above): a fabricated signal target is wrong in every package, and in test code most of all.

Opting out. There is no legitimate sentinel signal target. A liveness probe is already exempt by its signal argument; anything else is fixed at the source, not suppressed.

Rule: lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs. Fixture: lint-plugins/ok-rules/__fixtures__/no-sentinel-signal-target.fixture.tsx. Test: lint-plugins/ok-rules/tests/no-sentinel-signal-target.uncached.test.mjs. See PRECEDENTS.md #42 for the custom-rule convention.

no-hand-rolled-test-file-suffix

Scanners classify test-only TypeScript through isTestOnlySourceFile. Its predicate tests pin the supported naming families and direct Node import. Local suffix checks omitted helpers and type checks and caused false production-code findings. This section is the canonical scanner rule; keep it and the implementation aligned when either changes.

The default predicate includes Vitest tests, test helpers, type checks and Playwright files. Pass vitest, helper, typecheck or playwright when selecting one kind. A scanner selecting runnable tests must retain its runner and extension limits; test-only does not mean runnable by Vitest. The .uncached.test.ts form is already covered by .test.ts. TSX variants share their TS family.

The rule flags literal suffix checks with endsWith or includes, test-kind infix checks with includes, and direct literal suffix regexes used by test, exec, match or search. It recognizes static templates and computed method names. It leaves extension checks, full basenames, glob declarations, source-text extraction, regex replacement, and mixed JavaScript/TypeScript runner-discovery regexes alone. It does not trace aliases, computed suffixes, hoisted regexes or arbitrary equivalent regex expressions.

Included: **/*.ts, **/*.tsx, **/*.mts, **/*.cts, **/*.js, **/*.jsx, **/*.mjs, **/*.cjs. Excluded: test-support/test-only-source-file.mjs, lint-plugins/no-comments/portability.test.mjs.

The shared module owns the definition. The portability test inventories only the sibling dependency-free .mjs implementation modules; it does not classify TypeScript, and its test-file exclusion remains local. Scanners that deliberately inspect test helpers retain that scope rather than inheriting the production default.

The fixture pairs 15 violations with adjacent negatives. The self-test also plants a check and its shared-predicate replacement side by side under scripts/, lints both with the real lint configuration in one invocation, expects the diagnostic on the planted check alone, and removes both files. One invocation pays the type-aware startup once rather than once per file. The rule and its self-test run in the existing lint and uncached test jobs.

Rule: no-hand-rolled-test-file-suffix.mjs. Fixture: no-hand-rolled-test-file-suffix.fixture.tsx. Test: no-hand-rolled-test-file-suffix.uncached.test.mjs.

no-fixed-palette-color

Theme discipline. Chrome colors come from the active theme, so a custom or bundled palette recolors the whole app rather than everything except the surfaces someone styled with a fixed Tailwind hue. The rule flags a color utility that names a chromatic Tailwind hue (red through rose, shades 50 to 950), with any variant prefix or opacity modifier, and asks for a theme token instead: success, warning, destructive or info for status, chart-1 to chart-5 for data categories, and identity-1 to identity-4 for telling items such as threads apart. The identity tokens come from the palette slots that carry no status, so an identity color never reads as a state; four of the five chart tokens share slots with the status tokens, and chart-4 shares identity-1's. A status tint carries only text in that same status color, which the theme derivation holds at 4.5:1 up to a 25% tint: chips, badges, pills and hover states. That holds wherever some shade of the slot color passes on both the page and its tint; on a mid-tone page where none does, the derivation falls back to checking the bare page and card only, and the tint is unchecked. A ghost Button adds its own hover:text-foreground and dark:hover:bg-muted/50, so a status-tinted ghost Button names its hover text and dark hover fill explicitly. A callout or row whose text is the body foreground marks its status with a border and an icon or title, not a fill, because no wash fits under body text in every theme (Solarized's own foreground is 4.86:1 on its popover). The rule matches hue names, so it cannot catch bg-warning/10 text-foreground; review has to.

It matches every string, not only class props. Status colors in this codebase mostly live in maps and helpers ({ ready: 'bg-emerald-500' }, a TONE_CLASS record, a ring palette array) rather than in a className attribute, so the rule reads every string literal and template-literal chunk. It knows the color utilities by prefix, hyphenated ones included (ring-offset, inset-ring, inset-shadow, drop-shadow, text-shadow), so a CSS custom property name (--color-red-500), a bare red-500 and prose never match. The utility must also stand alone as a token, so an identifier that merely contains one (legacy-text-red-500, text-red-500-legacy) stays silent.

Neutrals are out of scope. Grays (slate, gray, zinc, neutral, stone) and black/white are not palette hues; the rule does not flag them.

The rule does NOT catch hex, rgb() or oklch() literals, which canvas-drawn surfaces such as the graph view use, or colors in stylesheets.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, packages/desktop/src/**/*.ts, packages/desktop/src/**/*.tsx, packages/plugin/src/**/*.ts, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-fixed-palette-color.fixture.tsx. Excluded: **/*.test.ts, **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.ts, **/*.test-helper.tsx.

Rule: no-fixed-palette-color.mjs. Fixture: no-fixed-palette-color.fixture.tsx. Test: no-fixed-palette-color.uncached.test.mjs.

no-empty-jsx-expression

Flags JSX expression braces in a child position that hold no expression. It has two messages.

Empty braces. {}, or braces with only whitespace between them, compile to nothing, so they are dead code. They are the shape a comment strip leaves when it removes a JSX comment but not its braces. Delete the braces, and the line when nothing else is on it. Read the JSX text around them first: braces between two runs of text keep those runs apart as separate children, so deleting them can join the text. one, {} and two on three lines render onetwo; without the braces they render one two.

Comment braces. {/* ... */} exists only to carry a comment. Put the comment between the element's props, or after its tag name, and delete the braces:

<div
  // a comment between props
  className="row"
>
<div // oxlint-disable-line jsx-a11y/no-static-element-interactions -- reason
  onClick={select}
>

A comment between < and the tag name is not an option: TypeScript 7 rejects it (TS1003).

Two directives have no other place, so they keep their braces:

  • a single biome-ignore. Biome reports at the opening <, so a biome-ignore between props or after the tag name does not apply.
  • a single oxlint-disable-next-line directly before JSX text, or before an element whose first child is JSX text. A rule that reports on the text (ok/microcopy-ellipsis) can be suppressed only by a comment on the line above that text.

Any other comment, or a second comment next to a directive, is flagged. The no-comments rule still judges the text of every comment.

Biome and oxlint reject <div title={} /> as a parse error (TS17000), so no lint rule runs on it.

oxlint.config.ts ignores lint-plugins/no-comments/__fixtures__/, because the no-comments fixtures hold JSX comments and unused directives on purpose.

Unscoped, because any JSX file can carry one.

Rule: no-empty-jsx-expression.ts. Fixture: no-empty-jsx-expression.fixture.tsx. Test: no-empty-jsx-expression.uncached.test.ts.

no-redundant-jsx-element-braces

Pairs with the built-in react/jsx-curly-brace-presence rule, which oxlint.config.ts enables with children: "never" and props: "never". The built-in rule reports braces around a single child element, <p>{<b>x</b>}</p>, and string braces such as {'text'} and title={'x'}. It skips any braces that hold a comment, and this rule covers that case.

This rule flags braces in a child position that hold one element or fragment and at least one comment. The comment can sit before or after the element, between its props, or on a child inside it. A comment strip leaves this shape when the braces held a line comment before the element.

The fix is to delete the braces and write the element as a direct child. A comment that the braces carried goes between the element's props, or after its tag name (<div // ...). The compiled output does not change.

The rule does NOT catch:

  • braces whose only comment outside the element is a single biome-ignore directive. Biome reports at the opening <, so a biome-ignore between props or after the tag name does not apply.
  • braces with no comment. The built-in rule reports them.
  • an element as an attribute value (icon={<Icon />}), where the braces are needed.
  • an element inside a larger expression ({ok && <b>x</b>}, {ok ? <b>x</b> : null}).

Unscoped, because any JSX file can carry one.

Rule: no-redundant-jsx-element-braces.ts. Fixture: no-redundant-jsx-element-braces.fixture.tsx. Test: no-redundant-jsx-element-braces.uncached.test.ts.

no-native-renderer-dialog

Feedback-surface discipline, from the display guide at plugins/ok/skills/feedback-surfaces/SKILL.md. Renderer code never opens the browser's native confirm, alert or prompt dialog. The native dialog has no title, no destructive button, no app theme and no focus handling, and its button labels come from the browser, so Lingui cannot translate them. Confirmations use AlertDialog from @/components/ui/alert-dialog, or DeleteConfirmationDialog for a delete.

The rule fires on a call of window.confirm, window.alert or window.prompt (also through globalThis or self), and on a bare confirm(...), alert(...) or prompt(...) call whose name resolves to the global. Resolution walks the scope chain from the call: an import, a parameter, or a function or variable declared in any enclosing scope is a local binding, so consentStore.confirm(...), threadClient.prompt(...), an imported prompt and a local function confirm stay silent. A parameter named window is local too, so window.confirm on it is not flagged.

The scope is the renderer packages, packages/app/src and packages/plugin/src. packages/desktop/src is left out: it holds the Electron main process, the preload bridge, the utility process and shared modules, none of which renders UI, and the desktop renderer is packages/app itself (the desktop build sets root: ../app). Native Electron dialogs in the main process are a different surface that the guide limits separately and no-blocking-error-box partly gates.

The rule does NOT catch a dialog function taken by reference and called later (const ask = window.confirm; ask(...)), a computed member (window['confirm']), or a call through another alias of the global object.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, packages/plugin/src/**/*.ts, packages/plugin/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-native-renderer-dialog.fixture.tsx. Excluded: **/*.test.ts, **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.ts, **/*.test-helper.tsx.

Rule: no-native-renderer-dialog.mjs. Fixture: no-native-renderer-dialog.fixture.tsx. Test: no-native-renderer-dialog.uncached.test.mjs.

no-custom-toast

Toast discipline, from the display guide at plugins/ok/skills/feedback-surfaces/SKILL.md. App code calls the typed sonner functions (toast.success, toast.error, toast.warning, toast.info, toast.loading), never toast.custom. The app's <Toaster richColors closeButton /> styles the typed toasts with their color, icon, width and close button. Sonner leaves a custom toast unstyled: it sizes to its content, renders no close button, and in a collapsed stack the toast behind keeps its content visible, so a mixed stack overlaps.

The rule resolves toast from the file's own sonner imports: a named toast import under any local name (import { toast as sonnerToast } from 'sonner') and toast read off a namespace import (sonner.toast.custom). The name must resolve to that import: a toast imported from another module, or a local declaration that shadows the import, is not flagged. A custom method on any other object is not flagged, and neither is a toast.custom reference that is never called.

Pre-rule backlog. The three existing custom toasts, in packages/app/src/lib/install-bug-report-send-toasts.ts, install-server-drift-listener.ts and install-stale-tab-reload-prompt.ts, carry a file-level // oxlint-disable ok/no-custom-toast -- pre-rule backlog: ... header. Delete the header in the change that moves the file to a typed toast. A toast that truly needs custom content keeps an inline // oxlint-disable-next-line ok/no-custom-toast -- <reason> and follows the guide: width: var(--width), its own close button, and a check stacked behind and in front of a typed toast.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-custom-toast.fixture.tsx. Excluded: **/*.test.ts, **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.ts, **/*.test-helper.tsx.

Rule: no-custom-toast.mjs. Fixture: no-custom-toast.fixture.tsx. Test: no-custom-toast.uncached.test.mjs.

no-raw-error-toast

Error-copy discipline, from the display guide at plugins/ok/skills/feedback-surfaces/SKILL.md. A toast never shows raw error text. Raw text is untranslatable, often an internal message, and frequently wrong for the user; the guide asks for the failure to be mapped to a reason with copy written for it ("Couldn't {verb} {thing}."), and for raw detail to go behind a "Show details" disclosure or into Report a bug.

The rule checks the message argument and the options object's description of a sonner toast(...), toast.error, toast.warning, toast.info, toast.success, toast.loading or toast.message call, with toast resolved from the file's sonner imports as in no-custom-toast. It fires when that value is raw error text, which it recognizes syntactically:

  • <x>.message, String(<x>) and <x>.toString(), where <x> is an error value;
  • an error value used directly (toast.error(result.error), description: res.error);
  • any errorText(...) call, since that helper exists to stringify an unknown error;
  • a template literal, or a Lingui t template, that interpolates any of the above;
  • either branch of a conditional, either side of ||, ?? or +, and the right side of &&, holding any of the above, so the common err instanceof Error ? err.message : t`...` fires.

The error-value heuristic. The rule runs on the untyped AST, so it cannot ask whether a value is an Error. It decides by name instead: an identifier, or the last property of a member chain, named err, error, e, ex, cause or reason, or ending in Error or Err after a lowercase letter or digit (saveError, cloneError, result.error, lastErr). A predicate such as isError also matches, which is harmless because a condition is never the rendered value: only the right side of && and the branches of a conditional are read, not its test. A message field on anything else is not flagged, because a result or protocol object's message cannot be told apart from user-facing copy without types.

The rule does NOT catch:

  • message on a non-error name. toast.error(result.message) and t`Message not sent: ${frame.message}` are raw text from a result or a server frame, but the name says nothing about it. Five such toasts exist today (RestartServerButton, DocumentErrorBoundary, NetworkAccessSection, presence/use-sync-toasts.ts, lib/acp/thread-client.ts).
  • Raw text under another name. description: detail or description: result.detail where detail came from an error, and a variable assigned from err.message on an earlier line and then passed to the toast. The rule reads the call's own arguments only.
  • Formatting helpers other than errorText. humanFormat(result.error) is treated as mapped copy, not raw text.
  • toast.promise and its error callback, and toasts built from a JSX element.

Read the heuristic in both directions: an error-named variable that already holds written, translated copy is still flagged when it is passed straight through. Rename it (errorCopy does not end in Error), or suppress the line with a reason.

Pre-rule backlog. Forty-two files under packages/app/src that predate the rule carry a file-level // oxlint-disable ok/no-raw-error-toast -- pre-rule backlog: ... header over their 73 existing raw-error toasts. The headers are the visible backlog. Drain a file by mapping each failure to written copy, then deleting its header; the rule fires again at once, so a partial migration fails the gate.

Included: packages/app/src/**/*.ts, packages/app/src/**/*.tsx, lint-plugins/ok-rules/__fixtures__/no-raw-error-toast.fixture.tsx. Excluded: **/*.test.ts, **/*.test.tsx, **/*.dom.test.tsx, **/*.test-helper.ts, **/*.test-helper.tsx.

Rule: no-raw-error-toast.mjs. Fixture: no-raw-error-toast.fixture.tsx. Test: no-raw-error-toast.uncached.test.mjs.

Suppression

Inline // oxlint-disable-next-line comments silence individual diagnostics. The form names the plugin, the rule and the reason:

// oxlint-disable-next-line ok/<rule-name> -- <reason>
<span>…</span>

Two scopes, and the choice between them is meaningful:

  • // oxlint-disable-next-line ok/<rule-name> -- reason silences the next line. Use it for a genuine one-off exception.
  • // oxlint-disable ok/<rule-name> -- reason at the top of a file silences the whole file. Use it only as a pre-rule backlog marker (see the ratchet contract in the rule's section above), never to opt a new file out.

The -- separator is required; oxlint reads everything after it as the reason. These replaced biome's // biome-ignore lint/plugin/<rule>: <reason> and // biome-ignore-all pair, which oxlint does not honour.

Current production suppressions:

rule line-level file-level (backlog)
no-physical-direction-utility 4 66
no-loosely-typed-webcontents-ipc 32 0
no-raw-html-interactive-element 0 19
no-unportaled-editor-content 10 0
require-windowshide-on-spawn 6 0
microcopy-ellipsis 2 0
no-unwrapped-user-facing-string 1 0
no-hand-rolled-spinner 1 0
no-raw-error-toast 0 42
no-custom-toast 0 3

Every other rule has zero. The file-level counts above are the visible migration backlogs for the logical-property pass, the shadcn migration and the feedback-surfaces guide.

Where an inline suppression can and cannot sit. A suppression comment needs a line of its own directly above the reported span, which is a property of the formatting rather than of the rule. On a JSX attribute that means the attribute must already be on its own line. A {/* oxlint-disable-next-line */} child covers the element that follows it, not a text node that starts after that element.

Adding a new rule

1. Author the rule module

Drop <rule-name>.mjs in rules/. A rule is an ESLint-shaped visitor object; context.report({ node, message }) emits the diagnostic:

import { docsUrl } from '../docs.mjs';

const URL = docsUrl('<rule-name>');
const MESSAGE = `<problem>. <fix-noun>. See ${URL}`;

export const ruleName = {
  meta: {
    type: 'problem',
    docs: { description: '<one line>', url: URL },
  },
  create(context) {
    return {
      CallExpression(node) {
        if (!/* matches */ false) return;
        context.report({ node, message: MESSAGE });
      },
    };
  },
};

No prose comments. Rule modules are .mjs or .ts, and the no-comments policy applies to both. Rationale goes in this README, in the rule's own section.

Message shape (load-bearing). The diagnostic message has three parts in order: (1) the problem statement, (2) the fix-noun naming the action that resolves it, (3) See <docs-URL> built by docsUrl('<rule-name>') so no message hand-writes the base URL.

2. Register the rule

Import it in index.mjs, add it to the declared map, then switch it on in oxlint.config.ts as 'ok/<rule-name>': 'error', and add the same entry to __fixtures__/oxlint.fixtures.json, the config the fixture tests lint with.

A small number of rules are registered from a second plugin instead of this one. If the rule you are adding documents a calibrated measurement, an internal file list, or anything else that should not reach a public clone, do not follow this step as written. That path is documented in a maintainers-only checklist that is not part of this clone; if you cannot reach it, open an issue describing what the rule would enforce and leave the registration to a maintainer rather than guessing at the shape.

3. Scope it, if it is not workspace-wide

Add a RULE_SCOPES['<rule-name>'] entry in scope.mjs: an array of globs where a leading ! excludes. A file is in scope when it matches at least one positive glob and no negative one. Include the rule's own fixture path so the fixture test can fire.

Scope lives here rather than in oxlint.config.ts#overrides because oxlint's overrides[].files does not honour ! negation (measured on oxlint 1.66.0: with the rule off at root and an override of files: ['lint-plugins/ok-rules/__fixtures__/**', '!**/*.fixture.tsx'], the rule still fired on the excluded fixture — the negative glob did not subtract from the positive one. Re-check this on an oxlint upgrade; if negation lands, this whole scope table becomes revisitable) — a negative glob in that list does not subtract from a positive one, so an override-scoped rule silently fires on its exclusions. Biome's includes did honour it, which is why the rules this replaced could scope in config.

Workspace-wide is a claim about this table, not about oxlint. A rule with no RULE_SCOPES entry is one no entry here narrows; it is not a rule oxlint feeds every file in the repo. Selection happens first and is narrower: ignorePatterns in oxlint.config.ts drops /reports/**, /specs/**, .agents/skills/**, .codex/skills/**, lint-plugins/no-comments/__fixtures__/** and lint-plugins/ok-rules/__fixtures__/** before any rule sees them, and naming one of those files positionally on the command line does not override it (measured on oxlint 1.80.0: --debug=files prints nothing for such a file while a control under packages/ is listed, and --no-ignore does not rescue it — that flag governs .gitignore, not this list). The pre-push lane is narrower still, since lint-staged routes only packages/**, docs/**, {scripts,.github/scripts}/**/*.mjs and root *.ts through oxlint.

4. Author the fixture file

Drop <rule-name>.fixture.tsx in __fixtures__/, pairing positive cases (must fire) with negative cases (must NOT fire), each labelled. Include a boundary negative: the nearest shape the rule must NOT match. The directory is in oxlint.config.ts#ignorePatterns so the deliberately-bad content does not break the main lint; __fixtures__/oxlint.fixtures.json enables the rules the fixture tests lint with, one entry per rule, and ok-rules-scope-partition.uncached.test.mjs fails, naming that file, when a registered rule has no error entry there.

5. Author the fixture-file test

Put it at lint-plugins/ok-rules/tests/<rule-name>.uncached.test.mjs, not in a package. The .uncached.test suffix runs it in the uncached cross-package tier (vitest.uncached.config.ts): every agent round, CI's open-knowledge / tier-guards (uncached) cell, and every whole-suite turbo run, which names test:uncached beside test. A package's cached test tier would replay a stale pass when only the rule or oxlint.config.ts changed, unless that package's Turbo key hashed both. The tests in that directory check that every rule the ok plugin registers has one. Write it as plain JavaScript.

The tier's global setup, test-support/ok-rules-fixture-lint.ts, runs oxlint once over every fixture with the fixture config and hands the report to the tests; a watch-mode rerun lints again. Every rule test fails when that run could not start, exited other than 1, gave no JSON report, linted a different number of files than the directory's *.fixture.tsx files, or reported a diagnostic on no fixture. lintOkRulesFixture in test-support/read-ok-rules-config.test-helper.ts returns one fixture's diagnostics from the report, each with its rule code, line:column position and message, in a fixed order. A diagnostic that names no rule (a rule that threw while linting that fixture, or a fixture oxlint could not parse) fails that fixture's test with oxlint's message, as it does the scope meta-test, which reads every fixture. oxlint also drops every other JS-plugin diagnostic on a file where a rule threw, so a rule whose scope reaches other fixtures fails their tests too. Run outside the tier, it fails and prints the command that runs the test. Assert the exact list of your rule's fire positions, filtered by its own code:

import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
import {
  lintOkRulesFixture,
  readEnabledRuleIds,
  readRegisteredRuleNames,
} from '../../../test-support/read-ok-rules-config.test-helper.ts';

const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url));
const RULE = '<rule-name>';
const FIXTURE = `lint-plugins/ok-rules/__fixtures__/${RULE}.fixture.tsx`;

describe(`${RULE} oxlint rule`, () => {
  test('fires at exactly its positive cases, by its own code, and on no negative case', () => {
    const fires = lintOkRulesFixture(FIXTURE).filter((d) => d.code === `ok(${RULE})`);
    expect(fires.map((fire) => fire.position)).toEqual(['12:5', '18:5']);
    for (const fire of fires) {
      expect(fire.message).toContain('<fix-noun>');
      expect(fire.message).toMatch(/https?:\/\/[^\s]+/);
      expect(fire.message).toContain(`lint-plugins/ok-rules/README.md#${RULE}`);
    }
  });

  test('rule is registered and enabled', async () => {
    expect(await readRegisteredRuleNames(REPO_ROOT)).toContain(RULE);
    expect(await readEnabledRuleIds(REPO_ROOT)).toContain(`ok/${RULE}`);
  });
});

The positions list is the point. Its length is the exact count, so it catches a weakened rule (a positive stops firing) and a widened one (a negative starts firing). It also catches what a count cannot: a rule that stops firing on one positive and starts firing on a negative keeps the same total but changes the list. Filtering by the rule's own code catches a rule registered under the wrong name. A rule with more than one message asserts each fire's branch beside its position, as no-sentinel-signal-target.uncached.test.mjs does. After editing the fixture, take the new positions from the failure diff and check each lands on a positive case.

6. Verify

# 1. Rule loads and the main lint stays clean:
pnpm run lint:oxlint

# 2. Fixture test fires the diagnostic on positive cases (from the Open Knowledge root):
pnpm exec vitest run --config vitest.uncached.config.ts <rule-name>

# 3. Mutation check (manual, one-time during dev):
#    Temporarily break the rule's predicate; re-run the test; confirm it FAILS;
#    restore it; re-run; confirm it passes.

# 4. False-positive widening check (manual, one-time):
#    Add a positive case to the fixture WITHOUT adding its position to the test.
#    Re-run; confirm it FAILS. This verifies the positions list is load-bearing.

7. Document the rule in this README

Add a ### \`section: what it catches, what it deliberately does NOT catch, the**Scope**note if it is scoped, and the Rule / Fixture / Test links. The anchor must matchdocsUrl(''), i.e. #`, because the fixture test asserts the message links here.

Out of scope

  • Autofix. oxlint JS-plugin diagnostics are diagnostic-only here; these rules name the fix rather than applying it. If autofix is required, a different enforcement mechanism is needed.
  • Type-aware discrimination. These rules run on the untyped AST. Where the type system carries the discriminating signal, precedent #42's decision tree routes to a TypeScript Language Service plugin instead.
  • CLI string content. process.stderr.write('...') / console.log template-literal content is not reliably matchable and is left to review discipline.

References