@noctcore/eslint-plugin-code-quality 0.1.0

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

@@ -0,0 +1,44 @@
+# `noctcore-code-quality/interface-prefix-i`
+
+> Interface names must be `I` + an uppercase letter (`IUserProfile`). **Opinionated — not in `recommended`.**
+
+## Why
+
+An `I`-prefixed interface reads as an interface at a glance and never collides with a value of the same
+name. This is a house-style naming convention, not a correctness rule — some teams find the prefix
+noisy. It is therefore **excluded from the `recommended` preset**; enable it explicitly if your team
+wants it.
+
+## What it flags
+
+A `TSInterfaceDeclaration` whose name is **not** `I` followed by an uppercase letter
+(`/^I[A-Z]/`). `Input` fails (the letter after `I` is lowercase); `IUserProfile` passes.
+
+Interfaces inside an ambient `declare module` / `declare global` block are **exempt** — their names are
+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; }
+
+// ✓ interface IUserProfile { id: string; }
+// ✓ declare global { interface Window { electron: unknown; } }  // augmentation
+```
+
+## Options
+
+None.
+
+## Enabling it
+
+Not part of `recommended`. Turn it on directly:
+
+```js
+'noctcore-code-quality/interface-prefix-i': 'error'
+```
+
+## When not to use it
+
+If your codebase does not use the `I` interface-prefix convention (most don't) — leave it off.

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

@@ -0,0 +1,44 @@
+# `noctcore-code-quality/no-bare-date-now`
+
+> Read wall-clock time through a mockable `clock` util, not bare `Date.now()` / `new Date()`.
+
+## Why
+
+Business logic that reads `Date.now()` or `new Date()` directly is hard to test: every time-dependent
+branch depends on the real clock. Routing wall-clock reads through a shared `clock` util
+(`nowMs()` / `now()`) gives time-dependent code one seam you can freeze or advance in tests.
+
+## What it flags
+
+- `Date.now()` → suggests `nowMs()`.
+- Zero-argument `new Date()` → suggests `now()`.
+
+`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
+const start = Date.now();
+const created = new Date();
+
+// ✓ through the clock seam
+const start = nowMs();
+const created = now();
+
+// ✓ parsing an explicit instant
+const at = new Date('2026-01-01T00:00:00Z');
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `allowIn` | `string[]` (globs) | `["**/clock.ts", "**/clock/**"]` | File-path globs (infra / the clock util itself) where bare `Date` is allowed. |
+
+```js
+'noctcore-code-quality/no-bare-date-now': ['error', { allowIn: ['**/clock.ts', '**/*.timing.ts'] }]
+```
+
+## When not to use it
+
+If your project has no clock abstraction and does not intend to add one.

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

@@ -0,0 +1,33 @@
+# `noctcore-code-quality/no-focused-tests`
+
+> Ban `.only` / `fdescribe` / `fit` so a focused test never silently lands in CI.
+
+## Why
+
+A focused test (`it.only`, `fdescribe`, …) silences the rest of the suite. Committed by accident it
+turns a green CI run into a lie — the suite "passes" because almost none of it ran. This rule makes a
+focused test a lint error so it can't merge.
+
+## What it flags
+
+- `.only` resolved back to a `it` / `describe` / `test` runner, including chained modifiers
+  (`test.concurrent.only`, `describe.concurrent.only`).
+- 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', () => {});
+
+// ✓ it('runs', () => {});
+// ✓ layout.fit('contain');   // not a test runner
+```
+
+## Options
+
+None.
+
+## When not to use it
+
+You almost always want this on. Disable only in throwaway scratch suites.

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

@@ -0,0 +1,31 @@
+# `noctcore-code-quality/no-historical-comments`
+
+> Comments describe the current invariant, not what the code used to do.
+
+## Why
+
+A comment that frames code against its past — "before the fix", "we used to", "no longer" — rots the
+moment the code changes again, and it forces the reader to reconstruct a history they don't need. The
+history belongs in the commit message or PR description, where it is durable and out of the way.
+This is also a common tell that a comment was generated to narrate a change rather than to explain the code.
+
+## What it flags
+
+Line and block comments (JSDoc `/** … */` blocks are exempt) matching narrow past-framing phrases:
+`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 {}.
+
+// ✓ Caps concurrent connections to avoid pool exhaustion.
+```
+
+## Options
+
+None.
+
+## When not to use it
+
+If you deliberately keep inline change-history in comments.

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

@@ -0,0 +1,34 @@
+# `noctcore-code-quality/no-narration-comments`
+
+> Ban step-by-step "Now we… / First we…" narration comments.
+
+## Why
+
+Comments like "Here we attach the user" or "First, we parse the cookies" restate what the next line
+of code already says. They add no information a reader can't get from the code and are a frequent tell
+of a comment generated to narrate a change. Describe the **why** when a comment is warranted, or
+delete it.
+
+## What it flags
+
+Line and block comments (JSDoc `/** … */` blocks are exempt) that **begin** with a narration
+construction: `here we`, `now we`, `first[,] we`, `then[,] we`, `next[,] we`, `finally[,] we`,
+`let's`, `let me`.
+
+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.
+
+// ✓ WHY: Prisma reuses the pooled connection across requests.
+// ✓ call next() to continue the middleware chain
+```
+
+## Options
+
+None.
+
+## When not to use it
+
+If your team writes tutorial-style narrated code on purpose.

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

@@ -0,0 +1,36 @@
+# `noctcore-code-quality/no-pr-reference-comments`
+
+> PR/issue references belong in commit messages, not in source comments.
+
+## Why
+
+`// fixes #123` or a link to a pull request rots the moment the repo moves, the issue tracker
+migrates, or the numbering changes — and it drags the reader out of the code to chase context that a
+`git blame` already carries. The git log and PR description are the canonical, durable home for
+repo-history references.
+
+## What it flags
+
+Comments containing:
+
+- a GitHub PR/issue URL (`https://github.com/owner/repo/pull/42`, `.../issues/42`);
+- an action reference (`see`/`closes`/`fixes`/`resolves`/`refs` `#123`);
+- 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)
+
+// ✓ Trust-proxy depth for single-host Traefik.
+const channel = "#general"; // ✓ not a comment
+```
+
+## Options
+
+None.
+
+## When not to use it
+
+If your workflow relies on inline issue links in code.

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

@@ -0,0 +1,38 @@
+# `noctcore-code-quality/no-process-exit`
+
+> `process.exit()` belongs to bootstrap/shutdown and CLIs — not application code.
+
+## Why
+
+`process.exit()` kills the whole process immediately, skipping pending I/O, `finally` blocks, and
+graceful-shutdown handlers. In request-scoped, service, or renderer code that is a footgun: a single
+call can take the entire process down mid-flight. Those layers should `throw` or reject and let the
+lifecycle decide how to tear down. The legitimate exit sites are standalone scripts, CLI entrypoints,
+and config files.
+
+## What it flags
+
+Any `process.exit(...)` call in a file **not** covered by `allowIn`. Both the dot form
+(`process.exit()`) and the computed form (`process['exit']()`) are caught so a computed callee
+cannot bypass the rule.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `allowIn` | `string[]` (globs) | see below | File-path globs where `process.exit()` is allowed. |
+
+The globs are matched against the file path (a leading `**/` may match zero leading directories, so
+the same pattern works for absolute and project-relative paths). Default:
+
+```jsonc
+["**/scripts/**", "**/bin/**", "**/cli/**", "**/*.config.{ts,js,mjs,cjs,cts,mts}"]
+```
+
+```js
+'noctcore-code-quality/no-process-exit': ['error', { allowIn: ['**/scripts/**', '**/*.cli.ts'] }]
+```
+
+## When not to use it
+
+Standalone CLI projects where every file is legitimately an entrypoint.

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

@@ -0,0 +1,44 @@
+# `noctcore-code-quality/no-template-trim-empty-ternary`
+
+> Extract the inline `` `…`.trim() === '' ? fallback : `…`.trim() `` pattern to a named util. **Niche — not in `recommended`.**
+
+## Why
+
+The inline shape `` `${a} ${b}`.trim() === '' ? fallback : `${a} ${b}`.trim() `` builds the same
+template-plus-`trim()` expression **twice** and buries a small piece of display logic where it can't be
+unit-tested on its own. Extracting it to a named helper (e.g. `buildDisplayName(...)`) builds the
+expression once and gives it one testable home.
+
+This is a very specific pattern, so the rule is **excluded from the `recommended` preset**. Enable it
+explicitly if the shape recurs in your codebase.
+
+## What it flags
+
+A `ConditionalExpression` whose test is a `===` / `!==` comparison between an **empty-string literal**
+and a **`.trim()` call on a template literal**, in either order.
+
+```ts
+// ✗
+const name = `${first} ${last}`.trim() === '' ? email : `${first} ${last}`.trim();
+const name = '' !== `${a}`.trim() ? `${a}`.trim() : fallback;
+
+// ✓
+const name = buildDisplayName({ first, last, fallback: email });
+const trimmed = value.trim() === '' ? fallback : value; // not a template literal
+```
+
+## Options
+
+None.
+
+## Enabling it
+
+Not part of `recommended`. Turn it on directly:
+
+```js
+'noctcore-code-quality/no-template-trim-empty-ternary': 'error'
+```
+
+## When not to use it
+
+If this pattern doesn't appear in your codebase, there's nothing to gain from enabling it.

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

@@ -0,0 +1,47 @@
+# `noctcore-code-quality/prefer-early-return`
+
+> Prefer a guard clause over wrapping the whole function body in an `if`.
+
+## Why
+
+When a function's entire body is wrapped in a single `if` with no `else`, the happy path is
+needlessly indented and the reader has to hold the condition in their head to the end. Inverting
+the condition into an early return keeps the meaningful work at the top level and reads top-to-bottom.
+
+## What it flags
+
+The **last** statement of a function block that is an `if` with:
+
+- no `else` branch, and
+- a block consequent holding **two or more** statements.
+
+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
+function handle(x) {
+  if (x) {
+    doA();
+    doB();
+  }
+}
+
+// ✓ guard clause
+function handle(x) {
+  if (!x) {
+    return;
+  }
+  doA();
+  doB();
+}
+```
+
+## Options
+
+None.
+
+## When not to use it
+
+If you prefer the wrapped style, or lint a codebase where trailing single-`if` bodies are idiomatic,
+disable it.

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

@@ -0,0 +1,50 @@
+# `noctcore-code-quality/skipped-tests-need-tracking`
+
+> A skipped test must carry a tracking marker (issue URL or `TODO(@owner)`) so the debt has an owner.
+
+## Why
+
+`.skip` / `.fixme` / `xit` / `xdescribe` are escape hatches. Left unowned they rot into permanent dark
+zones — nobody remembers why the test is off or who is meant to turn it back on. Requiring a tracking
+marker (an issue URL or a `TODO(@owner)`) within a few lines of the skip keeps a human attached to the
+debt.
+
+`.only` is deliberately **not** covered here — [`no-focused-tests`](./no-focused-tests.md) bans it
+outright, so it can never legitimately appear with or without tracking.
+
+## What it flags
+
+Any line matching a skip form — `it.skip(` / `test.skip(` / `describe.skip(`, the `.fixme(` variants,
+`xit(`, `xdescribe(`, `xtest(` — with **no** tracking marker on that line or within the `lookback`
+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
+// 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
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `markers` | `string[]` (regex sources) | `["https?://\\S+", "TODO\\(@?\\S+\\)"]` | Any pattern that, if found in the lookback window, satisfies the tracking requirement. Compiled with the `u` flag. |
+| `lookback` | `integer` (≥0) | `30` | How many lines above the skip a marker may live and still count. |
+
+```js
+// Require a Jira-style key instead of a URL / TODO.
+'noctcore-code-quality/skipped-tests-need-tracking': ['error', { markers: ['[A-Z]+-\\d+'] }]
+```
+
+## When not to use it
+
+If your project already enforces skip-tracking another way, or never skips tests.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@noctcore/eslint-plugin-code-quality",
+  "version": "0.1.0",
+  "description": "Portable code-quality, comment-hygiene, and test-discipline ESLint rules.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "code-quality",
+    "noctcore"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noctcore/eslint-plugins.git",
+    "directory": "packages/eslint-plugin-code-quality"
+  },
+  "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/eslint-plugin-code-quality",
+  "bugs": "https://github.com/noctcore/eslint-plugins/issues",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@noctcore/eslint-utils": "^0.1.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@noctcore/eslint-test-utils": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@typescript-eslint/rule-tester": "^8.61.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3"
+  }
+}