@zgeoff/oxlint-config 0.2.9 → 0.2.11

package/README.md

@@ -9,7 +9,8 @@ await arguments, awaits hidden inside a control-flow condition or a `&&`/`||`/`?
 that loosens either comment rule. `zgeoff/function-verb` enforces the function-naming taxonomy from
 the shared agent guidelines, `zgeoff/test-beside-module` keeps each test file beside the module it
 tests, `zgeoff/import-zones` fails an import that crosses a module boundary the repo declares,
-`zgeoff/no-restricted-words` keeps the words in its `words` option out of a path's text, and
+`zgeoff/no-restricted-words` keeps the words in its `words` option out of a path's text,
+`zgeoff/no-abbreviated-names` reports each abbreviated value name it lists with its full word, and
 `zgeoff/no-file-snapshot` bans file snapshots.
 
 ## Usage
@@ -106,6 +107,23 @@ the paths that may name the words:
 }
 ```
 
+## `zgeoff/no-abbreviated-names`
+
+The `names` option maps each abbreviation to the text that replaces it, and the rule reports every
+value name that has one of those names. A value name is any name that a declaration, an import, an
+export alias, a key or a member write binds, so function, class and method names count beside
+variables and properties. A key counts in each of its spellings, so `src`, `'src'`, `['src']` and
+`#src` all report. A name matches whole, so `ms` reports `ms` but not `timeoutMs`.
+
+The rule leaves alone the names that hold no value of their own. A destructured key that an alias
+renames belongs to the object being read, so the rule reports only the alias. A computed key that
+reads a variable, such as `[src]`, names no property, and the rule checks the variable at its
+declaration. Type names, type-only imports and exports, labels and quoted module names hold no
+value, so the rule skips them.
+
+The shipped config lists the abbreviations that the code-style skill bans and turns on `id-length`
+beside the rule, so a one-letter name fails too, other than `x`, `y`, `z`, `$` and `_`.
+
 ## `zgeoff/no-file-snapshot`
 
 Snapshots are inline only, so the golden value sits in the test that pins it. The rule reports every

package/no-abbreviated-names.js

@@ -0,0 +1,271 @@
+// each `names` key is a short name and its value the text that replaces it;
+// the rule matches a whole name, so `timeoutMs` passes when `ms` is listed
+const noAbbreviatedNames = {
+  meta: {
+    type: 'suggestion',
+    messages: {
+      abbreviated:
+        'Rename `{{name}}` to {{replacement}}: name a value for what it holds, in full words.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          names: { type: 'object', additionalProperties: { type: 'string', minLength: 1 } },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const names = new Map(Object.entries(context.options[0]?.names ?? {}));
+
+    if (names.size === 0) {
+      return {};
+    }
+
+    const checkName = (node) => {
+      const name = findStaticName(node);
+
+      if (name === null || !names.has(name)) {
+        return;
+      }
+
+      const prefix = node.type === 'PrivateIdentifier' ? '#' : '';
+
+      context.report({
+        node,
+        messageId: 'abbreviated',
+        data: { name: `${prefix}${name}`, replacement: names.get(name) },
+      });
+    };
+
+    const checkPattern = (node) => {
+      for (const identifier of collectPatternIdentifiers(node)) {
+        checkName(identifier);
+      }
+    };
+
+    // a computed key names its property as a plain key does when it is a
+    // string written in place, as in `{ ['src']: 1 }`; a computed identifier
+    // reads a variable, whose declaration is checked where it is made
+    const checkMemberName = (node, name) => {
+      if (!node.computed || name.type !== 'Identifier') {
+        checkName(name);
+      }
+    };
+
+    const checkKey = (node) => {
+      checkMemberName(node, node.key);
+    };
+
+    const checkParams = (node) => {
+      for (const param of node.params) {
+        checkPattern(param);
+      }
+    };
+
+    // a write to a member names that property, whether the member stands
+    // alone or sits inside a destructuring target
+    const checkAssignmentTarget = (node) => {
+      for (const member of collectTargetMembers(node)) {
+        checkMemberName(member, member.property);
+      }
+    };
+
+    const checkLoopTarget = (node) => {
+      if (node.left.type !== 'VariableDeclaration') {
+        checkAssignmentTarget(node.left);
+      }
+    };
+
+    // function-verb checks only a plain function or method name, so a quoted
+    // method, a signature or a declared function would pass both rules
+    const checkFunction = (node) => {
+      checkName(node.id);
+      checkParams(node);
+    };
+
+    return {
+      VariableDeclarator(node) {
+        checkPattern(node.id);
+      },
+      FunctionDeclaration: checkFunction,
+      FunctionExpression: checkFunction,
+      ArrowFunctionExpression: checkParams,
+
+      // a signature without a body names its parameters as an implementation does
+      TSDeclareFunction: checkFunction,
+      TSEmptyBodyFunctionExpression: checkParams,
+      TSFunctionType: checkParams,
+      TSConstructorType: checkParams,
+      TSMethodSignature(node) {
+        checkKey(node);
+        checkParams(node);
+      },
+      TSCallSignatureDeclaration: checkParams,
+      TSConstructSignatureDeclaration: checkParams,
+      CatchClause(node) {
+        checkPattern(node.param);
+      },
+      'ObjectExpression > Property': checkKey,
+      PropertyDefinition: checkKey,
+      AccessorProperty: checkKey,
+      TSAbstractPropertyDefinition: checkKey,
+      TSAbstractAccessorProperty: checkKey,
+      TSPropertySignature: checkKey,
+      MethodDefinition: checkKey,
+      TSAbstractMethodDefinition: checkKey,
+
+      // a class, an enum and a namespace are values at run time; a quoted
+      // module name is a path, not a value name
+      'ClassDeclaration, ClassExpression, TSEnumDeclaration'(node) {
+        checkName(node.id);
+      },
+      TSModuleDeclaration(node) {
+        if (node.id.type === 'Identifier') {
+          checkName(node.id);
+        }
+      },
+
+      // an import's local binding is a value name in this module, whatever the
+      // exporting module calls it; a type-only import names a type, not a value
+      'ImportSpecifier, ImportDefaultSpecifier, ImportNamespaceSpecifier'(node) {
+        if (!isTypeOnlyImport(node)) {
+          checkName(node.local);
+        }
+      },
+      TSImportEqualsDeclaration(node) {
+        if (node.importKind !== 'type') {
+          checkName(node.id);
+        }
+      },
+      TSIndexSignature(node) {
+        for (const parameter of node.parameters) {
+          checkName(parameter);
+        }
+      },
+      TSEnumMember(node) {
+        checkName(node.id);
+      },
+
+      // an export alias is the name every importing module reads the value by
+      ExportSpecifier(node) {
+        if (!isTypeOnlyExport(node)) {
+          checkName(node.exported);
+        }
+      },
+      ExportAllDeclaration(node) {
+        if (node.exportKind !== 'type') {
+          checkName(node.exported);
+        }
+      },
+      AssignmentExpression(node) {
+        checkAssignmentTarget(node.left);
+      },
+      ForInStatement: checkLoopTarget,
+      ForOfStatement: checkLoopTarget,
+    };
+  },
+};
+
+// the name a key or binding spells out in the source: an identifier, a
+// string, or a template with no substitutions; a key built at run time has
+// no static name, so the result is null
+function findStaticName(node) {
+  if (node?.type === 'Identifier' || node?.type === 'PrivateIdentifier') {
+    return node.name;
+  }
+
+  if (node?.type === 'Literal' && typeof node.value === 'string') {
+    return node.value;
+  }
+
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0].value.cooked ?? null;
+  }
+
+  return null;
+}
+
+function isTypeOnlyImport(specifier) {
+  return specifier.importKind === 'type' || specifier.parent.importKind === 'type';
+}
+
+function isTypeOnlyExport(specifier) {
+  return specifier.exportKind === 'type' || specifier.parent.exportKind === 'type';
+}
+
+// the members an assignment target writes; a bare identifier in the target
+// writes a variable declared elsewhere, and its declaration is checked there
+function collectTargetMembers(node) {
+  if (node === null || node === undefined) {
+    return [];
+  }
+
+  if (node.type === 'MemberExpression') {
+    return [node];
+  }
+
+  if (node.type === 'ObjectPattern') {
+    return node.properties.flatMap((property) => {
+      const target = property.type === 'RestElement' ? property : property.value;
+
+      return collectTargetMembers(target);
+    });
+  }
+
+  if (node.type === 'ArrayPattern') {
+    return node.elements.flatMap((element) => collectTargetMembers(element));
+  }
+
+  if (node.type === 'AssignmentPattern') {
+    return collectTargetMembers(node.left);
+  }
+
+  if (node.type === 'RestElement') {
+    return collectTargetMembers(node.argument);
+  }
+
+  return [];
+}
+
+// the names a binding pattern declares: a destructured key's alias, not the
+// key, since the key belongs to the object being read
+function collectPatternIdentifiers(node) {
+  if (node === null || node === undefined) {
+    return [];
+  }
+
+  if (node.type === 'Identifier') {
+    return [node];
+  }
+
+  if (node.type === 'ObjectPattern') {
+    return node.properties.flatMap((property) => {
+      const binding = property.type === 'RestElement' ? property : property.value;
+
+      return collectPatternIdentifiers(binding);
+    });
+  }
+
+  if (node.type === 'ArrayPattern') {
+    return node.elements.flatMap((element) => collectPatternIdentifiers(element));
+  }
+
+  if (node.type === 'AssignmentPattern') {
+    return collectPatternIdentifiers(node.left);
+  }
+
+  if (node.type === 'RestElement') {
+    return collectPatternIdentifiers(node.argument);
+  }
+
+  if (node.type === 'TSParameterProperty') {
+    return collectPatternIdentifiers(node.parameter);
+  }
+
+  return [];
+}
+
+export default noAbbreviatedNames;

package/oxlintrc.json

@@ -33,6 +33,35 @@
     "zgeoff/test-beside-module": "error",
     "zgeoff/no-file-snapshot": "error",
 
+    // name a value for what it holds, in full words: one letter only for a
+    // coordinate, zod's `z`, Bun's shell `$` or an unread `_` placeholder, and
+    // each listed abbreviation reported with its full word; both rules read
+    // every binding (destructured aliases and imports included) and every
+    // property key, but a type parameter is not a value, so generics stay
+    // unchecked
+    "id-length": [
+      "error",
+      { "min": 2, "exceptions": ["x", "y", "z", "$", "_"], "checkGeneric": false }
+    ],
+    // oxlintrc.test.ts holds the same names with their full words, and fails
+    // when an entry changes here without it
+    "zgeoff/no-abbreviated-names": [
+      "error",
+      {
+        "names": {
+          "mgr": "`manager`",
+          "dir": "`directory`",
+          "tmp": "`temporary`",
+          "proc": "`process`",
+          "src": "`source`",
+          "dest": "`destination`",
+          "prev": "`previous`",
+          "msg": "`message`",
+          "ms": "a name for the value with `Ms` as its unit suffix, such as `timeoutMs`"
+        }
+      }
+    ],
+
     // enforced comment style — line comments unless JSDoc or exclamation
     "@stylistic/multiline-comment-style": [
       "error",
@@ -114,14 +143,13 @@
     // category-enabled rules that contradict this config's style: inline named
     // export declarations are the convention (group-exports demands the exact
     // form no-bare-named-exports bans), keys group by meaning not alphabet,
-    // comments stay lowercase, short identifiers and literal numbers are fine
+    // comments stay lowercase, and literal numbers are fine
     "import/prefer-default-export": "off",
     "import/no-named-export": "off",
     "import/exports-last": "off",
     "import/group-exports": "off",
     "sort-keys": "off",
     "capitalized-comments": "off",
-    "id-length": "off",
     "no-magic-numbers": "off",
     // prefer-ternary (only-single-line, above) wants ternaries where they fit
     // on one line; no-ternary would ban the same code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
   "license": "MIT",
   "repository": {
@@ -13,6 +13,7 @@
     "plugin.js",
     "function-verb.js",
     "no-restricted-words.js",
+    "no-abbreviated-names.js",
     "max-consecutive-line-comments.js",
     "no-jsdoc.js",
     "no-comment-rule-override.js",

package/plugin.js

@@ -1,6 +1,7 @@
 import functionVerb from './function-verb.js';
 import importZones from './import-zones.js';
 import maxConsecutiveLineComments from './max-consecutive-line-comments.js';
+import noAbbreviatedNames from './no-abbreviated-names.js';
 import noCommentRuleOverride from './no-comment-rule-override.js';
 import noFileSnapshot from './no-file-snapshot.js';
 import noJSDoc from './no-jsdoc.js';
@@ -107,6 +108,7 @@ const plugin = {
     'no-comment-rule-override': noCommentRuleOverride,
     'function-verb': functionVerb,
     'no-restricted-words': noRestrictedWords,
+    'no-abbreviated-names': noAbbreviatedNames,
     'test-beside-module': testBesideModule,
     'no-file-snapshot': noFileSnapshot,
     'import-zones': importZones,