@zgeoff/oxlint-config 0.0.4 → 0.0.6

package/README.md

@@ -6,6 +6,7 @@ restriction-rule cherry-picks, comment-style enforcement via `@stylistic`, and a
 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.
 
 ## Usage
 
@@ -34,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,219 @@
+// 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;
+  }
+
+  // a digit also ends the verb: acronyms like 2FA start camelCase segments
+  return name.startsWith(verb) && /[A-Z0-9]/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

@@ -26,6 +26,7 @@
     "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": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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",

package/plugin.js

@@ -1,9 +1,11 @@
+import functionVerb from './function-verb.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.
 
-function banSelectors(type, message, selectors) {
+function buildBanRule(type, message, selectors) {
   return {
     meta: { type, messages: { banned: message }, schema: [] },
     create(context) {
@@ -96,7 +98,7 @@ const noSingleLineJSDoc = {
 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.',
       [
@@ -106,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.',
       [
@@ -126,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.',
       [
@@ -134,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.',
       [
@@ -147,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.',
       [
@@ -160,12 +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,
   },
 };