@crescware/eslint-plugin-crescware-iteration-var-names 0.0.2

package/README.md

@@ -0,0 +1,32 @@
+# @crescware/eslint-plugin-crescware-iteration-var-names
+
+ESLint plugin that bans thoughtless single-character variables in iteration contexts.
+
+## Stack
+
+- **Runtime**: Node.js 24 (via [mise](https://mise.jdx.dev/))
+- **Package manager**: pnpm (via corepack)
+- **Language**: TypeScript ([native preview](https://github.com/nicolo-ribaudo/tc39-proposal-type-annotations))
+- **Test**: [Vitest](https://vitest.dev/)
+- **Lint**: [oxlint](https://oxc.rs/docs/guide/usage/linter)
+- **Format**: [oxfmt](https://github.com/nicolo-ribaudo/oxfmt)
+- **Unused code**: [Knip](https://knip.dev/)
+
+## Setup
+
+```sh
+mise install
+corepack enable
+pnpm install
+```
+
+## Scripts
+
+| Command            | Description                              |
+| ------------------ | ---------------------------------------- |
+| `pnpm check`       | Run all checks (types, lint, knip, test) |
+| `pnpm check:types` | Type check                               |
+| `pnpm check:lint`  | Lint and format check                    |
+| `pnpm check:knip`  | Unused files/exports check               |
+| `pnpm test`        | Run tests                                |
+| `pnpm format`      | Fix lint and format                      |

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+type ReportDescriptor = {
+    message: string;
+    node: unknown;
+};
+type RuleContext = {
+    report: (descriptor: ReportDescriptor) => void;
+};
+type Visitor = Record<string, (node: never) => void>;
+type Rule = {
+    meta?: Record<string, unknown>;
+    create: (context: RuleContext) => Visitor;
+};
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "array-callback-arg-names": Rule;
+    };
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,177 @@
+const TARGET_METHODS = new Set([
+    "map",
+    "filter",
+    "forEach",
+    "find",
+    "findIndex",
+    "findLast",
+    "findLastIndex",
+    "some",
+    "every",
+    "flatMap",
+    "reduce",
+    "reduceRight",
+    "sort",
+]);
+const expectedNamesFor = (kind) => {
+    switch (kind) {
+        case "reduce-sync":
+            return ["acc", "v", "i", "arr"];
+        case "reduce-async":
+            return ["prev", "v", "i", "arr"];
+        case "sort":
+            return ["a", "b"];
+        case "iterator":
+            return ["v", "i", "arr"];
+    }
+};
+const methodKindOf = (methodName, isAsync) => {
+    if (methodName === "reduce" || methodName === "reduceRight") {
+        return isAsync ? "reduce-async" : "reduce-sync";
+    }
+    if (methodName === "sort") {
+        return "sort";
+    }
+    if (TARGET_METHODS.has(methodName)) {
+        return "iterator";
+    }
+    return null;
+};
+const getTargetMethodName = (call) => {
+    const callee = call.callee;
+    if (callee.type !== "MemberExpression") {
+        return null;
+    }
+    if (callee.computed === true) {
+        return null;
+    }
+    const property = callee.property;
+    if (property === undefined || property.type !== "Identifier") {
+        return null;
+    }
+    const name = property.name;
+    if (name === undefined || !TARGET_METHODS.has(name)) {
+        return null;
+    }
+    return name;
+};
+const getCallbackFunction = (call) => {
+    const first = call.arguments[0];
+    if (first === undefined) {
+        return null;
+    }
+    if (first.type !== "ArrowFunctionExpression" &&
+        first.type !== "FunctionExpression") {
+        return null;
+    }
+    return first;
+};
+const isIdentifier = (node) => {
+    return (node !== undefined &&
+        node.type === "Identifier" &&
+        typeof node.name === "string");
+};
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce naming convention for Array.prototype callback arguments (v/i/arr, acc, prev, a/b).",
+        },
+        schema: [],
+    },
+    create(context) {
+        const callbackStack = [];
+        const callbackToFrame = new WeakMap();
+        const reportInner = (param, methodName, kind, paramIndex) => {
+            const expected = expectedNamesFor(kind)[paramIndex];
+            if (expected === undefined) {
+                return;
+            }
+            if (param.name.length >= 2) {
+                return;
+            }
+            if (param.name === expected) {
+                return;
+            }
+            context.report({
+                message: `Array.prototype.${methodName} expects '${expected}' for argument ${paramIndex + 1} (got: '${param.name}').`,
+                node: param,
+            });
+        };
+        const reportOuter = (param, methodName) => {
+            if (param.name.length >= 2) {
+                return;
+            }
+            context.report({
+                message: `Avoid the single-character name '${param.name}' on an outer Array.prototype.${methodName} callback; use a meaningful name with 2 or more characters.`,
+                node: param,
+            });
+        };
+        const onCallEnter = (node) => {
+            const methodName = getTargetMethodName(node);
+            if (methodName === null) {
+                return;
+            }
+            const callback = getCallbackFunction(node);
+            if (callback === null) {
+                return;
+            }
+            const kind = methodKindOf(methodName, callback.async === true);
+            if (kind === null) {
+                return;
+            }
+            const frame = { kind, methodName, hasNested: false };
+            callbackToFrame.set(callback, frame);
+            const top = callbackStack[callbackStack.length - 1];
+            if (top !== undefined) {
+                top.hasNested = true;
+            }
+        };
+        const onFunctionEnter = (node) => {
+            const frame = callbackToFrame.get(node);
+            if (frame === undefined) {
+                return;
+            }
+            callbackStack.push(frame);
+        };
+        const onFunctionExit = (node) => {
+            const frame = callbackToFrame.get(node);
+            if (frame === undefined) {
+                return;
+            }
+            const popped = callbackStack.pop();
+            if (popped !== frame) {
+                return;
+            }
+            const expected = expectedNamesFor(frame.kind);
+            const params = node.params;
+            const limit = Math.min(params.length, expected.length);
+            for (let i = 0; i < limit; i++) {
+                const param = params[i];
+                if (!isIdentifier(param)) {
+                    continue;
+                }
+                if (frame.hasNested) {
+                    reportOuter(param, frame.methodName);
+                }
+                else {
+                    reportInner(param, frame.methodName, frame.kind, i);
+                }
+            }
+        };
+        return {
+            CallExpression: onCallEnter,
+            ArrowFunctionExpression: onFunctionEnter,
+            "ArrowFunctionExpression:exit": onFunctionExit,
+            FunctionExpression: onFunctionEnter,
+            "FunctionExpression:exit": onFunctionExit,
+        };
+    },
+};
+const plugin = {
+    meta: { name: "crescware-iteration-var-names" },
+    rules: {
+        "array-callback-arg-names": rule,
+    },
+};
+export default plugin;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@crescware/eslint-plugin-crescware-iteration-var-names",
+  "version": "0.0.2",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsgo -p tsconfig.build.json",
+    "check": "pnpm run check:types && pnpm run check:lint && pnpm run check:knip && pnpm run test",
+    "check:knip": "knip",
+    "check:lint": "oxlint && oxfmt --check",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "exec:fixtures": "oxlint -c fixtures/oxlintrc.fixtures.json --no-ignore -f json fixtures/",
+    "format": "oxlint --fix && oxfmt",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.2",
+    "@typescript/native-preview": "7.0.0-dev.20260422.1",
+    "knip": "6.7.0",
+    "oxfmt": "0.47.0",
+    "oxlint": "1.62.0",
+    "rimraf": "6.1.3",
+    "vitest": "4.1.5"
+  },
+  "packageManager": "pnpm@10.33.2"
+}