@doubleloop-io/oxlint-plugin-effect 0.1.0-rc.0 → 0.1.0-rc.1

package/dist/rules/single-style-per-function.js

@@ -1,20 +1,40 @@
 import { defineRule } from "@oxlint/plugins";
-import { isEffectGenerator, memberOf } from "../shared/effect-ast.js";
+import { isEffectGenerator, isServerComponent, memberOf, } from "../shared/effect-ast.js";
+import { filePatternsSchema } from "../shared/file-globs.js";
+import { isTestFile } from "../shared/test-files.js";
 const isThenCall = (node) => node.callee.type === "MemberExpression" &&
     !node.callee.computed &&
     node.callee.property.type === "Identifier" &&
     node.callee.property.name === "then";
 const testRunners = new Set(["test", "it"]);
-// `test(…)`, `test.only(…)`, `test.each(table)(…)`: the callee chain roots at `test` or `it`.
-const isTestCallback = (fn) => {
+const testHooks = new Set(["beforeAll", "afterAll", "beforeEach", "afterEach"]);
+// `test(…)`, `test.only(…)`, `test.each(table)(…)`: the callee chain roots at the runner or hook.
+const testRoleOf = (fn) => {
     const call = fn.parent;
     if (call?.type !== "CallExpression" || !call.arguments.some((arg) => arg === fn))
-        return false;
+        return undefined;
     let callee = call.callee;
     while (callee.type === "MemberExpression" || callee.type === "CallExpression") {
         callee = callee.type === "MemberExpression" ? callee.object : callee.callee;
     }
-    return callee.type === "Identifier" && testRunners.has(callee.name);
+    if (callee.type !== "Identifier")
+        return undefined;
+    if (testRunners.has(callee.name))
+        return "test";
+    if (testHooks.has(callee.name))
+        return "hook";
+    return undefined;
+};
+// Awaiting promise-based fixtures and then one Effect program reads as Arrange/Act/Assert;
+// a second Effect step is where promise and Effect sequencing start to interleave.
+const interleavesEffectSteps = (frame) => {
+    const effectSteps = frame.promiseSteps.filter((step) => step.involvesEffect);
+    return (effectSteps.length > 1 || effectSteps.some((step) => step.node.type !== "AwaitExpression"));
+};
+const reportFor = {
+    test: "asyncEffectTest",
+    hook: "asyncEffectHook",
+    helper: "asyncEffectHelper",
 };
 export const singleStylePerFunctionRule = defineRule({
     meta: {
@@ -25,31 +45,66 @@ export const singleStylePerFunctionRule = defineRule({
         messages: {
             asyncEffect: "This function builds Effects: drop `async` and lift promises with `Effect.tryPromise({ try, catch })`.",
             promiseStep: "Do not mix promises with Effect in the same function: lift the promise with `Effect.tryPromise({ try, catch })`.",
-            asyncEffectTest: "This test mixes promises with Effect: make its body one Effect, with `it.effect` from `@effect/vitest` or by returning a single test runner call from a non-async callback.",
+            asyncEffectTest: "This test chains promises around Effect: await a single program and assert on its result, or make its body one Effect with `it.effect` from `@effect/vitest`.",
+            asyncEffectHook: "This hook chains promises around Effect: await a single program, lifting the promises into it with `Effect.tryPromise({ try, catch })`, or build the fixture as a Layer with `layer` from `@effect/vitest`.",
+            asyncEffectHelper: "This test helper chains promises around Effect: await a single program, lifting the promises into it with `Effect.tryPromise({ try, catch })`.",
         },
+        schema: [
+            {
+                type: "object",
+                properties: { testFiles: filePatternsSchema },
+                additionalProperties: false,
+            },
+        ],
     },
     createOnce(context) {
         const frames = [];
         const current = () => frames.at(-1);
+        const openSteps = [];
+        let inTestFile = false;
+        // In a test file a helper such as `probe` or `captureLines` is a promise/Effect boundary
+        // like the test that calls it, so it gets the same allowance.
+        const roleOf = (fn) => testRoleOf(fn) ?? (inTestFile && !isEffectGenerator(fn) ? "helper" : undefined);
         const enter = (fn) => {
-            frames.push({ fn, effectful: isEffectGenerator(fn), promiseSteps: [] });
+            frames.push({
+                fn,
+                effectful: isEffectGenerator(fn),
+                rendersJsx: false,
+                promiseSteps: [],
+            });
+        };
+        const openStep = (node) => {
+            const step = { node, involvesEffect: false };
+            current()?.promiseSteps.push(step);
+            openSteps.push(step);
         };
         const exit = () => {
             const frame = frames.pop();
-            if (frame === undefined || !frame.effectful)
+            if (frame === undefined)
                 return;
-            // One report per test: the remedy is the test's shape, not each promise in it.
-            if (isTestCallback(frame.fn)) {
-                if (frame.fn.async || frame.promiseSteps.length > 0)
-                    context.report({ node: frame.fn, messageId: "asyncEffectTest" });
+            // One report per test or hook: the remedy is its shape, not each promise in it.
+            const role = roleOf(frame.fn);
+            if (role !== undefined) {
+                if (interleavesEffectSteps(frame))
+                    context.report({ node: frame.fn, messageId: reportFor[role] });
                 return;
             }
+            if (!frame.effectful || isServerComponent(frame.fn, frame.rendersJsx))
+                return;
             if (frame.fn.async)
                 context.report({ node: frame.fn, messageId: "asyncEffect" });
-            for (const node of frame.promiseSteps)
-                context.report({ node, messageId: "promiseStep" });
+            for (const step of frame.promiseSteps)
+                context.report({ node: step.node, messageId: "promiseStep" });
+        };
+        const markJsx = () => {
+            const frame = current();
+            if (frame !== undefined)
+                frame.rendersJsx = true;
         };
         return {
+            before() {
+                inTestFile = isTestFile(context);
+            },
             ArrowFunctionExpression: enter,
             FunctionExpression: enter,
             FunctionDeclaration: enter,
@@ -57,20 +112,33 @@ export const singleStylePerFunctionRule = defineRule({
             "FunctionExpression:exit": exit,
             "FunctionDeclaration:exit": exit,
             MemberExpression(node) {
-                const frame = current();
                 const name = memberOf(node, "Effect");
+                if (name === undefined)
+                    return;
+                // A step involves Effect wherever it appears in it, nested callbacks included.
+                for (const step of openSteps)
+                    step.involvesEffect = true;
+                const frame = current();
+                if (frame === undefined)
+                    return;
                 // `Effect.run*` is how an async boundary legitimately hands off to Effect (P27);
-                // where it may appear is run-only-at-entry's business.
-                if (frame !== undefined && name !== undefined && !name.startsWith("run")) {
+                // where it may appear is run-only-in-runner's business.
+                if (!name.startsWith("run"))
                     frame.effectful = true;
-                }
             },
-            AwaitExpression(node) {
-                current()?.promiseSteps.push(node);
+            JSXElement: markJsx,
+            JSXFragment: markJsx,
+            AwaitExpression: openStep,
+            "AwaitExpression:exit"() {
+                openSteps.pop();
             },
             CallExpression(node) {
                 if (isThenCall(node))
-                    current()?.promiseSteps.push(node);
+                    openStep(node);
+            },
+            "CallExpression:exit"(node) {
+                if (isThenCall(node))
+                    openSteps.pop();
             },
         };
     },

package/dist/shared/effect-ast.d.ts

@@ -7,3 +7,4 @@ export declare const isEffectFnApplication: (node: ESTree.Node | null | undefine
 export declare const isEffectGenerator: (fn: FunctionNode) => boolean;
 export declare const isInsideEffectGeneratorBody: (node: ESTree.Node) => boolean;
 export declare const nearestFunction: (node: ESTree.Node) => FunctionNode | undefined;
+export declare const isServerComponent: (fn: FunctionNode, rendersJsx: boolean) => boolean;

package/dist/shared/effect-ast.js

@@ -28,8 +28,12 @@ export const isEffectGenerator = (fn) => {
         return call.arguments.some((arg) => arg === fn);
     return isEffectFnApplication(call) && call.arguments[0] === fn;
 };
-// Plain callbacks inside the generator still belong to its success path; the pipeable
-// arguments of an `Effect.fn` nested in it are the handler slot, so they do not.
+const isEffectCombinatorCallback = (fn) => fn.parent?.type === "CallExpression" &&
+    memberOf(fn.parent.callee, "Effect") !== undefined &&
+    fn.parent.arguments.some((arg) => arg === fn);
+// Callbacks handed to an `Effect.*` combinator inside the generator still belong to its success
+// path; the pipeable arguments of an `Effect.fn` nested in it are the handler slot, so they do
+// not, and neither does a function the generator only defines (an HTTP handler, a service method).
 export const isInsideEffectGeneratorBody = (node) => {
     let child = node;
     for (let current = node.parent; current; current = current.parent) {
@@ -37,8 +41,12 @@ export const isInsideEffectGeneratorBody = (node) => {
             current.arguments.findIndex((arg) => arg === child) > 0) {
             return false;
         }
-        if (isFunctionNode(current) && current.generator)
-            return isEffectGenerator(current);
+        if (isFunctionNode(current)) {
+            if (current.generator)
+                return isEffectGenerator(current);
+            if (!isEffectCombinatorCallback(current))
+                return false;
+        }
         child = current;
     }
     return false;
@@ -50,3 +58,6 @@ export const nearestFunction = (node) => {
     }
     return undefined;
 };
+// An async function that renders JSX is a React Server Component: it hands its outcome to React,
+// and how failures become UI is the application's call, not a rule's.
+export const isServerComponent = (fn, rendersJsx) => fn.async && rendersJsx;

package/dist/shared/effect-runners.d.ts

@@ -0,0 +1,2 @@
+import type { ESTree } from "@oxlint/plugins";
+export declare const runnerName: (node: ESTree.MemberExpression) => string | undefined;

package/dist/shared/effect-runners.js

@@ -0,0 +1,14 @@
+import { memberOf } from "./effect-ast.js";
+const runtimeEntries = [
+    ["NodeRuntime", "runMain"],
+    ["BunRuntime", "runMain"],
+    ["ManagedRuntime", "make"],
+];
+// The qualified name of the runner `node` refers to, when it runs an Effect program.
+export const runnerName = (node) => {
+    const effectMember = memberOf(node, "Effect");
+    if (effectMember?.startsWith("run"))
+        return `Effect.${effectMember}`;
+    const entry = runtimeEntries.find(([object, property]) => memberOf(node, object) === property);
+    return entry === undefined ? undefined : `${entry[0]}.${entry[1]}`;
+};

package/dist/shared/entry-files.d.ts

@@ -1,4 +1,4 @@
-export declare const defaultEntryFiles: string[];
+export declare const defaultEntryFiles: readonly ["**/main.ts", "**/cli.ts", "**/bin/**"];
 export declare const isEntryFile: (context: {
     readonly filename: string;
     readonly cwd: string;

package/dist/shared/test-files.d.ts

@@ -1,4 +1,4 @@
-export declare const defaultTestFiles: string[];
+export declare const defaultTestFiles: readonly ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/test/**", "**/tests/**"];
 export declare const isTestFile: (context: {
     readonly filename: string;
     readonly cwd: string;

package/package.json

@@ -1,57 +1,63 @@
 {
-    "name": "@doubleloop-io/oxlint-plugin-effect",
-    "version": "0.1.0-rc.0",
-    "description": "Oxlint rules for Effect 4 code",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/doubleloop-io/oxlint-plugin-effect.git"
-    },
-    "files": [
-        "dist/",
-        "RULES.md",
-        "README.md",
-        "LICENSE",
-        "LICENSE.anti-slop"
-    ],
-    "type": "module",
-    "exports": {
-        "./presets/all": {
-            "types": "./dist/presets/all.d.ts",
-            "default": "./dist/presets/all.js"
-        },
-        "./presets/all.json": "./dist/presets/all.json"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "scripts": {
-        "format": "oxfmt",
-        "format:check": "oxfmt --check",
-        "typecheck": "tsc --noEmit",
-        "lint": "oxlint --deny-warnings",
-        "test": "node --test install-skill.test.ts rules-md.test.ts rules/*.test.ts",
-        "check": "pnpm format:check && pnpm typecheck && pnpm lint && pnpm test",
-        "build": "rm -rf dist && tsc -p tsconfig.build.json && node presets/all-json.ts",
-        "pack:check": "node --test presets/all-dist.test.ts && node scripts/pack-check.ts",
-        "build-and-pack": "pnpm check && pnpm build && pnpm pack:check && pnpm smoke-test",
-        "smoke-test": "node scripts/smoke-test.ts"
-    },
-    "dependencies": {
-        "@oxlint/plugins": "^1.82.0"
-    },
-    "devDependencies": {
-        "@types/node": "^24.13.6",
-        "oxfmt": "0.67.0",
-        "oxlint": "1.82.0",
-        "publint": "^0.3.25",
-        "typescript": "^7.0.2"
-    },
-    "peerDependencies": {
-        "oxlint": "^1.82.0"
-    },
-    "engines": {
-        "node": "^22.20.0 || >=24.8.0"
-    },
-    "packageManager": "pnpm@12.4.1"
-}
+  "name": "@doubleloop-io/oxlint-plugin-effect",
+  "version": "0.1.0-rc.1",
+  "description": "Oxlint rules for Effect 4 code",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doubleloop-io/oxlint-plugin-effect.git"
+  },
+  "files": [
+    "dist/",
+    "RULES.md",
+    "README.md",
+    "LICENSE",
+    "LICENSE.anti-slop"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./presets/all": {
+      "types": "./dist/presets/all.d.ts",
+      "default": "./dist/presets/all.js"
+    },
+    "./presets/all.json": "./dist/presets/all.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oxlint/plugins": "^1.82.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.6",
+    "oxfmt": "0.67.0",
+    "oxlint": "1.82.0",
+    "publint": "^0.3.25",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "oxlint": "^1.82.0"
+  },
+  "engines": {
+    "node": "^22.20.0 || >=24.8.0"
+  },
+  "scripts": {
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings",
+    "test": "node --test install-skill.test.ts link-consumer.test.ts rules-md.test.ts rules/*.test.ts",
+    "check": "pnpm format:check && pnpm typecheck && pnpm lint && pnpm test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node presets/all-json.ts",
+    "build:w": "node --watch-path=index.ts --watch-path=rules --watch-path=presets --watch-path=shared --watch-path=tsconfig.build.json scripts/build.ts",
+    "pack:check": "node --test presets/all-dist.test.ts && node scripts/pack-check.ts",
+    "build-and-pack": "pnpm check && pnpm build && pnpm pack:check && pnpm smoke-test",
+    "smoke-test": "node scripts/smoke-test.ts",
+    "consumer:link": "./link-consumer.sh link",
+    "consumer:unlink": "./link-consumer.sh unlink"
+  }
+}

package/dist/rules/boundary-entrypoint-shape.d.ts

@@ -1 +0,0 @@
-export declare const boundaryEntrypointShapeRule: import("@oxlint/plugins").Rule;

package/dist/rules/boundary-entrypoint-shape.js

@@ -1,52 +0,0 @@
-import { defineRule } from "@oxlint/plugins";
-import { calleeOf, nearestFunction } from "../shared/effect-ast.js";
-// The *Exit runners hand failures back as values, so an open error channel cannot leak there.
-const effectRunners = new Set(["runPromise", "runSync", "runFork", "runCallback"]);
-const runtimes = ["NodeRuntime", "BunRuntime"];
-const isRunnerCall = (node) => effectRunners.has(calleeOf(node, "Effect") ?? "") ||
-    runtimes.some((runtime) => calleeOf(node, runtime) === "runMain");
-const isEffectTypeName = (name) => (name.type === "Identifier" && name.name === "Effect") ||
-    (name.type === "TSQualifiedName" &&
-        name.left.type === "Identifier" &&
-        name.left.name === "Effect" &&
-        name.right.name === "Effect");
-const isClosedEffectType = (type) => type?.type === "TSTypeReference" &&
-    isEffectTypeName(type.typeName) &&
-    type.typeArguments?.params[1]?.type === "TSNeverKeyword";
-const parameterType = (identifier) => {
-    for (let fn = nearestFunction(identifier); fn; fn = nearestFunction(fn)) {
-        for (const param of fn.params) {
-            if (param.type === "Identifier" && param.name === identifier.name) {
-                return param.typeAnnotation?.typeAnnotation;
-            }
-        }
-    }
-    return undefined;
-};
-const hasClosedErrorChannel = (node) => {
-    if (node?.type === "TSSatisfiesExpression")
-        return isClosedEffectType(node.typeAnnotation);
-    if (node?.type === "Identifier")
-        return isClosedEffectType(parameterType(node));
-    return false;
-};
-export const boundaryEntrypointShapeRule = defineRule({
-    meta: {
-        type: "problem",
-        docs: {
-            description: "Close the error channel to `never` before running an Effect at the boundary.",
-        },
-        messages: {
-            openErrorChannel: "Close the error channel before running: `program satisfies Effect.Effect<A, never>`, or a runner parameter typed `Effect.Effect<A, never, never>`.",
-        },
-    },
-    createOnce(context) {
-        return {
-            CallExpression(node) {
-                if (isRunnerCall(node) && !hasClosedErrorChannel(node.arguments[0])) {
-                    context.report({ node, messageId: "openErrorChannel" });
-                }
-            },
-        };
-    },
-});

package/dist/rules/run-only-at-entry.d.ts

@@ -1 +0,0 @@
-export declare const runOnlyAtEntryRule: import("@oxlint/plugins").Rule;