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

package/dist/rules/exported-schema-identifier.js

@@ -0,0 +1,117 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf } from "../shared/effect-ast.js";
+// `Schema.Class` and `Schema.TaggedError` carry their name already.
+const anonymousSchemas = new Set(["Struct", "Union", "Array"]);
+const chainedMethod = (node) => node.type === "CallExpression" &&
+    node.callee.type === "MemberExpression" &&
+    !node.callee.computed &&
+    node.callee.property.type === "Identifier"
+    ? { name: node.callee.property.name, receiver: node.callee.object, call: node }
+    : undefined;
+// `X.pipe(Schema.annotate(a))` and `X.annotate(a)`, in any order along the chain.
+const annotationsOf = (init) => {
+    const annotations = [];
+    let current = init;
+    while (calleeOf(current, "Schema") === undefined) {
+        const link = chainedMethod(current);
+        if (link === undefined)
+            return undefined;
+        if (link.name === "annotate")
+            annotations.push(...link.call.arguments);
+        else if (link.name === "pipe") {
+            for (const argument of link.call.arguments) {
+                if (calleeOf(argument, "Schema") === "annotate" &&
+                    argument.type === "CallExpression") {
+                    annotations.push(...argument.arguments);
+                }
+            }
+        }
+        else if (link.name !== "check")
+            return undefined;
+        current = link.receiver;
+    }
+    const root = calleeOf(current, "Schema");
+    return root !== undefined && anonymousSchemas.has(root) ? annotations : undefined;
+};
+const identifierOf = (annotations) => {
+    for (const annotation of annotations) {
+        if (annotation.type !== "ObjectExpression")
+            continue;
+        for (const property of annotation.properties) {
+            if (property.type === "Property" &&
+                !property.computed &&
+                ((property.key.type === "Identifier" && property.key.name === "identifier") ||
+                    (property.key.type === "Literal" && property.key.value === "identifier"))) {
+                return property.value;
+            }
+        }
+    }
+    return undefined;
+};
+export const exportedSchemaIdentifierRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Annotate every exported `Schema.Struct`, `Schema.Union` and `Schema.Array` with an `identifier` equal to its name.",
+        },
+        hasSuggestions: true,
+        messages: {
+            missingIdentifier: 'Annotate `{{name}}` with `identifier: "{{name}}"`, so errors, JSON Schema and arbitraries name it.',
+            wrongIdentifier: 'The `identifier` of `{{name}}` is `{{identifier}}`: use `"{{name}}"`, the name the schema is imported by.',
+            addIdentifier: 'Append `.annotate({ identifier: "{{name}}" })`.',
+            renameIdentifier: 'Use `"{{name}}"` as identifier.',
+        },
+    },
+    createOnce(context) {
+        const check = (declarator) => {
+            const { id, init } = declarator;
+            if (id.type !== "Identifier" || !init)
+                return;
+            const annotations = annotationsOf(init);
+            if (annotations === undefined)
+                return;
+            const name = id.name;
+            const identifier = identifierOf(annotations);
+            if (identifier === undefined) {
+                context.report({
+                    node: id,
+                    messageId: "missingIdentifier",
+                    data: { name },
+                    suggest: [
+                        {
+                            messageId: "addIdentifier",
+                            data: { name },
+                            fix: (fixer) => fixer.insertTextAfter(init, `.annotate({ identifier: "${name}" })`),
+                        },
+                    ],
+                });
+                return;
+            }
+            // A computed identifier cannot be checked without evaluating it.
+            if (identifier.type !== "Literal" || typeof identifier.value !== "string")
+                return;
+            if (identifier.value === name)
+                return;
+            context.report({
+                node: identifier,
+                messageId: "wrongIdentifier",
+                data: { name, identifier: identifier.value },
+                suggest: [
+                    {
+                        messageId: "renameIdentifier",
+                        data: { name },
+                        fix: (fixer) => fixer.replaceText(identifier, `"${name}"`),
+                    },
+                ],
+            });
+        };
+        return {
+            // Internal fragments, reused through `.fields`, never reach an error message alone.
+            ExportNamedDeclaration(node) {
+                if (node.declaration?.type !== "VariableDeclaration")
+                    return;
+                node.declaration.declarations.forEach(check);
+            },
+        };
+    },
+});

package/dist/rules/no-asymmetric-match-handlers.d.ts

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

package/dist/rules/no-asymmetric-match-handlers.js

@@ -0,0 +1,74 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, isEffectFnApplication, isFunctionNode } from "../shared/effect-ast.js";
+import { handlersOf, isMatchCall } from "../shared/match-ast.js";
+const isDelegation = (node) => node?.type === "Identifier" ||
+    node?.type === "MemberExpression" ||
+    node?.type === "CallExpression" ||
+    node?.type === "NewExpression";
+const isEffectBody = (node) => node.type === "CallExpression" &&
+    (isEffectFnApplication(node) || calleeOf(node, "Effect") === "gen") &&
+    node.arguments.some(isFunctionNode);
+const shapeOfResult = (node) => {
+    if (!node)
+        return "value";
+    if (isEffectBody(node))
+        return "inline";
+    return isDelegation(node) ? "delegating" : "value";
+};
+// Literals, templates, arrays and ternaries produce a value rather than implement a step,
+// so they sit on either side of an asymmetry without breaking it.
+const shapeOf = (handler) => {
+    if (!isFunctionNode(handler))
+        return shapeOfResult(handler);
+    if (!handler.body)
+        return "value";
+    if (handler.generator)
+        return "inline";
+    if (handler.body.type !== "BlockStatement")
+        return shapeOfResult(handler.body);
+    const [only, ...rest] = handler.body.body;
+    if (!only)
+        return "value";
+    if (rest.length > 0 || only.type !== "ReturnStatement")
+        return "inline";
+    return shapeOfResult(only.argument);
+};
+const effectFnName = (handler) => {
+    if (handler.type !== "CallExpression" || handler.callee.type !== "CallExpression")
+        return;
+    const [name] = handler.callee.arguments;
+    return name?.type === "Literal" && typeof name.value === "string" ? name.value : undefined;
+};
+export const noAsymmetricMatchHandlersRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Keep the handlers of a match at one level of abstraction: when one delegates to a named function, extract the inline ones too.",
+        },
+        messages: {
+            inlineHandler: "This handler is implemented inline while another branch of the same match delegates to a named function. Extract it into a named function{{hint}} and call it from the handler.",
+        },
+    },
+    createOnce(context) {
+        return {
+            CallExpression(node) {
+                if (!isMatchCall(node))
+                    return;
+                const handlers = handlersOf(node);
+                const shapes = handlers.map(shapeOf);
+                if (!shapes.includes("delegating"))
+                    return;
+                handlers.forEach((handler, index) => {
+                    if (shapes[index] !== "inline")
+                        return;
+                    const name = effectFnName(handler);
+                    context.report({
+                        node: handler,
+                        messageId: "inlineHandler",
+                        data: { hint: name ? ` (\`${name}\`)` : "" },
+                    });
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-bare-error-in-effect.d.ts

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

package/dist/rules/no-bare-error-in-effect.js

@@ -0,0 +1,49 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, isEffectGenerator, nearestFunction } from "../shared/effect-ast.js";
+import { filePatternsSchema } from "../shared/file-globs.js";
+import { isTestFile } from "../shared/test-files.js";
+// Only the two forms the effecttsgo preset misses: `Effect.fail(new Error(…))` and
+// `extends Error` are already reported by global-error-in-effect-failure and extends-native-error.
+export const noBareErrorInEffectRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Fail Effects with tagged errors, never with a `throw` or a primitive value. Primitive failures in test files are allowed.",
+        },
+        messages: {
+            throwInGenerator: "A `throw` inside an Effect generator becomes a defect: `return yield* new TaggedError(...)` instead.",
+            primitiveFailure: "Fail with a tagged error (`Data.TaggedError` or `Schema.TaggedError`), not a primitive value.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { testFiles: filePatternsSchema },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let inTestFile = false;
+        return {
+            // A test's synthetic failure (`Effect.fail("boom")`) feeds code generic over the error,
+            // which never discriminates it; a `throw` is still a defect there.
+            before() {
+                inTestFile = isTestFile(context);
+            },
+            ThrowStatement(node) {
+                const fn = nearestFunction(node);
+                if (fn !== undefined && isEffectGenerator(fn)) {
+                    context.report({ node, messageId: "throwInGenerator" });
+                }
+            },
+            CallExpression(node) {
+                if (inTestFile || calleeOf(node, "Effect") !== "fail")
+                    return;
+                const [failure] = node.arguments;
+                if (failure?.type === "Literal" || failure?.type === "TemplateLiteral") {
+                    context.report({ node: failure, messageId: "primitiveFailure" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-effect-promise.d.ts

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

package/dist/rules/no-effect-promise.js

@@ -0,0 +1,57 @@
+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";
+// Argument index of the release step, where a promise that cannot reject is the normal case.
+const releaseSlots = new Map([
+    ["acquireRelease", 1],
+    ["acquireUseRelease", 2],
+    ["addFinalizer", 0],
+]);
+const isInsideRelease = (node) => {
+    let child = node;
+    for (let current = node.parent; current; current = current.parent) {
+        const slot = releaseSlots.get(calleeOf(current, "Effect") ?? "");
+        if (current.type === "CallExpression" &&
+            slot !== undefined &&
+            current.arguments[slot] === child) {
+            return true;
+        }
+        child = current;
+    }
+    return false;
+};
+export const noEffectPromiseRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Prefer `Effect.tryPromise` over `Effect.promise` outside resource release. Test files are skipped.",
+        },
+        messages: {
+            rejectionAsDefect: "`Effect.promise` turns a rejection into a defect: use `Effect.tryPromise({ try, catch })` unless the promise cannot reject.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { testFiles: filePatternsSchema },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let inTestFile = false;
+        return {
+            // A rejection during test setup is a broken test, and a defect fails it with the cause.
+            before() {
+                inTestFile = isTestFile(context);
+            },
+            CallExpression(node) {
+                if (inTestFile)
+                    return;
+                if (calleeOf(node, "Effect") === "promise" && !isInsideRelease(node)) {
+                    context.report({ node, messageId: "rejectionAsDefect" });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-effect-return-type.d.ts

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

package/dist/rules/no-effect-return-type.js

@@ -0,0 +1,130 @@
+import { defineRule } from "@oxlint/plugins";
+import { nearestFunction } from "../shared/effect-ast.js";
+// `Effect.Effect`, `Stream.Stream`, `Layer.Layer`: the types that carry error and requirement
+// channels collected from everything they call.
+const channelModules = new Set(["Effect", "Stream", "Layer"]);
+const isChannelType = (node) => node.typeName.type === "TSQualifiedName" &&
+    node.typeName.left.type === "Identifier" &&
+    channelModules.has(node.typeName.left.name) &&
+    node.typeName.right.name === node.typeName.left.name;
+const isInside = (node, ancestor) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current === ancestor)
+            return true;
+    }
+    return false;
+};
+const branchesOf = (expression) => expression.type === "ConditionalExpression"
+    ? [...branchesOf(expression.consequent), ...branchesOf(expression.alternate)]
+    : [expression];
+// Without type information, branches built differently (`Effect.succeed` and `Effect.fail`)
+// stand in for an inferred union of effects that the annotation folds into one type.
+const returnsDifferentShapes = (branches, sourceCode) => {
+    const shapeOf = (branch) => branch.type === "CallExpression" || branch.type === "NewExpression"
+        ? `${branch.type} ${sourceCode.getText(branch.callee)}`
+        : branch.type;
+    return new Set(branches.map(shapeOf)).size > 1;
+};
+// TypeScript cannot infer the return type of a function that calls itself: it falls back to
+// `any` and asks for the annotation.
+const isRecursive = (node, sourceCode) => {
+    const declaration = node.type === "FunctionDeclaration" ? node : node.parent;
+    const name = declaration?.type === "FunctionDeclaration"
+        ? declaration.id?.name
+        : declaration?.type === "VariableDeclarator" && declaration.id.type === "Identifier"
+            ? declaration.id.name
+            : undefined;
+    if (declaration === null || name === undefined)
+        return false;
+    // The declared variables of a function declaration include its parameters.
+    return sourceCode
+        .getDeclaredVariables(declaration)
+        .some((variable) => variable.name === name &&
+        variable.references.some((reference) => isInside(reference.identifier, node)));
+};
+// Only the declaration itself: methods of an exported object and functions it returns are not
+// part of the module's signature.
+const isExportedDeclaration = (node) => {
+    const declarator = node.parent;
+    const declaration = declarator?.type === "VariableDeclarator" && declarator.init === node
+        ? declarator.parent
+        : node;
+    const parent = declaration?.parent?.type;
+    return parent === "ExportNamedDeclaration" || parent === "ExportDefaultDeclaration";
+};
+const checksExported = (options) => {
+    const [first] = options;
+    return typeof first === "object" && first !== null && "checkExported" in first
+        ? first.checkExported === true
+        : false;
+};
+export const noEffectReturnTypeRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Let inference type a function returning an Effect: its error and requirement channels change with every callee. Exported declarations are skipped: their annotation is a contract.",
+        },
+        hasSuggestions: true,
+        messages: {
+            effectReturnType: "Remove the return type annotation: error and requirement channels follow the callees, so inference keeps them up to date.",
+            removeReturnType: "Remove the return type annotation.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: { checkExported: { type: "boolean" } },
+                additionalProperties: false,
+            },
+        ],
+    },
+    createOnce(context) {
+        let checkExported = false;
+        const annotated = new Set();
+        const returned = new Map();
+        const collect = (node) => {
+            const fn = nearestFunction(node);
+            if (fn === undefined || node.argument === null)
+                return;
+            returned.set(fn, [...(returned.get(fn) ?? []), node.argument]);
+        };
+        const check = (node) => {
+            const statements = returned.get(node) ?? [];
+            returned.delete(node);
+            if (!annotated.delete(node) || !node.returnType)
+                return;
+            const expressions = node.body?.type === "BlockStatement" ? statements : node.body ? [node.body] : [];
+            if (returnsDifferentShapes(expressions.flatMap(branchesOf), context.sourceCode))
+                return;
+            if (isRecursive(node, context.sourceCode))
+                return;
+            if (!checkExported && isExportedDeclaration(node))
+                return;
+            const { returnType } = node;
+            context.report({
+                node: returnType,
+                messageId: "effectReturnType",
+                suggest: [
+                    {
+                        messageId: "removeReturnType",
+                        fix: (fixer) => fixer.remove(returnType),
+                    },
+                ],
+            });
+        };
+        return {
+            before() {
+                checkExported = checksExported(context.options);
+            },
+            TSTypeReference(node) {
+                const fn = nearestFunction(node);
+                if (fn?.returnType && isChannelType(node) && isInside(node, fn.returnType)) {
+                    annotated.add(fn);
+                }
+            },
+            ReturnStatement: collect,
+            "ArrowFunctionExpression:exit": check,
+            "FunctionDeclaration:exit": check,
+            "FunctionExpression:exit": check,
+        };
+    },
+});

package/dist/rules/no-inline-schema-codec.d.ts

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

package/dist/rules/no-inline-schema-codec.js

@@ -0,0 +1,46 @@
+import { defineRule } from "@oxlint/plugins";
+import { calleeOf, nearestFunction } from "../shared/effect-ast.js";
+// Only the codec factories: `Schema.decode`, `decodeTo`, `encodeKeys`, … build schemas.
+const codecFactory = /^(decode|encode)(Unknown)?(Effect|Exit|Option|Promise|Result|Sync)$/;
+const layerConstructors = new Set(["effect", "scoped"]);
+const isLayerConstructor = (node) => {
+    const name = calleeOf(node, "Layer");
+    return name !== undefined && layerConstructors.has(name);
+};
+// `Layer.effect(T, Effect.gen(…))` and the curried `Layer.effect(T)(Effect.gen(…))`: the
+// generator runs once, when the Layer is built.
+const isLayerConstructionGenerator = (fn) => {
+    const gen = fn.parent;
+    if (!fn.generator || gen?.type !== "CallExpression" || calleeOf(gen, "Effect") !== "gen") {
+        return false;
+    }
+    const layer = gen.parent;
+    if (layer?.type !== "CallExpression" || !layer.arguments.some((arg) => arg === gen)) {
+        return false;
+    }
+    return isLayerConstructor(layer) || isLayerConstructor(layer.callee);
+};
+export const noInlineSchemaCodecRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Extract `Schema.decode*`/`Schema.encode*` codecs into module-level constants instead of applying them inline.",
+        },
+        messages: {
+            inlineCodec: "`Schema.{{factory}}(…)` is built and applied inline: extract it into a named module-level constant.",
+        },
+    },
+    createOnce(context) {
+        return {
+            CallExpression(node) {
+                const factory = calleeOf(node.callee, "Schema");
+                if (factory === undefined || !codecFactory.test(factory))
+                    return;
+                const fn = nearestFunction(node);
+                if (fn === undefined || isLayerConstructionGenerator(fn))
+                    return;
+                context.report({ node: node.callee, messageId: "inlineCodec", data: { factory } });
+            },
+        };
+    },
+});

package/dist/rules/no-inline-yield-star.d.ts

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