@noctcore/eslint-plugin-code-quality 0.1.0 → 0.2.1

package/docs/rules/fake-timers-must-be-restored.md

@@ -0,0 +1,106 @@
+# `noctcore-code-quality/fake-timers-must-be-restored`
+
+> A file that installs fake timers must restore real ones.
+
+Ported from [tsforge](https://github.com/boringstack-xyz/tsforge) (MIT). See
+[THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md).
+
+## Why
+
+`jest.useFakeTimers()` / `vi.useFakeTimers()` replace the global clock. Without a matching
+`useRealTimers()` the fake clock leaks into later tests in the same worker, and those tests fail or,
+worse, pass for the wrong reason, depending on file order.
+
+## What it flags
+
+Every call to a `fakeTimerMethods` method (`useFakeTimers` by default, as `name()` or `obj.name()`)
+in a file with no call to a `restoreTimerMethods` method, unless the restore lives in a shared suite
+the file runs.
+
+### Shared suites
+
+A contract suite often owns the restore: the spec installs fake timers inside a helper it hands to
+the suite, and the suite restores them in its own `afterEach`.
+
+```ts prose reason="two files: the rule reads the imported suite from disk"
+// provider.contract-suite.ts
+export function runProviderContract(subject: Subject): void {
+  describe('provider contract', () => {
+    afterEach(() => jest.useRealTimers());
+    // ...
+  });
+}
+
+// fake-provider.contract.spec.ts
+import { runProviderContract } from './provider.contract-suite';
+
+const advancePastDeadline = () => {
+  jest.useFakeTimers();
+  jest.setSystemTime(Date.now() + 86_400_000);
+};
+
+runProviderContract({ advancePastDeadline });
+```
+
+With `followImportedSuites` on (the default), the rule follows each relative import whose binding the
+file calls (`runProviderContract(...)` or `suite.run(...)`), resolves it on disk (`.ts`, `.tsx`,
+`.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`, or a directory `index`), and accepts a restore call
+in that module's source. The check is one level deep and text-based. An import that is only
+re-exported, never called, does not count.
+
+For a suite the rule cannot resolve (a path alias or a workspace package), name it in
+`sharedSuiteModules`.
+
+```ts bad filename=src/session.test.ts
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+it('expires the session', () => {
+  vi.advanceTimersByTime(60_000);
+  expect(session.isExpired()).toBe(true);
+});
+```
+
+```ts good filename=src/session.test.ts
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+it('expires the session', () => {
+  vi.advanceTimersByTime(60_000);
+  expect(session.isExpired()).toBe(true);
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `fakeTimerMethods` | `string[]` | `["useFakeTimers"]` | Methods that install fake timers. |
+| `restoreTimerMethods` | `string[]` | `["useRealTimers"]` | Methods that restore real timers. One call anywhere in the file satisfies the rule. |
+| `followImportedSuites` | `boolean` | `true` | Accept a restore found in a relative module this file imports and calls. |
+| `sharedSuiteModules` | `string[]` (globs) | `[]` | Import specifiers trusted to restore timers when the file imports and calls them. Supports `*`, `**`, `?` and `{a,b}`. |
+
+```js
+'noctcore-code-quality/fake-timers-must-be-restored': ['error', {
+  fakeTimerMethods: ['useFakeTimers', 'install'],
+  restoreTimerMethods: ['useRealTimers', 'uninstall'],
+  sharedSuiteModules: ['@acme/testing/*-suite'],
+}]
+```
+
+## Caveats
+
+Reading an imported suite from disk means an edit to the suite alone does not invalidate
+`eslint --cache` for the spec. The rule caches each suite's source by modification time within one
+process.
+
+## When not to use it
+
+If your runner restores timers globally (for example a setup file with a global `afterEach` that
+calls `useRealTimers()`).

package/docs/rules/interface-prefix-i.md

@@ -19,12 +19,14 @@ dictated by the module being augmented (`Register`, `Window`).
 
 Report-only: a rename touches every reference, which a single-file fixer cannot do safely.
 
-```ts
-// ✗ interface UserProfile { id: string; }
-// ✗ interface Input { value: string; }
+```ts bad reports=2
+interface UserProfile { id: string; }
+interface Input { value: string; }
+```
 
-// ✓ interface IUserProfile { id: string; }
-// ✓ declare global { interface Window { electron: unknown; } }  // augmentation
+```ts good
+interface IUserProfile { id: string; }
+declare global { interface Window { electron: unknown; } } // augmentation
 ```
 
 ## Options

package/docs/rules/no-bare-date-now.md

@@ -16,16 +16,20 @@ branch depends on the real clock. Routing wall-clock reads through a shared `clo
 `new Date(value)` with an argument is a **parse** of an explicit instant, not a bare clock read, and
 is never flagged. Files covered by `allowIn` are skipped entirely.
 
-```ts
-// ✗ bare clock reads in business logic
+```ts bad reports=2
+// bare clock reads in business logic
 const start = Date.now();
 const created = new Date();
+```
+
+```ts good
+import { now, nowMs } from './clock';
 
-// ✓ through the clock seam
+// through the clock seam
 const start = nowMs();
 const created = now();
 
-// ✓ parsing an explicit instant
+// parsing an explicit instant
 const at = new Date('2026-01-01T00:00:00Z');
 ```
 

package/docs/rules/no-conditional-expect.md

@@ -0,0 +1,80 @@
+# `noctcore-code-quality/no-conditional-expect`
+
+> An `expect()` that may not run lets a broken test pass.
+
+Ported from [tsforge](https://github.com/boringstack-xyz/tsforge) (MIT). See
+[THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md).
+
+## Why
+
+An assertion inside an `if`, a `switch` case, a ternary, a `&&` / `||` / `??` or a `catch` only runs
+when that branch is taken. When the code under test changes so the branch is skipped, the test
+passes with zero assertions. The classic case is `try { await f(); } catch (e) { expect(e)... }`:
+if `f` stops throwing, the test goes green.
+
+The rule matches on method names, so it covers Jest, Vitest and Bun alike.
+
+## What it flags
+
+`expect(...)`, or `obj.expect(...)` on an identifier (`t.expect`, `chai.expect`), whose path up to
+the enclosing test or suite callback crosses the conditional part of a branch. The test of an `if`
+and the left side of a logical expression run unconditionally and are not flagged.
+
+The search stops at the enclosing `it` / `test` / `describe` / `suite` callback, so a suite-level
+loop or `if` that generates tests does not flag the expects inside those tests.
+
+A test that calls `expect.assertions(n)` or `expect.hasAssertions()` is exempt: a skipped branch
+already fails it.
+
+```ts bad filename=src/parse.test.ts reports=2
+it('rejects bad input', async () => {
+  try {
+    await parse('');
+  } catch (error) {
+    expect(error).toBeInstanceOf(ParseError);
+  }
+});
+
+it('returns the value', () => {
+  const result = load();
+  if (result.ok) {
+    expect(result.value).toBe(1);
+  }
+});
+```
+
+```ts good filename=src/parse.test.ts
+it('rejects bad input', async () => {
+  await expect(parse('')).rejects.toBeInstanceOf(ParseError);
+});
+
+it('returns the value', () => {
+  expect(load()).toEqual({ ok: true, value: 1 });
+});
+
+describe('parse', () => {
+  for (const c of cases) {
+    it(c.name, () => {
+      expect(parse(c.input)).toEqual(c.output);
+    });
+  }
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `checkLoops` | `boolean` | `false` | Also treat a `for` / `for...in` / `for...of` / `while` / `do...while` body as conditional, since a loop over an empty collection asserts nothing. |
+
+`checkLoops` is off by default, unlike the tsforge original. On a real 650-file suite, loops made up
+164 of 173 reports, almost all table-driven loops over literal arrays and constant maps.
+
+```js
+'noctcore-code-quality/no-conditional-expect': ['error', { checkLoops: true }]
+```
+
+## When not to use it
+
+If your suites rely on type-narrowing guards such as `if (result.success) expect(result.data)...`
+after an unconditional `expect(result.success).toBe(true)`, and you do not want to rewrite them.

package/docs/rules/no-focused-tests.md

@@ -15,13 +15,15 @@ focused test a lint error so it can't merge.
 - The Jest/Jasmine focused-call forms `fdescribe(...)`, `fit(...)`, `ddescribe(...)` — but only as a
   bare-identifier callee, so an unrelated `obj.fit(...)` method is not flagged.
 
-```ts
-// ✗ it.only('runs', () => {});
-// ✗ test.concurrent.only('case', () => {});
-// ✗ fdescribe('suite', () => {});
+```ts bad filename=src/example.test.ts reports=3
+it.only('runs', () => {});
+test.concurrent.only('case', () => {});
+fdescribe('suite', () => {});
+```
 
-// ✓ it('runs', () => {});
-// ✓ layout.fit('contain');   // not a test runner
+```ts good filename=src/example.test.ts
+it('runs', () => {});
+layout.fit('contain'); // not a test runner
 ```
 
 ## Options

package/docs/rules/no-historical-comments.md

@@ -15,11 +15,13 @@ Line and block comments (JSDoc `/** … */` blocks are exempt) matching narrow p
 `before/after the fix`, `before/after the refactor`, `we/this used to`, `used to be`, `no longer`,
 `kept for backwards/legacy/compat`, `was/were a bug/footgun`, and `historical(ly)`.
 
-```ts
-// ✗ We used to read process.env directly here.
-// ✗ Before the fix this collapsed to {}.
+```ts bad reports=2
+// We used to read process.env directly here.
+// Before the fix this collapsed to {}.
+```
 
-// ✓ Caps concurrent connections to avoid pool exhaustion.
+```ts good
+// Caps concurrent connections to avoid pool exhaustion.
 ```
 
 ## Options

package/docs/rules/no-narration-comments.md

@@ -17,12 +17,14 @@ construction: `here we`, `now we`, `first[,] we`, `then[,] we`, `next[,] we`, `f
 
 A bare leading word ("Next attempt…", "First run…") is fine — only the "we"/"let's" narration form matches.
 
-```ts
-// ✗ Now we attach the user to the socket.
-// ✗ Let's validate the session token.
+```ts bad reports=2
+// Now we attach the user to the socket.
+// Let's validate the session token.
+```
 
-// ✓ WHY: Prisma reuses the pooled connection across requests.
-// ✓ call next() to continue the middleware chain
+```ts good
+// WHY: Prisma reuses the pooled connection across requests.
+// call next() to continue the middleware chain
 ```
 
 ## Options

package/docs/rules/no-pr-reference-comments.md

@@ -18,13 +18,15 @@ Comments containing:
 - a `PR #123` / `PR 123` reference;
 - a bare `#123` at a word boundary.
 
-```ts
-// ✗ fixes #123
-// ✗ See https://github.com/noctcore/eslint-plugins/pull/42 for context.
-// ✗ workaround (#88)
+```ts bad reports=3
+// fixes #123
+// See https://github.com/noctcore/eslint-plugins/pull/42 for context.
+// workaround (#88)
+```
 
-// ✓ Trust-proxy depth for single-host Traefik.
-const channel = "#general"; // ✓ not a comment
+```ts good
+// Trust-proxy depth for single-host Traefik.
+const channel = "#general"; // the string is not a comment
 ```
 
 ## Options

package/docs/rules/no-process-exit.md

@@ -16,6 +16,24 @@ Any `process.exit(...)` call in a file **not** covered by `allowIn`. Both the do
 (`process.exit()`) and the computed form (`process['exit']()`) are caught so a computed callee
 cannot bypass the rule.
 
+```ts bad filename=src/orders/orders.service.ts
+if (!order) {
+  process.exit(1);
+}
+```
+
+```ts good filename=src/orders/orders.service.ts
+if (!order) {
+  throw new Error('order not found');
+}
+```
+
+Moving the exit to a CLI entrypoint is the other fix:
+
+```ts good filename=scripts/migrate.ts relocation
+main().catch(() => process.exit(1));
+```
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/docs/rules/no-real-network-in-unit-tests.md

@@ -0,0 +1,80 @@
+# `noctcore-code-quality/no-real-network-in-unit-tests`
+
+> Unit tests must not perform real network I/O.
+
+Ported from [tsforge](https://github.com/boringstack-xyz/tsforge) (MIT). See
+[THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md).
+
+## Why
+
+A unit test that calls `fetch` or `axios` for real depends on a server, a port, DNS and the network
+being up. It is slow, flaky and order-dependent, and it hides the fact that the code under test has
+no seam for a test double. Mock the client, or move the test to an integration suite where real I/O
+is the point.
+
+## What it flags
+
+In a unit test file (a path ending in one of `testFileSuffixes`, and not containing any
+`integrationMarkers`):
+
+- a call to a `networkCallees` global: `fetch(...)`, `globalThis.fetch(...)`, `window.fetch(...)`;
+- a call to an `httpClients` client or its request methods: `axios(...)`, `axios.get(...)`,
+  `axios.post(...)`, and `put` / `patch` / `delete` / `head` / `options` / `request`.
+
+It does not flag:
+
+- a locally declared double (`const fetch = vi.fn()`); an imported `fetch` is still reported;
+- a global the file stubs (`vi.stubGlobal('fetch', ...)`, `jest.spyOn(globalThis, 'fetch')`,
+  `globalThis.fetch = vi.fn()`);
+- a client whose module the file mocks (`vi.mock('axios')`, `jest.mock('node-fetch')`);
+- a method that only shares a name (`repository.fetch(1)`, `store.get('k')`).
+
+```ts bad filename=src/api/client.test.ts
+it('loads the profile', async () => {
+  const res = await fetch('https://api.example.com/me');
+  expect(res.status).toBe(200);
+});
+```
+
+```ts good filename=src/api/client.test.ts
+it('loads the profile', async () => {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('{"id":1}')));
+  expect(await loadProfile()).toEqual({ id: 1 });
+});
+```
+
+A test that needs the real server moves to an integration suite:
+
+```ts good filename=src/api/client.integration.test.ts relocation
+it('loads the profile', async () => {
+  const res = await fetch('https://api.example.com/me');
+  expect(res.status).toBe(200);
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `testFileSuffixes` | `string[]` | `.test` / `.spec` with `.ts`, `.tsx`, `.js`, `.jsx` | A file is a unit test when its path ends with one of these. |
+| `integrationMarkers` | `string[]` | `.integration.test.`, `.integration.spec.`, `.e2e.test.`, `.e2e.spec.`, `.e2e-spec.`, `/integration/`, `/e2e/` | A test file whose path, relative to the ESLint working directory, contains one of these is skipped. |
+| `networkCallees` | `string[]` | `["fetch"]` | Global functions that perform network I/O. |
+| `httpClients` | `string[]` | `["axios"]` | HTTP clients whose direct call or request methods perform network I/O. |
+
+```js
+'noctcore-code-quality/no-real-network-in-unit-tests': ['error', {
+  integrationMarkers: ['.integration.', '/e2e/', '.live.'],
+  httpClients: ['axios', 'ky'],
+}]
+```
+
+## Limitations
+
+The rule sees calls in the test file only, not network calls made by the code under test. A request
+intercepted by a setup-file mock server (for example MSW) is still reported when the test file itself
+calls `fetch`; add that file's suffix to `integrationMarkers` or disable the rule for it.
+
+## When not to use it
+
+If your unit tests deliberately run against a local server started in-process, name those files with
+an integration marker instead of turning the rule off.

package/docs/rules/no-template-trim-empty-ternary.md

@@ -17,12 +17,12 @@ explicitly if the shape recurs in your codebase.
 A `ConditionalExpression` whose test is a `===` / `!==` comparison between an **empty-string literal**
 and a **`.trim()` call on a template literal**, in either order.
 
-```ts
-// ✗
+```ts bad reports=2
 const name = `${first} ${last}`.trim() === '' ? email : `${first} ${last}`.trim();
-const name = '' !== `${a}`.trim() ? `${a}`.trim() : fallback;
+const label = '' !== `${a}`.trim() ? `${a}`.trim() : fallback;
+```
 
-// ✓
+```ts good
 const name = buildDisplayName({ first, last, fallback: email });
 const trimmed = value.trim() === '' ? fallback : value; // not a template literal
 ```

package/docs/rules/no-vacuous-expect.md

@@ -0,0 +1,87 @@
+# `noctcore-code-quality/no-vacuous-expect`
+
+> A test must assert behaviour that a real regression would break.
+
+Ported from [tsforge](https://github.com/boringstack-xyz/tsforge) (MIT). See
+[THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md).
+
+## Why
+
+Some assertions pass for almost any implementation. `expect(typeof handler).toBe('function')` proves
+a binding exists. `expect(true).toBe(true)` cannot fail. A test whose only assertion is
+`toBeDefined()` or `toBeTruthy()` stays green when the function returns the wrong object, the wrong
+string or the wrong number. These tests add to the count and protect nothing.
+
+The rule matches on method names, not on a runner import, so it covers Jest, Vitest and Bun alike.
+
+## What it flags
+
+- `typeofExpect`: `expect(typeof x).toBe('<typeof result>')`, also with `toEqual`, `toStrictEqual`
+  and `.not`.
+- `tautologyExpect`: `expect(<literal>).toBe(<same literal>)`, also with `toEqual` / `toStrictEqual`.
+- `soleWeakExpect`: a test (`it` / `test`, including `.concurrent`, `.each` and other modifiers)
+  whose only assertion is a weak matcher.
+
+A test counts every `expect(...)` matcher plus any call matching `assertionCallees`, so a weak
+`expect` next to `assert.equal(...)`, `expectValidUser(...)` or supertest's `.expect(200)` is fine.
+
+```ts bad filename=src/token.test.ts reports=3
+it('should be defined', () => {
+  expect(service).toBeDefined();
+});
+
+it('returns a token', () => {
+  expect(typeof issueToken()).toBe('string');
+});
+
+it('works', () => {
+  expect(true).toBe(true);
+});
+```
+
+```ts good filename=src/token.test.ts
+it('issues a signed token for the user', () => {
+  const token = issueToken({ userId: 'u-1' });
+  expect(verify(token)).toEqual({ userId: 'u-1' });
+});
+
+it('creates the user', () => {
+  const user = create({ name: 'ada' });
+  expect(user).toBeDefined();
+  expect(user.name).toBe('ada');
+});
+
+it('clears the key', () => {
+  cache.delete('k');
+  expect(cache.get('k')).toBeUndefined(); // a specific absence, not a weak check
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `weakMatchers` | `string[]` | `["toBeDefined", "toBeTruthy", "toBeFalsy", "not.toBeUndefined"]` | Matchers that cannot carry a test alone. Prefix `not.` for the negated form. |
+| `assertionCallees` | `string[]` (regex sources) | `["^assert", "^expect\\w", "\\.expect$"]` | Calls that also count as an assertion. Matched against `name`, `obj.name` (member on an identifier) or `.name` (any other member). |
+
+`toBeUndefined`, `toBeNull` and `not.toBeNull` are not weak by default: each pins one specific
+value, and `expect(container.querySelector('nav')).not.toBeNull()` is a real presence check.
+
+```js
+// Treat toBeUndefined as weak too, and count a project helper as an assertion.
+'noctcore-code-quality/no-vacuous-expect': ['error', {
+  weakMatchers: ['toBeDefined', 'toBeTruthy', 'toBeFalsy', 'toBeUndefined'],
+  assertionCallees: ['^assert', '^expect\\w', '\\.expect$', '^verifySnapshot$'],
+}]
+```
+
+## Limitations
+
+Assertions are counted syntactically inside the test callback. An assertion hidden in a helper whose
+name does not match `assertionCallees` is not seen. A sole `toBeTruthy()` on a Testing Library
+`getBy*` query is reported even though the query itself throws when the element is missing; assert
+with a matcher that states the intent instead.
+
+## When not to use it
+
+In a smoke suite whose only purpose is to prove modules load.

package/docs/rules/prefer-early-return.md

@@ -18,16 +18,18 @@ The **last** statement of a function block that is an `if` with:
 A single-statement `if`, an `if/else`, or an `if` that is not the final statement is left alone —
 those are not body-wraps.
 
-```ts
-// ✗ the whole body is wrapped
+```ts bad
+// the whole body is wrapped
 function handle(x) {
   if (x) {
     doA();
     doB();
   }
 }
+```
 
-// ✓ guard clause
+```ts good
+// guard clause
 function handle(x) {
   if (!x) {
     return;

package/docs/rules/skipped-tests-need-tracking.md

@@ -21,16 +21,18 @@ window above it.
 Faithful to the original text-scanning implementation, the source is scanned line by line, so a marker
 in a trailing comment, a preceding comment, or anywhere in the lookback window is honoured.
 
-```ts
-// ✓ tracked
+```ts bad filename=src/example.test.ts reports=2
+// untracked
+it.skip('later', () => {});
+xdescribe('later', () => {});
+```
+
+```ts good filename=src/example.test.ts
+// tracked
 // TODO(@alice): flaky under CI
 it.skip('later', () => {});
 
 it.skip('later', () => {}); // https://github.com/org/repo/issues/1
-
-// ✗ untracked
-it.skip('later', () => {});
-xdescribe('later', () => {});
 ```
 
 ## Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-code-quality",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Portable code-quality, comment-hygiene, and test-discipline ESLint rules.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "sideEffects": false,
   "keywords": [
@@ -59,6 +60,6 @@
     "@typescript-eslint/rule-tester": "^8.61.1",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^3"
+    "vitest": "^4"
   }
 }