@barnum/eslint-plugin 0.0.0-main-9c142eea

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const plugin: {
+    rules: {
+        "exported-handler": import("eslint").Rule.RuleModule;
+        "require-callback-params": import("eslint").Rule.RuleModule;
+        "require-type-params": import("eslint").Rule.RuleModule;
+    };
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,11 @@
+import exportedHandler from "./rules/exported-handler.js";
+import requireCallbackParams from "./rules/require-callback-params.js";
+import requireTypeParams from "./rules/require-type-params.js";
+const plugin = {
+    rules: {
+        "exported-handler": exportedHandler,
+        "require-callback-params": requireCallbackParams,
+        "require-type-params": requireTypeParams,
+    },
+};
+export default plugin;

package/dist/rules/exported-handler.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/exported-handler.js

@@ -0,0 +1,147 @@
+const HANDLER_FACTORIES = new Set([
+    "createHandler",
+    "createHandlerWithConfig",
+]);
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require createHandler/createHandlerWithConfig calls to be exported with a name matching the exportName argument",
+        },
+        messages: {
+            unexported: "createHandler/createHandlerWithConfig must be exported. The runtime resolves handlers by module path + export name.",
+            nameMismatch: "Export name '{{ exportName }}' does not match the exportName argument '{{ argName }}'. The runtime uses the exportName argument to locate the handler at {{ module }}:{{ argName }}.",
+            defaultMissingArg: "Default exports should omit the exportName argument or pass 'default'. Got '{{ argName }}'.",
+            moduleExports: "module.exports assignment is not supported. Use ES module export syntax.",
+        },
+        schema: [],
+    },
+    create(context) {
+        function getCalleeHandlerName(node) {
+            if (node.type === "CallExpression" &&
+                node.callee?.type === "Identifier" &&
+                node.callee.name &&
+                HANDLER_FACTORIES.has(node.callee.name)) {
+                return node.callee.name;
+            }
+            return undefined;
+        }
+        function getExportNameArg(node) {
+            // Second argument is the exportName string
+            const arg = node.arguments[1];
+            if (!arg)
+                return null;
+            if (arg.type === "Literal" && typeof arg.value === "string") {
+                return arg.value;
+            }
+            // Non-string-literal second arg — can't statically verify
+            return null;
+        }
+        return {
+            // Catch module.exports.foo = createHandler(...)
+            AssignmentExpression(node) {
+                if (node.right.type === "CallExpression" &&
+                    getCalleeHandlerName(node.right)) {
+                    if (node.left.type === "MemberExpression" &&
+                        node.left.object.type === "MemberExpression" &&
+                        node.left.object.object.type === "Identifier" &&
+                        node.left.object.object.name === "module" &&
+                        node.left.object.property.type === "Identifier" &&
+                        node.left.object.property.name === "exports") {
+                        context.report({ node, messageId: "moduleExports" });
+                        return;
+                    }
+                    if (node.left.type === "MemberExpression" &&
+                        node.left.object.type === "Identifier" &&
+                        node.left.object.name === "exports") {
+                        context.report({ node, messageId: "moduleExports" });
+                        return;
+                    }
+                }
+            },
+            // Catch all CallExpressions to createHandler/createHandlerWithConfig
+            CallExpression(node) {
+                if (!getCalleeHandlerName(node))
+                    return;
+                // Walk up to find if this is in an export context
+                const parent = node.parent;
+                if (!parent) {
+                    context.report({ node, messageId: "unexported" });
+                    return;
+                }
+                // Already reported by AssignmentExpression handler
+                if (parent.type === "AssignmentExpression") {
+                    return;
+                }
+                // Case 1: export default createHandler(...)
+                if (parent.type === "ExportDefaultDeclaration") {
+                    const argName = getExportNameArg(node);
+                    if (argName !== null && argName !== "default") {
+                        context.report({
+                            node,
+                            messageId: "defaultMissingArg",
+                            data: { argName },
+                        });
+                    }
+                    return;
+                }
+                // Case 2: export const foo = createHandler({...}, "foo")
+                // The CallExpression is inside a VariableDeclarator
+                if (parent.type === "VariableDeclarator") {
+                    const declaration = parent.parent;
+                    if (!declaration || declaration.type !== "VariableDeclaration") {
+                        context.report({ node, messageId: "unexported" });
+                        return;
+                    }
+                    const exportNode = declaration.parent;
+                    if (!exportNode ||
+                        exportNode.type !== "ExportNamedDeclaration") {
+                        context.report({ node, messageId: "unexported" });
+                        return;
+                    }
+                    // It's exported — now check name match
+                    if (parent.id.type !== "Identifier") {
+                        // Destructuring pattern — weird but report
+                        context.report({ node, messageId: "unexported" });
+                        return;
+                    }
+                    const exportName = parent.id.name;
+                    const argName = getExportNameArg(node);
+                    // If no second arg, the runtime uses "default" — that won't match
+                    // a named export unless the export is literally named "default"
+                    if (argName === null && node.arguments.length < 2) {
+                        // No exportName arg provided — runtime defaults to "default"
+                        // but this is a named export, so it won't resolve
+                        if (exportName !== "default") {
+                            context.report({
+                                node,
+                                messageId: "nameMismatch",
+                                data: {
+                                    exportName,
+                                    argName: "default",
+                                    module: "<this file>",
+                                },
+                            });
+                        }
+                        return;
+                    }
+                    if (argName !== null && argName !== exportName) {
+                        context.report({
+                            node,
+                            messageId: "nameMismatch",
+                            data: {
+                                exportName,
+                                argName,
+                                module: "<this file>",
+                            },
+                        });
+                    }
+                    return;
+                }
+                // Any other position — not exported
+                context.report({ node, messageId: "unexported" });
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/require-callback-params.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/require-callback-params.js

@@ -0,0 +1,57 @@
+/**
+ * Combinator name → minimum required callback params (first argument).
+ * Applies to both standalone calls and postfix method calls by name.
+ * Add/remove entries here to adjust what's tracked.
+ */
+const MIN_CALLBACK_PARAMS = new Map([
+    ["bindInput", 1],
+    ["loop", 1],
+    ["earlyReturn", 1],
+]);
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require combinator callbacks to declare their parameters. A zero-arity callback ignores values the combinator provides.",
+        },
+        messages: {
+            missingParams: "'{{ name }}' callback must declare at least {{ min }} parameter(s). The callback receives values from the combinator — ignoring them is likely a bug.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                let name;
+                if (node.callee.type === "Identifier") {
+                    name = node.callee.name;
+                }
+                else if (node.callee.type === "MemberExpression" &&
+                    node.callee
+                        .property.type === "Identifier") {
+                    name = node.callee.property.name;
+                }
+                else {
+                    return;
+                }
+                const minParams = MIN_CALLBACK_PARAMS.get(name);
+                if (minParams === undefined)
+                    return;
+                const bodyArg = node.arguments?.[0];
+                if (!bodyArg)
+                    return;
+                if (bodyArg.type === "ArrowFunctionExpression" ||
+                    bodyArg.type === "FunctionExpression") {
+                    if (bodyArg.params.length < minParams) {
+                        context.report({
+                            node: bodyArg,
+                            messageId: "missingParams",
+                            data: { name, min: String(minParams) },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/require-type-params.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/require-type-params.js

@@ -0,0 +1,92 @@
+/** Standalone call configs: loop(...), bindInput(...), earlyReturn(...) */
+const STANDALONE_CONFIG = new Map([
+    ["loop", { minParams: 1, params: ["input", "output"] }], // TIn, TOut
+    ["earlyReturn", { minParams: 1, params: ["output", "input", "output"] }], // TEarlyReturn, TIn, TOut
+    ["bindInput", { minParams: 2, params: ["input", "output"] }], // TIn, TOut
+]);
+/** Postfix method call configs: x.bindInput<TOut>(...) */
+const POSTFIX_CONFIG = new Map([
+    ["bindInput", { minParams: 1, params: ["output"] }], // TOut only
+]);
+function getTypeName(node) {
+    if (node.type === "TSAnyKeyword")
+        return "any";
+    if (node.type === "TSUnknownKeyword")
+        return "unknown";
+    if (node.type === "TSNeverKeyword")
+        return "never";
+    if (node.type === "TSTypeReference" && node.typeName?.name) {
+        return node.typeName.name;
+    }
+    return null;
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require explicit type parameters on loop, earlyReturn, and bindInput. Disallow `any` in output positions and `unknown` in input positions.",
+        },
+        messages: {
+            missingTypeParams: "'{{ name }}' requires at least {{ min }} explicit type parameter(s). TypeScript defaults mask type errors (e.g., `any` silently satisfies `never` constraints in loop bodies).",
+            anyInOutput: "Type parameter {{ position }} of '{{ name }}' is an output type — `any` defeats type checking. Use a concrete type or `never` for loop/earlyReturn bodies.",
+            unknownInInput: "Type parameter {{ position }} of '{{ name }}' is an input type — `unknown` is too wide. Use the concrete input type.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                let name;
+                let config;
+                if (node.callee.type === "Identifier") {
+                    name = node.callee.name;
+                    config = STANDALONE_CONFIG.get(name);
+                }
+                else if (node.callee.type === "MemberExpression" &&
+                    node.callee.property.type === "Identifier") {
+                    name = node.callee.property.name;
+                    config = POSTFIX_CONFIG.get(name);
+                }
+                else {
+                    return;
+                }
+                if (!config)
+                    return;
+                // Check for type parameters (TSTypeParameterInstantiation)
+                // typescript-eslint uses "typeArguments" on CallExpression nodes
+                const typeParams = node.typeArguments;
+                if (!typeParams || typeParams.params.length < config.minParams) {
+                    context.report({
+                        node,
+                        messageId: "missingTypeParams",
+                        data: { name, min: String(config.minParams) },
+                    });
+                    return;
+                }
+                // Check each provided type parameter
+                for (let i = 0; i < typeParams.params.length; i++) {
+                    const param = typeParams.params[i];
+                    const position = config.params[i];
+                    if (!position)
+                        break;
+                    const typeName = getTypeName(param);
+                    if (position === "output" && typeName === "any") {
+                        context.report({
+                            node: param,
+                            messageId: "anyInOutput",
+                            data: { name, position: String(i + 1) },
+                        });
+                    }
+                    if (position === "input" && typeName === "unknown") {
+                        context.report({
+                            node: param,
+                            messageId: "unknownInInput",
+                            data: { name, position: String(i + 1) },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@barnum/eslint-plugin",
+  "version": "0.0.0-main-9c142eea",
+  "description": "ESLint rules for Barnum workflows",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "eslint": "^9.27.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.32.1",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/barnum-circus/barnum.git"
+  },
+  "files": [
+    "dist/**/*"
+  ]
+}