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

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

@@ -0,0 +1,108 @@
+# `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
+// 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
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+it('expires the session', () => {
+  vi.advanceTimersByTime(60_000);
+  expect(session.isExpired()).toBe(true);
+});
+```
+
+```ts
+// Good
+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/no-conditional-expect.md

@@ -0,0 +1,82 @@
+# `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
+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
+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-real-network-in-unit-tests.md

@@ -0,0 +1,75 @@
+# `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: 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: 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 });
+});
+
+// Good: src/api/client.integration.test.ts runs against a real server.
+```
+
+## 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-vacuous-expect.md

@@ -0,0 +1,89 @@
+# `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
+it('should be defined', () => {
+  expect(service).toBeDefined();
+});
+
+it('returns a token', () => {
+  expect(typeof issueToken()).toBe('string');
+});
+
+it('works', () => {
+  expect(true).toBe(true);
+});
+```
+
+```ts
+// Good
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-code-quality",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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"
   }
 }