@zgeoff/oxlint-config 0.0.6 → 0.2.0

package/README.md

@@ -4,9 +4,10 @@ Shareable [oxlint](https://oxc.rs/docs/guide/usage/linter.html) config: every ca
 restriction-rule cherry-picks, comment-style enforcement via `@stylistic`, and a bundled JS plugin
 (`zgeoff/*` rules) banning shapes no native oxlint rule can express — top-level arrows, nested
 function declarations, bare named exports, destructured and inline-typed parameters, ternary and
-await arguments, awaits hidden inside a control-flow condition or a `&&`/`||`/`??` chain, and
-single-line `/** … */` blocks (auto-fixed to multi-line; inline `@type`/`@lends` casts exempt).
-`zgeoff/function-verb` enforces the function-naming taxonomy from the shared agent guidelines.
+await arguments, awaits hidden inside a control-flow condition or a `&&`/`||`/`??` chain, every
+JSDoc block, and any run of more than three line comments. `zgeoff/function-verb` enforces the
+function-naming taxonomy from the shared agent guidelines, and `zgeoff/test-beside-module` keeps
+each test file beside the module it tests.
 
 ## Usage
 
@@ -54,6 +55,39 @@ Options extend the shipped set per repo:
 }
 ```
 
+## `zgeoff/no-jsdoc` and `zgeoff/max-consecutive-line-comments`
+
+A comment holds only what neither the code, a type, a test name, nor the subsystem doc can hold: the
+reason a line does the non-obvious thing. `no-jsdoc` reports every `/** … */` block (inline
+`@type`/`@lends` casts exempt). `max-consecutive-line-comments` reports a run of own-line `//`
+comments longer than `max` (default 3); tool directives (`oxlint-`, `eslint-`, `@ts-`, …) neither
+count nor join the prose around them. Neither rule fixes: a deleted comment is a decision, not a
+whitespace change.
+
+```jsonc
+{
+  "rules": {
+    "zgeoff/max-consecutive-line-comments": ["error", { "max": 3 }],
+  },
+}
+```
+
+## `zgeoff/test-beside-module`
+
+A `<name>.test.ts` or `<name>.test.tsx` file needs a non-test file `<name>.<ext>` in the same
+directory — `.ts`, `.tsx`, `.sh`, `.json`, or any other single extension, so `install.test.ts` may
+test `install.sh`. Files under an `e2e/` or `evals/` directory at the repo root (the nearest
+ancestor holding `.git`, else oxlint's working directory) are exempt; no other directory is. Exempt
+any other test with a file-level disable comment that states the reason. The rule reports at the
+first statement, so put the comment above it:
+
+```ts
+// oxlint-disable zgeoff/test-beside-module -- tests base.json and react.json together
+```
+
+A second test file for a module (`<name>.host.test.ts`) needs its own `<name>.host.<ext>`, so the
+rule reports it beside only `<name>.ts`.
+
 ## Notes
 
 - The config enables the `typescript`, `unicorn`, `oxc`, `import`, and `promise` plugins and loads

package/function-verb.js

@@ -148,15 +148,6 @@ function planReport(name, verbs, exemptNames) {
   };
 }
 
-/**
- * Enforces the function-naming taxonomy on function declarations,
- * function-valued variables, and class methods. Object-literal properties are
- * exempt — they overwhelmingly implement externally-defined shapes (rule
- * visitors, route tables) whose names the author doesn't choose — as are
- * names not starting with a lowercase letter (components, classes).
- * Options: `verbs` appends repo-local verbs to the shipped taxonomy;
- * `exemptNames` skips exact names.
- */
 const functionVerb = {
   meta: {
     type: 'suggestion',

package/max-consecutive-line-comments.js

@@ -0,0 +1,76 @@
+// tool directives are not prose: they neither count toward a run nor join
+// the prose on either side of them into one
+const directivePattern =
+  /^\s*(?:oxlint-|eslint-|@ts-|prettier-|oxfmt-|biome-ignore|#region|#endregion|\/\s*<)/u;
+
+function isOwnLine(text, comment) {
+  const lineStart = text.lastIndexOf('\n', comment.range[0] - 1) + 1;
+
+  return /^[ \t]*$/u.test(text.slice(lineStart, comment.range[0]));
+}
+
+function isProseLine(text, comment) {
+  return (
+    comment.type === 'Line' && !directivePattern.test(comment.value) && isOwnLine(text, comment)
+  );
+}
+
+// a run is prose line comments on consecutive lines; whatever else occupies
+// a line between two of them (code, a blank, a directive, a block comment)
+// breaks adjacency and so ends the run
+function collectRuns(text, comments) {
+  const runs = [];
+
+  for (const comment of comments.filter((candidate) => isProseLine(text, candidate))) {
+    const run = runs.at(-1);
+
+    if (run !== undefined && comment.loc.start.line === run.at(-1).loc.end.line + 1) {
+      run.push(comment);
+    } else {
+      runs.push([comment]);
+    }
+  }
+
+  return runs;
+}
+
+const maxConsecutiveLineComments = {
+  meta: {
+    type: 'suggestion',
+    messages: {
+      tooLong:
+        'This comment run is {{count}} lines; the limit is {{max}}. Cut it to the fact the code cannot show, or move it into a test name or the subsystem doc.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          max: { type: 'integer', minimum: 1 },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const max = context.options[0]?.max ?? 3;
+
+    return {
+      Program() {
+        const text = context.sourceCode.text;
+        const runs = collectRuns(text, context.sourceCode.getAllComments());
+
+        for (const run of runs) {
+          if (run.length > max) {
+            context.report({
+              loc: { start: run[0].loc.start, end: run.at(-1).loc.end },
+              messageId: 'tooLong',
+              data: { count: String(run.length), max: String(max) },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default maxConsecutiveLineComments;

package/no-jsdoc.js

@@ -0,0 +1,40 @@
+// mirrors eslint-plugin-jsdoc's default singleLineTags: a block that exists to
+// cast inline (`/** @type {Foo} */ (bar)`) is a type annotation, not prose
+const inlineTagPattern = /^@(?:type|lends)\b/u;
+
+function isJSDoc(comment) {
+  return comment.type === 'Block' && comment.value.startsWith('*');
+}
+
+function isInlineCast(comment) {
+  return (
+    comment.loc.start.line === comment.loc.end.line &&
+    inlineTagPattern.test(comment.value.slice(1).trim())
+  );
+}
+
+const noJSDoc = {
+  meta: {
+    type: 'suggestion',
+    messages: {
+      jsdoc:
+        'Delete this JSDoc block. A rule a caller must respect is a test whose name states it or a sentence in the subsystem doc; the reason a line does the non-obvious thing is a `//` at that line.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Program() {
+        const offenders = context.sourceCode
+          .getAllComments()
+          .filter((comment) => isJSDoc(comment) && !isInlineCast(comment));
+
+        for (const comment of offenders) {
+          context.report({ loc: comment.loc, messageId: 'jsdoc' });
+        }
+      },
+    };
+  },
+};
+
+export default noJSDoc;

package/oxlintrc.json

@@ -25,8 +25,10 @@
     "zgeoff/no-await-args": "error",
     "zgeoff/no-await-in-condition": "error",
     "zgeoff/no-await-in-logical": "error",
-    "zgeoff/no-single-line-jsdoc": "error",
+    "zgeoff/no-jsdoc": "error",
+    "zgeoff/max-consecutive-line-comments": ["error", { "max": 3 }],
     "zgeoff/function-verb": "error",
+    "zgeoff/test-beside-module": "error",
 
     // enforced comment style — line comments unless JSDoc or exclamation
     "@stylistic/multiline-comment-style": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.0.6",
+  "version": "0.2.0",
   "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,9 @@
     "oxlintrc.json",
     "plugin.js",
     "function-verb.js",
+    "max-consecutive-line-comments.js",
+    "no-jsdoc.js",
+    "test-beside-module.js",
     "index.js"
   ],
   "type": "module",

package/plugin.js

@@ -1,9 +1,11 @@
 import functionVerb from './function-verb.js';
+import maxConsecutiveLineComments from './max-consecutive-line-comments.js';
+import noJSDoc from './no-jsdoc.js';
+import testBesideModule from './test-beside-module.js';
 
-// Custom lint rules, loaded through oxlint's jsPlugins (ESLint v9 rule API).
-// Each rule bans a shape no native oxlint rule can express — esquery selectors
-// for AST shapes, a source-comment scan where the target isn't
-// esquery-selectable.
+// custom rules loaded through oxlint's jsPlugins (ESLint v9 rule API): each
+// bans a shape no native oxlint rule can express, as an esquery selector or a
+// source-comment scan
 
 function buildBanRule(type, message, selectors) {
   return {
@@ -19,82 +21,6 @@ function buildBanRule(type, message, selectors) {
   };
 }
 
-// mirrors eslint-plugin-jsdoc's default singleLineTags: blocks that exist to
-// cast inline (`/** @type {Foo} */ (bar)`) stay single-line by design
-const inlineTagPattern = /^@(?:type|lends)\b/u;
-
-function isSingleLineJSDoc(comment) {
-  return (
-    comment.type === 'Block' &&
-    comment.value.startsWith('*') &&
-    comment.loc.start.line === comment.loc.end.line
-  );
-}
-
-/**
- * Builds the multi-line replacement for a single-line JSDoc comment, or null
- * when the comment shares its line with code — expanding those in place would
- * scramble the surrounding statement, so they are reported without a fix.
- */
-function planExpansion(text, comment) {
-  if (!isOwnLine(text, comment)) {
-    return null;
-  }
-
-  const lineStart = text.lastIndexOf('\n', comment.range[0] - 1) + 1;
-  const indent = text.slice(lineStart, comment.range[0]);
-  const body = comment.value.slice(1).trim();
-  const bodyLine = body === '' ? `${indent} *` : `${indent} * ${body}`;
-
-  return `/**\n${bodyLine}\n${indent} */`;
-}
-
-function isOwnLine(text, comment) {
-  const [start, end] = comment.range;
-  const lineStart = text.lastIndexOf('\n', start - 1) + 1;
-  const lineEnd = text.indexOf('\n', end);
-  const sliceEnd = lineEnd === -1 ? text.length : lineEnd;
-
-  return /^[ \t]*$/u.test(text.slice(lineStart, start)) && text.slice(end, sliceEnd).trim() === '';
-}
-
-const noSingleLineJSDoc = {
-  meta: {
-    type: 'layout',
-    fixable: 'whitespace',
-    messages: {
-      singleLine:
-        'Write JSDoc blocks multi-line: `/**` alone, one `*`-prefixed line per point, `*/` alone.',
-    },
-    schema: [],
-  },
-  create(context) {
-    return {
-      Program() {
-        const offenders = context.sourceCode
-          .getAllComments()
-          .filter(
-            (comment) =>
-              isSingleLineJSDoc(comment) && !inlineTagPattern.test(comment.value.slice(1).trim()),
-          );
-
-        for (const comment of offenders) {
-          const replacement = planExpansion(context.sourceCode.text, comment);
-
-          context.report({
-            loc: comment.loc,
-            messageId: 'singleLine',
-            fix:
-              replacement === null
-                ? undefined
-                : (fixer) => fixer.replaceTextRange(comment.range, replacement),
-          });
-        }
-      },
-    };
-  },
-};
-
 const plugin = {
   meta: { name: 'zgeoff' },
   rules: {
@@ -167,8 +93,10 @@ const plugin = {
       'Await into a named const instead of chaining it after a && / || / ?? operator.',
       ['LogicalExpression > AwaitExpression'],
     ),
-    'no-single-line-jsdoc': noSingleLineJSDoc,
+    'no-jsdoc': noJSDoc,
+    'max-consecutive-line-comments': maxConsecutiveLineComments,
     'function-verb': functionVerb,
+    'test-beside-module': testBesideModule,
   },
 };
 

package/test-beside-module.js

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+
+const testFilePattern = /^(?<base>.+)\.test\.tsx?$/u;
+
+// suites that run the whole program have no single module to sit beside
+const exemptRootDirs = new Set(['e2e', 'evals']);
+
+function isUnderExemptRoot(cwd, filename) {
+  const [first] = relative(findRepoRoot(filename) ?? cwd, filename).split(sep);
+
+  return exemptRootDirs.has(first);
+}
+
+// the repo root, not oxlint's working directory, so a per-package lint
+// script neither exempts a package's own e2e/ nor flags the root one
+function findRepoRoot(filename) {
+  let dir = dirname(filename);
+
+  while (!existsSync(join(dir, '.git'))) {
+    const parent = dirname(dir);
+
+    if (parent === dir) {
+      return null;
+    }
+
+    dir = parent;
+  }
+
+  return dir;
+}
+
+// a module is `<name>.<ext>` with a single-segment extension, so a
+// declaration file never stands in for one, and neither does another test
+// (`foo.test.ts` beside `foo.test.test.ts`)
+function hasModuleSibling(dir, name) {
+  return readdirSync(dir).some((entry) => {
+    const dot = entry.lastIndexOf('.');
+
+    return (
+      dot > 0 &&
+      entry.slice(0, dot) === name &&
+      !testFilePattern.test(entry) &&
+      isFile(join(dir, entry))
+    );
+  });
+}
+
+// follows a symlink, so a linked module counts as the file it points at
+function isFile(path) {
+  return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
+}
+
+const testBesideModule = {
+  meta: {
+    type: 'problem',
+    messages: {
+      missing:
+        'Move this test beside the module it tests: no `{{name}}.<ext>` sits in this directory. Whole-program suites belong in a root `e2e/` or `evals/` directory.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Program() {
+        const filename = context.physicalFilename;
+        const match = testFilePattern.exec(basename(filename));
+
+        if (match === null || isUnderExemptRoot(context.cwd, filename)) {
+          return;
+        }
+
+        const name = match.groups.base;
+
+        if (hasModuleSibling(dirname(filename), name)) {
+          return;
+        }
+
+        // anchor on the first statement, not offset 0, so a disable comment
+        // at the top of the file sits before the report and covers it
+        const start = context.sourceCode.ast.body[0]?.loc.start ?? { line: 1, column: 0 };
+
+        context.report({
+          loc: { start, end: start },
+          messageId: 'missing',
+          data: { name },
+        });
+      },
+    };
+  },
+};
+
+export default testBesideModule;