@zgeoff/oxlint-config 0.0.3 → 0.0.5

package/README.md

@@ -2,9 +2,11 @@
 
 Shareable [oxlint](https://oxc.rs/docs/guide/usage/linter.html) config: every category at `error`,
 restriction-rule cherry-picks, comment-style enforcement via `@stylistic`, and a bundled JS plugin
-(`zgeoff/*` rules) banning AST shapes no native oxlint rule can express — top-level arrows, nested
+(`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, and awaits hidden inside a control-flow condition or a `&&`/`||`/`??` chain.
+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.
 
 ## Usage
 
@@ -33,6 +35,25 @@ import config from '@zgeoff/oxlint-config';
 The plugin is addressable on its own at `@zgeoff/oxlint-config/plugin` for configs that want the
 `zgeoff/*` rules without the rest.
 
+## `zgeoff/function-verb`
+
+Every function declaration, function-valued variable, and class method must start with a verb from
+the function-naming taxonomy. Banned verbs report their taxonomy replacement (`fetchUser` → use
+`read`). Object-literal properties are exempt — they overwhelmingly implement externally-defined
+shapes whose names the author doesn't choose — as are names not starting with a lowercase letter.
+Exempt an algorithm-native name (`walk`, `backtrack`) with a disable comment in the module
+implementing that algorithm.
+
+Options extend the shipped set per repo:
+
+```jsonc
+{
+  "rules": {
+    "zgeoff/function-verb": ["error", { "verbs": ["walk"], "exemptNames": ["main"] }],
+  },
+}
+```
+
 ## Notes
 
 - The config enables the `typescript`, `unicorn`, `oxc`, `import`, and `promise` plugins and loads

package/function-verb.js

@@ -0,0 +1,218 @@
+// the closed verb list from the shared function-naming taxonomy, one entry
+// per table row; extending it here without the matching taxonomy edit fails
+// the drift-guard test
+const taxonomyVerbs = [
+  'is',
+  'has',
+  'can',
+  'should',
+  'needs',
+  'build',
+  'define',
+  'parse',
+  'encode',
+  'decode',
+  'derive',
+  'plan',
+  'pick',
+  'find',
+  'get',
+  'collect',
+  'count',
+  'split',
+  'merge',
+  'sort',
+  'format',
+  'render',
+  'normalize',
+  'resolve',
+  'expand',
+  'compress',
+  'decompress',
+  'to',
+  'transform',
+  'apply',
+  'create',
+  'claim',
+  'read',
+  'load',
+  'write',
+  'remove',
+  'update',
+  'upsert',
+  'set',
+  'toggle',
+  'reset',
+  'print',
+  'run',
+  'check',
+  'try',
+  'register',
+  'subscribe',
+  'unsubscribe',
+  'assert',
+  'require',
+  'verify',
+  'emit',
+  'send',
+  'wait',
+  'setup',
+  'teardown',
+  'start',
+  'stop',
+  'drain',
+  'with',
+  'make',
+  'use',
+  'on',
+  'handle',
+];
+
+// the templated taxonomy entries (`with<X>`, `handle<Event>`, …): the verb is
+// only valid with a suffix, so the bare word is not a function name
+const suffixRequiredVerbs = new Set([
+  'build',
+  'define',
+  'to',
+  'toggle',
+  'try',
+  'with',
+  'make',
+  'use',
+  'on',
+  'handle',
+]);
+
+// banned verb → the taxonomy verb to use instead; null means the verb is too
+// vague to map and the name should say what the function does
+const bannedVerbs = new Map([
+  ['process', null],
+  ['manage', null],
+  ['do', null],
+  ['perform', null],
+  ['execute', 'run'],
+  ['compute', 'build'],
+  ['fetch', 'read'],
+  ['save', 'write'],
+  ['store', 'write'],
+  ['delete', 'remove'],
+  ['search', 'find'],
+  ['lookup', 'find'],
+]);
+
+function isVerbMatch(name, verb, bareAllowed) {
+  if (name === verb) {
+    return bareAllowed;
+  }
+
+  return name.startsWith(verb) && /[A-Z]/u.test(name.charAt(verb.length));
+}
+
+function findAllowedVerb(name, verbs) {
+  return verbs.find((verb) => isVerbMatch(name, verb, !suffixRequiredVerbs.has(verb))) ?? null;
+}
+
+function findBannedVerb(name) {
+  for (const [verb, replacement] of bannedVerbs) {
+    if (isVerbMatch(name, verb, true)) {
+      return { verb, replacement };
+    }
+  }
+
+  return null;
+}
+
+function planReport(name, verbs, exemptNames) {
+  if (exemptNames.has(name) || !/^[a-z]/u.test(name)) {
+    return null;
+  }
+
+  if (findAllowedVerb(name, verbs) !== null) {
+    return null;
+  }
+
+  const banned = findBannedVerb(name);
+
+  if (banned === null) {
+    return { messageId: 'unknownVerb', data: { name } };
+  }
+
+  if (banned.replacement === null) {
+    return { messageId: 'vagueVerb', data: { name, verb: banned.verb } };
+  }
+
+  return {
+    messageId: 'bannedVerb',
+    data: { name, verb: banned.verb, replacement: banned.replacement },
+  };
+}
+
+/**
+ * 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',
+    messages: {
+      unknownVerb:
+        "'{{name}}' does not start with a taxonomy verb — pick one, or extend the taxonomy and the `verbs` option in the same PR.",
+      bannedVerb: "'{{name}}' starts with the banned verb '{{verb}}' — use `{{replacement}}`.",
+      vagueVerb: "'{{name}}' starts with the banned verb '{{verb}}' — name what the function does.",
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          verbs: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          exemptNames: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const verbs =
+      options.verbs === undefined ? taxonomyVerbs : [...taxonomyVerbs, ...options.verbs];
+    const exemptNames = new Set(options.exemptNames);
+
+    const checkName = (id) => {
+      const report = planReport(id.name, verbs, exemptNames);
+
+      if (report !== null) {
+        context.report({ node: id, messageId: report.messageId, data: report.data });
+      }
+    };
+
+    return {
+      FunctionDeclaration(node) {
+        if (node.id !== null) {
+          checkName(node.id);
+        }
+      },
+      VariableDeclarator(node) {
+        const isFunctionInit =
+          node.init !== null &&
+          node.init !== undefined &&
+          (node.init.type === 'ArrowFunctionExpression' || node.init.type === 'FunctionExpression');
+
+        if (isFunctionInit && node.id.type === 'Identifier') {
+          checkName(node.id);
+        }
+      },
+      MethodDefinition(node) {
+        if (node.kind === 'method' && !node.computed && node.key.type === 'Identifier') {
+          checkName(node.key);
+        }
+      },
+    };
+  },
+};
+
+export default functionVerb;

package/oxlintrc.json

@@ -25,6 +25,8 @@
     "zgeoff/no-await-args": "error",
     "zgeoff/no-await-in-condition": "error",
     "zgeoff/no-await-in-logical": "error",
+    "zgeoff/no-single-line-jsdoc": "error",
+    "zgeoff/function-verb": "error",
 
     // enforced comment style — line comments unless JSDoc or exclamation
     "@stylistic/multiline-comment-style": [
@@ -142,8 +144,9 @@
     {
       "files": ["**/*.js", "**/*.cjs", "**/*.mjs"],
       // untyped JS is `any` end to end, so the unsafe-* rules flag every
-      // expression
+      // expression and strict-boolean-expressions every conditional
       "rules": {
+        "typescript/strict-boolean-expressions": "off",
         "typescript/no-unsafe-argument": "off",
         "typescript/no-unsafe-assignment": "off",
         "typescript/no-unsafe-call": "off",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
   "license": "MIT",
   "repository": {
@@ -11,6 +11,7 @@
   "files": [
     "oxlintrc.json",
     "plugin.js",
+    "function-verb.js",
     "index.js"
   ],
   "type": "module",
@@ -22,9 +23,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "typecheck": "tsc"
+  },
   "dependencies": {
     "@stylistic/eslint-plugin": "5.10.0"
   },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "7.0.1-rc"
+  },
   "peerDependencies": {
     "oxlint": ">=1.71.0"
   }

package/plugin.js

@@ -1,8 +1,11 @@
+import functionVerb from './function-verb.js';
+
 // Custom lint rules, loaded through oxlint's jsPlugins (ESLint v9 rule API).
-// Each rule bans an AST shape that no native oxlint rule can express, using
-// esquery selectors.
+// 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.
 
-function banSelectors(type, message, selectors) {
+function buildBanRule(type, message, selectors) {
   return {
     meta: { type, messages: { banned: message }, schema: [] },
     create(context) {
@@ -16,10 +19,86 @@ function banSelectors(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: {
-    'no-top-level-arrow': banSelectors(
+    'no-top-level-arrow': buildBanRule(
       'problem',
       'Declare top-level functions with the `function` keyword instead of assigning an arrow function.',
       [
@@ -29,19 +108,19 @@ const plugin = {
         "Program > ExpressionStatement > AssignmentExpression[right.type='ArrowFunctionExpression']",
       ],
     ),
-    'no-nested-function-declaration': banSelectors(
+    'no-nested-function-declaration': buildBanRule(
       'problem',
       'Use an arrow function here; reserve the `function` keyword for top-level declarations.',
       [
         'FunctionDeclaration:not(Program > FunctionDeclaration):not(Program > ExportNamedDeclaration > FunctionDeclaration):not(Program > ExportDefaultDeclaration > FunctionDeclaration)',
       ],
     ),
-    'no-bare-named-exports': banSelectors(
+    'no-bare-named-exports': buildBanRule(
       'problem',
       'Export declarations inline instead of listing names in `export { ... }`.',
       ['ExportNamedDeclaration[specifiers.length>0][declaration=null][source=null]'],
     ),
-    'no-inline-param-object-types': banSelectors(
+    'no-inline-param-object-types': buildBanRule(
       'problem',
       'Give this parameter a named interface or type alias instead of an inline object-literal type.',
       [
@@ -49,7 +128,7 @@ const plugin = {
         'TSMethodSignature > Identifier.params > TSTypeAnnotation > TSTypeLiteral',
       ],
     ),
-    'no-destructured-params': banSelectors(
+    'no-destructured-params': buildBanRule(
       'suggestion',
       'Accept the parameter whole instead of destructuring it in the signature.',
       [
@@ -57,12 +136,12 @@ const plugin = {
         ':matches(FunctionDeclaration, FunctionExpression, ArrowFunctionExpression) > AssignmentPattern.params > ObjectPattern',
       ],
     ),
-    'no-pick-destructuring': banSelectors(
+    'no-pick-destructuring': buildBanRule(
       'suggestion',
       'Use direct member access; destructure an object only with a rest element to omit properties.',
       ['VariableDeclarator > ObjectPattern:not(:has(> RestElement))'],
     ),
-    'no-ternary-args': banSelectors(
+    'no-ternary-args': buildBanRule(
       'suggestion',
       'Extract this ternary to a named const instead of passing it as an argument.',
       [
@@ -70,12 +149,12 @@ const plugin = {
         'NewExpression > ConditionalExpression.arguments',
       ],
     ),
-    'no-await-args': banSelectors(
+    'no-await-args': buildBanRule(
       'suggestion',
       'Await into a named const instead of awaiting inside an argument list.',
       ['CallExpression > AwaitExpression.arguments', 'NewExpression > AwaitExpression.arguments'],
     ),
-    'no-await-in-condition': banSelectors(
+    'no-await-in-condition': buildBanRule(
       'suggestion',
       'Await into a named const before the statement instead of inside a control-flow condition.',
       [
@@ -83,11 +162,13 @@ const plugin = {
         'SwitchStatement > AwaitExpression.discriminant',
       ],
     ),
-    'no-await-in-logical': banSelectors(
+    'no-await-in-logical': buildBanRule(
       'suggestion',
       'Await into a named const instead of chaining it after a && / || / ?? operator.',
       ['LogicalExpression > AwaitExpression'],
     ),
+    'no-single-line-jsdoc': noSingleLineJSDoc,
+    'function-verb': functionVerb,
   },
 };