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

package/dist/rules/no-manual-discriminant-construction.js

@@ -0,0 +1,90 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf } from "../shared/effect-ast.js";
+import { configuredDiscriminants, discriminantsSchema, isStringLiteral, propertyName, } from "../shared/tagged-values.js";
+export const remedyFor = (discriminant) => discriminant === "_tag"
+    ? "the Schema's tagged `.make`, the tagged class or error constructor, or the `Data.taggedEnum` variant constructor"
+    : "the Schema's `.make` or the class constructor";
+const isMatchPatternCall = (call) => {
+    const method = calleeOf(call, "Match");
+    return method === "when" || method === "not";
+};
+// `match(value).with(pattern, handler)`, also after earlier `.with`/`.when` links of the chain.
+const isTsPatternWithCall = (call) => {
+    if (call.callee.type !== "MemberExpression" ||
+        call.callee.computed ||
+        call.callee.property.type !== "Identifier" ||
+        call.callee.property.name !== "with") {
+        return false;
+    }
+    let link = call.callee.object;
+    while (link.type === "CallExpression" && link.callee.type === "MemberExpression") {
+        link = link.callee.object;
+    }
+    return (link.type === "CallExpression" &&
+        link.callee.type === "Identifier" &&
+        link.callee.name === "match");
+};
+// `Schema.decodeUnknownSync(X)(input)`: the literal is raw data to validate, not a value of X.
+const isSchemaCodecApplication = (call) => {
+    const method = calleeOf(call.callee, "Schema");
+    return method !== undefined && (method.startsWith("decode") || method.startsWith("encode"));
+};
+// A literal nested in a pattern or in a codec input belongs to it as much as the outermost one.
+const isPatternOrCodecInput = (node) => {
+    let child = node;
+    let current = node.parent;
+    while (current?.type === "Property" ||
+        current?.type === "ObjectExpression" ||
+        current?.type === "ArrayExpression") {
+        child = current;
+        current = current.parent;
+    }
+    return (current?.type === "CallExpression" &&
+        current.arguments.some((argument) => argument === child) &&
+        (isMatchPatternCall(current) ||
+            isTsPatternWithCall(current) ||
+            isSchemaCodecApplication(current)));
+};
+export const noManualDiscriminantConstructionRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Construct a union's variants with their constructor, not as object literals with the discriminant.",
+        },
+        messages: {
+            manualConstruction: "An object literal with a literal `{{discriminant}}` skips the variant's constructor: use {{remedy}}.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { discriminants: discriminantsSchema },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let discriminants = new Set();
+        return {
+            before() {
+                discriminants = configuredDiscriminants(context.options);
+            },
+            ObjectExpression(node) {
+                for (const property of node.properties) {
+                    if (property.type !== "Property" || !isStringLiteral(property.value))
+                        continue;
+                    const discriminant = propertyName(property);
+                    if (discriminant === undefined || !discriminants.has(discriminant))
+                        continue;
+                    if (isPatternOrCodecInput(node))
+                        return;
+                    context.report({
+                        node: property,
+                        messageId: "manualConstruction",
+                        data: { discriminant, remedy: remedyFor(discriminant) },
+                    });
+                    return;
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-nested-match.d.ts

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

package/dist/rules/no-nested-match.js

@@ -0,0 +1,24 @@
+import { defineRule } from "@oxlint/plugins";
+import { handlersOf, isMatchCall, nestedBranches } from "../shared/match-ast.js";
+export const noNestedMatchRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Flatten a match whose handler branches again: a guard clause inside generators, a named handler outside.",
+        },
+        messages: {
+            nestedBranch: "This handler branches again inside a match. Inside a generator, return early on the exit case (`if (Result.isFailure(parsed)) return yield* ...`); outside, name the inner choice and pass it as the handler.",
+        },
+    },
+    createOnce(context) {
+        return {
+            CallExpression(node) {
+                if (!isMatchCall(node))
+                    return;
+                for (const branch of handlersOf(node).flatMap(nestedBranches)) {
+                    context.report({ node: branch, messageId: "nestedBranch" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-parameterless-catch-all.d.ts

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

package/dist/rules/no-parameterless-catch-all.js

@@ -0,0 +1,29 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf } from "../shared/effect-ast.js";
+const catchAlls = new Set(["catch", "catchAll", "catchCause", "catchEager"]);
+export const noParameterlessCatchAllRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid catch-all handlers that ignore the error they catch.",
+        },
+        messages: {
+            swallowed: "`Effect.{{name}}` ignores what it catches, so it also swallows failures added later: use `Effect.catchTag`, or `Effect.orElseSucceed`/`Effect.orElse` when every failure truly means the same fallback.",
+        },
+    },
+    createOnce(context) {
+        return {
+            CallExpression(node) {
+                const name = calleeOf(node, "Effect");
+                if (name === undefined || !catchAlls.has(name))
+                    return;
+                const handler = node.arguments.at(-1);
+                if ((handler?.type === "ArrowFunctionExpression" ||
+                    handler?.type === "FunctionExpression") &&
+                    handler.params.length === 0) {
+                    context.report({ node: handler, messageId: "swallowed", data: { name } });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-provide-on-definition.d.ts

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

package/dist/rules/no-provide-on-definition.js

@@ -0,0 +1,94 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, isEffectFnApplication } from "../shared/effect-ast.js";
+import { filePatternsSchema } from "../shared/file-globs.js";
+import { isTestFile } from "../shared/test-files.js";
+const pipeReceiver = (call) => {
+    const { callee } = call;
+    return callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === "pipe"
+        ? callee.object
+        : undefined;
+};
+const isProgramDefinition = (node) => {
+    if (node?.type !== "CallExpression")
+        return false;
+    if (calleeOf(node, "Effect") === "gen" || isEffectFnApplication(node))
+        return true;
+    return isProgramDefinition(pipeReceiver(node));
+};
+const isContextCapture = (init) => {
+    if (init?.type !== "YieldExpression" || !init.delegate)
+        return false;
+    let source = init.argument;
+    while (source?.type === "CallExpression" && pipeReceiver(source))
+        source = pipeReceiver(source);
+    return calleeOf(source, "Effect") === "context";
+};
+const isCapturedContext = (value) => {
+    if (value?.type !== "Identifier")
+        return false;
+    for (let current = value.parent; current; current = current.parent) {
+        if (current.type !== "BlockStatement")
+            continue;
+        const captured = current.body.some((statement) => statement.type === "VariableDeclaration" &&
+            statement.kind === "const" &&
+            statement.declarations.some((declarator) => declarator.id.type === "Identifier" &&
+                declarator.id.name === value.name &&
+                isContextCapture(declarator.init)));
+        if (captured)
+            return true;
+    }
+    return false;
+};
+const providedValue = (provide) => provide.arguments[provide.arguments.length > 1 ? 1 : 0];
+const providedDefinition = (provide) => {
+    if (provide.arguments.length > 1)
+        return isProgramDefinition(provide.arguments[0]);
+    const parent = provide.parent;
+    if (parent?.type !== "CallExpression")
+        return false;
+    // `Effect.fn("name")(body, Effect.provide(layer))`: the pipeable slot belongs to the definition.
+    if (isEffectFnApplication(parent) && parent.arguments.indexOf(provide) > 0)
+        return true;
+    return parent.arguments.includes(provide) && isProgramDefinition(pipeReceiver(parent));
+};
+// A program that provides its own layers can no longer be wired differently by its caller:
+// the dispatch that picks the adapters is where `Effect.provide` belongs.
+export const noProvideOnDefinitionRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Keep `Effect.provide` off `Effect.gen`/`Effect.fn` definitions; provide where the program is dispatched. Test files are skipped.",
+        },
+        messages: {
+            provideOnDefinition: "Define the program without layers and apply `Effect.provide` where it is dispatched, to a named program.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { testFiles: filePatternsSchema },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let inTestFile = false;
+        return {
+            // `it.effect(…, () => Effect.gen(…).pipe(Effect.provide(fakes)))` is the idiomatic test.
+            before() {
+                inTestFile = isTestFile(context);
+            },
+            CallExpression(node) {
+                if (inTestFile || calleeOf(node, "Effect") !== "provide")
+                    return;
+                // A Layer that captures its context with `Effect.context()` hands it back to each
+                // method: the caller already chose the adapters when it built the Layer.
+                if (providedDefinition(node) && !isCapturedContext(providedValue(node))) {
+                    context.report({ node, messageId: "provideOnDefinition" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-transport-types-in-generator.d.ts

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

package/dist/rules/no-transport-types-in-generator.js

@@ -0,0 +1,63 @@
+import { defineRule } from "@oxlint/plugins";
+import { isInsideEffectGeneratorBody } from "../shared/effect-ast.js";
+const defaultTransportTypes = ["Response", "NextResponse"];
+const configuredTransportTypes = (options) => {
+    const [first] = options;
+    if (typeof first !== "object" || first === null || !("transportTypes" in first)) {
+        return new Set(defaultTransportTypes);
+    }
+    const types = first.transportTypes;
+    return new Set(Array.isArray(types) ? types.filter((type) => typeof type === "string") : []);
+};
+// `new Response(…)`, `Response.json(…)` and a plain factory call `toDto(…)` all build one.
+const constructedTypeName = (node) => {
+    const callee = node.callee;
+    if (callee.type === "Identifier")
+        return callee.name;
+    if (node.type === "CallExpression" &&
+        callee.type === "MemberExpression" &&
+        callee.object.type === "Identifier") {
+        return callee.object.name;
+    }
+    return undefined;
+};
+export const noTransportTypesInGeneratorRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Return domain values from Effect generators and convert them to transport types in the second argument of `Effect.fn`.",
+        },
+        messages: {
+            transportInGenerator: "Do not build `{{name}}` inside the generator: return a domain value and convert it with `Effect.map`/`Effect.catchTags` in the pipeable arguments of `Effect.fn`.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    transportTypes: { type: "array", items: { type: "string" }, uniqueItems: true },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let transportTypes = new Set();
+        const check = (node) => {
+            const name = constructedTypeName(node);
+            if (name === undefined ||
+                !transportTypes.has(name) ||
+                !isInsideEffectGeneratorBody(node)) {
+                return;
+            }
+            context.report({ node, messageId: "transportInGenerator", data: { name } });
+        };
+        return {
+            // Options are per file, so they can only be read once a file starts.
+            before() {
+                transportTypes = configuredTransportTypes(context.options);
+            },
+            NewExpression: check,
+            CallExpression: check,
+        };
+    },
+});

package/dist/rules/no-yielded-match.d.ts

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

package/dist/rules/no-yielded-match.js

@@ -0,0 +1,91 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, isEffectGenerator, isFunctionNode, memberOf, nearestFunction, } from "../shared/effect-ast.js";
+import { handlersOf, nestedBranches } from "../shared/match-ast.js";
+const guards = { Option: "Option.isNone", Result: "Result.isFailure" };
+const matchedModule = (node) => {
+    if (node?.type !== "CallExpression")
+        return undefined;
+    if (memberOf(node.callee, "Option") === "match")
+        return "Option";
+    if (memberOf(node.callee, "Result") === "match")
+        return "Result";
+    return undefined;
+};
+const isPipe = (callee) => (callee.type === "Identifier" && callee.name === "pipe") ||
+    (callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === "pipe");
+// Data-first `Option.match(x, {…})`, or a match as the last step of `x.pipe(…)`/`pipe(x, …)`.
+const yieldedMatch = (node) => {
+    if (node?.type !== "CallExpression")
+        return undefined;
+    if (matchedModule(node) !== undefined && node.arguments.length === 2)
+        return node;
+    if (!isPipe(node.callee))
+        return undefined;
+    const last = node.arguments.at(-1);
+    return matchedModule(last) !== undefined && last?.type === "CallExpression" ? last : undefined;
+};
+const handlerNamed = (match, name) => {
+    for (const argument of match.arguments) {
+        if (argument.type !== "ObjectExpression")
+            continue;
+        for (const property of argument.properties) {
+            if (property.type === "Property" &&
+                !property.computed &&
+                property.key.type === "Identifier" &&
+                property.key.name === name) {
+                return property.value;
+            }
+        }
+    }
+    return undefined;
+};
+// `onSome: Effect.succeed` or `onSome: (x) => Effect.succeed(x)`.
+const resultsIn = (handler, constructor) => {
+    if (memberOf(handler, "Effect") === constructor)
+        return true;
+    return (isFunctionNode(handler) &&
+        handler.body?.type !== "BlockStatement" &&
+        calleeOf(handler.body, "Effect") === constructor);
+};
+// `option-match-to-from-option` (effecttsgo) proposes `Effect.fromOption` for this shape.
+const isFromOptionShape = (match) => matchedModule(match) === "Option" &&
+    resultsIn(handlerNamed(match, "onNone"), "fail") &&
+    resultsIn(handlerNamed(match, "onSome"), "succeed");
+export const noYieldedMatchRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Inside an Effect generator, return early on the empty or failed case instead of yielding an `Option.match`/`Result.match`.",
+        },
+        messages: {
+            yieldedMatch: "This `yield*` of a `{{module}}.match` splits the generator into two branches: return early with `if ({{guard}}(…)) return …` and keep one main path.",
+        },
+    },
+    createOnce(context) {
+        return {
+            YieldExpression(node) {
+                if (!node.delegate)
+                    return;
+                const match = yieldedMatch(node.argument);
+                const module = matchedModule(match);
+                if (match === undefined || module === undefined)
+                    return;
+                const generator = nearestFunction(node);
+                if (generator === undefined || !isEffectGenerator(generator))
+                    return;
+                if (isFromOptionShape(match))
+                    return;
+                if (handlersOf(match).some((handler) => nestedBranches(handler).length > 0))
+                    return;
+                context.report({
+                    node: match,
+                    messageId: "yieldedMatch",
+                    data: { module, guard: guards[module] },
+                });
+            },
+        };
+    },
+});

package/dist/rules/prefer-effect-fn.d.ts

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

package/dist/rules/prefer-effect-fn.js

@@ -0,0 +1,102 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, isEffectFnApplication, isFunctionNode, memberOf, } from "../shared/effect-ast.js";
+const isEffectGenChain = (node) => {
+    if (node?.type !== "CallExpression")
+        return false;
+    if (calleeOf(node, "Effect") === "gen")
+        return true;
+    const callee = node.callee;
+    return (callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === "pipe" &&
+        isEffectGenChain(callee.object));
+};
+const returnedExpression = (fn) => {
+    if (fn.body?.type !== "BlockStatement")
+        return fn.body;
+    const statements = fn.body.body;
+    const [only] = statements;
+    return statements.length === 1 && only?.type === "ReturnStatement" ? only.argument : undefined;
+};
+// Callbacks such as `it.effect("…", () => Effect.gen(…))` are not named functions: only
+// declarations, variables and object members get a span name worth having.
+const isNamedFunction = (fn) => {
+    const parent = fn.parent;
+    return (fn.type === "FunctionDeclaration" ||
+        (parent?.type === "VariableDeclarator" && parent.init === fn) ||
+        ((parent?.type === "Property" || parent?.type === "PropertyDefinition") &&
+            parent.value === fn));
+};
+const isPipeCall = (node) => node.callee.type === "MemberExpression" &&
+    !node.callee.computed &&
+    node.callee.property.type === "Identifier" &&
+    node.callee.property.name === "pipe";
+// A value keeps its span through `Effect.withSpan`: `Effect.fn` would add only a call-site frame
+// that always points at the same line.
+const hasSpan = (node) => node?.type === "CallExpression" &&
+    isPipeCall(node) &&
+    node.callee.type === "MemberExpression" &&
+    (node.arguments.some((argument) => calleeOf(argument, "Effect") === "withSpan") ||
+        hasSpan(node.callee.object));
+const isUntracedValue = (node) => isEffectGenChain(node) && !hasSpan(node);
+export const preferEffectFnRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Write effectful functions with a named `Effect.fn` instead of returning `Effect.gen`.",
+        },
+        messages: {
+            useEffectFn: 'Use `Effect.fn("name")(function* (...) {...})` instead of a function that returns `Effect.gen`.',
+            missingName: 'Give `Effect.fn` a span name: `Effect.fn("name")(function* (...) {...})`.',
+            useEffectFnForValue: 'Give `{{name}}` a span: declare it as `Effect.fn("{{name}}")(function* () {...})` and call it, or append `.pipe(Effect.withSpan("{{name}}"))`.',
+            pipeOnEffectFn: "Pass combinators as extra arguments of `Effect.fn(...)(body, ...)` instead of calling `.pipe` on it.",
+        },
+    },
+    createOnce(context) {
+        const checkFunction = (fn) => {
+            if (fn.generator || !isNamedFunction(fn))
+                return;
+            if (isEffectGenChain(returnedExpression(fn))) {
+                context.report({ node: fn, messageId: "useEffectFn" });
+            }
+        };
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type === "Identifier" && isUntracedValue(node.init)) {
+                    context.report({
+                        node,
+                        messageId: "useEffectFnForValue",
+                        data: { name: node.id.name },
+                    });
+                }
+            },
+            Property(node) {
+                if (node.key.type === "Identifier" && isUntracedValue(node.value)) {
+                    context.report({
+                        node,
+                        messageId: "useEffectFnForValue",
+                        data: { name: node.key.name },
+                    });
+                }
+            },
+            ArrowFunctionExpression: checkFunction,
+            FunctionExpression: checkFunction,
+            FunctionDeclaration: checkFunction,
+            CallExpression(node) {
+                if (memberOf(node.callee, "Effect") === "fn" && isFunctionNode(node.arguments[0])) {
+                    context.report({ node, messageId: "missingName" });
+                }
+                const callee = node.callee;
+                if (callee.type === "MemberExpression" &&
+                    !callee.computed &&
+                    callee.property.type === "Identifier" &&
+                    callee.property.name === "pipe" &&
+                    isEffectFnApplication(callee.object) &&
+                    isFunctionNode(callee.object.arguments[0])) {
+                    context.report({ node, messageId: "pipeOnEffectFn" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/provide-named-layer.d.ts

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

package/dist/rules/provide-named-layer.js

@@ -0,0 +1,55 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf } from "../shared/effect-ast.js";
+import { filePatternsSchema } from "../shared/file-globs.js";
+import { isTestFile } from "../shared/test-files.js";
+const matchers = new Set(["match", "$match"]);
+// Factories and module members (`planLayer(csv)`, `CsvSheetReader.layer(path)`) are names;
+// only composition written in the argument itself is reported.
+const isInlineComposition = (layer) => {
+    if (layer?.type === "ConditionalExpression" || layer?.type === "LogicalExpression")
+        return true;
+    if (layer?.type !== "CallExpression" || layer.callee.type !== "MemberExpression")
+        return false;
+    const { callee } = layer;
+    if (callee.object.type === "Identifier" && callee.object.name === "Layer")
+        return true;
+    return (!callee.computed &&
+        callee.property.type === "Identifier" &&
+        matchers.has(callee.property.name));
+};
+export const provideNamedLayerRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Provide named layers instead of composing them inside `Effect.provide`. Test files are skipped.",
+        },
+        messages: {
+            inlineLayer: "Name the layer passed to `Effect.provide` (`const appLayer = Layer.mergeAll(...)`) instead of composing it inline.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { testFiles: filePatternsSchema },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let inTestFile = false;
+        return {
+            // Tests build per-test fakes inline, which is the idiomatic form there.
+            before() {
+                inTestFile = isTestFile(context);
+            },
+            CallExpression(node) {
+                if (inTestFile || calleeOf(node, "Effect") !== "provide")
+                    return;
+                // Data-first `Effect.provide(effect, layer)` and data-last `Effect.provide(layer)`.
+                const layer = node.arguments.at(-1);
+                if (isInlineComposition(layer)) {
+                    context.report({ node: layer, messageId: "inlineLayer" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/redacted-secret-names.d.ts

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