Skip to content
Esc

@noctcore/eslint-plugin-code-quality

v1.0.021 rules12 recommended2 strict only7 opt-innamespace noctcore-code-quality

A bad fit if your team writes explanatory step-by-step comments on purpose.

Guard clauses, comment hygiene, test discipline and deterministic time.

A grab bag with one theme: code and tests that stay honest over time. Focused and silently skipped tests, assertions that can never fail, fake timers that leak into the next test, unit tests that hit the real network, comments that narrate or reference a PR number that means nothing in a year, Date.now() scattered through business logic.

It will yell at you about tests and comments more than about runtime code. The comment rules (no-narration-comments, no-historical-comments, no-pr-reference-comments) are opinionated and will fire on a lot of existing code; that is the point, but expect a cleanup pass. no-bare-date-now assumes you read time through a shared clock. The test rules match on method names, so they cover Jest, Vitest and Bun alike. It is a bad fit if your team writes explanatory step-by-step comments on purpose. interface-prefix-i and no-template-trim-empty-ternary are exported but left out of the preset: they are house style, not correctness.

Install
npm install --save-dev @noctcore/eslint-plugin-code-quality @typescript-eslint/parser
# or: bun add -D / pnpm add -D @noctcore/eslint-plugin-code-quality @typescript-eslint/parser

The recommended preset enables 12 of 21 rules. The strict preset adds 2 house rules (naming, folder shape, size caps) on top. The rules board below builds the flat config: start from a preset, switch single rules between error and off, and copy the result.

Each rule links to its page, with the options it takes and Incorrect and Correct examples. A good first read is no-conditional-expect.

12 of 21 at error

--fixsuggestionsneeds optionstype infoEach switch sets a rule to error or off.

fake-timers-must-be-restored
A test file that calls useFakeTimers() must also call useRealTimers(), so fake timers do not leak into later tests.
recommended
interface-prefix-i
Interface names must be prefixed with I followed by an uppercase letter. Module/global augmentations are exempt.
opt-in
no-bare-date-now
Disallow bare Date.now() / new Date() in business logic. Read wall-clock time through a shared clock util (nowMs() / now()) so time is mockable.
strict only
no-conditional-expect
Disallow expect() inside a branch, catch or loop that may not run: a skipped assertion lets a broken test pass.
recommended
no-elided-code-comments
Disallow comments that stand in for elided code ('// ... existing code ...', '// rest of the function unchanged', '// your code here'). They are what an agent leaves when it rewrites a file from an abbreviated draft, and the code they replaced has usually been deleted.
recommended
no-focused-tests
Ban focused tests (it.only / describe.only / test.only, fdescribe / fit / ddescribe) so a focused test never silently lands in CI.
Editor suggestions
recommended
no-historical-comments
Disallow comments that frame code relative to what it used to do or to a past incident ('before the fix', 'after the refactor', 'we used to', 'no longer'). Source comments describe the current invariant; history belongs in the commit message or PR description, where it does not rot when the code changes again.
recommended
no-message-only-throw-assertion
Disallow toThrow() with no argument or with only a message: any error passes, including a TypeError from a broken mock. Pin the error class.
opt-in
no-narration-comments
Disallow narrative comments like 'Here we...', 'Now we...', 'First, we...'. These read as step-by-step prose and add no information a future reader cannot get from the code itself. Often a tell that the comment was generated by an agent describing its own changes.
recommended
no-pr-reference-comments
Disallow PR/issue references in comments. They belong in commit messages and PR descriptions, where they do not rot when the repo moves, the issue tracker migrates, or the numbering changes.
recommended
no-process-exit
Disallow process.exit() outside bootstrap/shutdown paths and standalone CLIs. Application and service code must throw or reject so the lifecycle can shut down gracefully.
recommended
no-real-clock-in-unit-tests
Unit tests must not read the real clock (Date.now(), new Date()) unless the file fakes it; an offset from now (Date.now() + 60_000) is allowed.
opt-in
no-real-network-in-unit-tests
Unit tests must not perform real network I/O: mock the HTTP client, or move the test to an integration suite.
recommended
no-sleep-in-unit-tests
Unit tests must not sleep on the real clock (new Promise((r) => setTimeout(r, n)), timers/promises): fake the timers or wait for the condition.
opt-in
no-swallowed-assertion
Disallow assertions inside a try whose catch neither rethrows nor asserts, and .catch() handlers that swallow an expect(...).rejects/.resolves failure: the assertion fails, the error is dropped, and the test passes.
recommended
no-template-trim-empty-ternary
Disallow inline <template>.trim() === '' ? fallback : <template>.trim() patterns. Extract to a named utility so the expression is built once and is unit-testable in one place.
opt-in
no-vacuous-expect
Disallow vacuous expects (typeof checks, literal tautologies, a sole toBeDefined/toBeTruthy, a sole presence check on the render root): a test must assert behaviour that a real regression would break.
recommended
prefer-early-return
Prefer guard clauses (early return) over wrapping the whole function body in a multi-statement if without an else.
strict only
prefer-web-first-page-assertions
Disallow asserting on a one-shot Playwright page read (expect(page.url()), expect(await page.title())): the check runs once, possibly before the navigation lands. Use the retrying toHaveURL / toHaveTitle.
Editor suggestions
opt-in
skipped-tests-need-tracking
Skipped tests (.skip / .fixme / xit / xdescribe, and unconditional node:test { skip } / { todo } / t.skip()) must carry a tracking marker (an issue URL or TODO(@owner)) on or above the line, so the debt has an owner instead of rotting silently.
Editor suggestions
recommended
typed-mock-over-double-cast
Disallow an object literal of jest.fn() / vi.fn() mocks cast as unknown as T: the double cast switches type checking off, so a mock of a renamed or removed method keeps passing.
opt-in