Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { defineRule } from '@oxlint/plugins'; |
| 2 | |
| 3 | import type { ESTree, SourceCode } from '@oxlint/plugins'; |
| 4 | |
| 5 | import { |
| 6 | collectEffectModuleNames, |
| 7 | genFunction, |
| 8 | isFunction, |
| 9 | keyName, |
| 10 | moduleCallName, |
| 11 | moduleMemberName, |
| 12 | precedingSteps, |
| 13 | returnedExpressions, |
| 14 | unwrapNode, |
| 15 | walk, |
| 16 | type EffectModuleNames, |
| 17 | type FunctionNode, |
| 18 | } from '../shared/effect-modules.ts'; |
| 19 | |
| 20 | const narrowingOperators: ReadonlySet<string> = new Set([ |
| 21 | 'mapError', |
| 22 | 'catch', |
| 23 | 'catchAll', |
| 24 | 'catchCause', |
| 25 | 'orElse', |
| 26 | ]); |
| 27 | const tapOperators: ReadonlySet<string> = new Set([ |
| 28 | 'tapError', |
| 29 | 'tapErrorCause', |
| 30 | 'tapCause', |
| 31 | 'tapErrorTag', |
| 32 | ]); |
| 33 | const effectModuleNamesList: readonly ('Context' | 'Effect' | 'Layer' | 'ManagedRuntime')[] = [ |
| 34 | 'Context', |
| 35 | 'Effect', |
| 36 | 'Layer', |
| 37 | 'ManagedRuntime', |
| 38 | ]; |
| 39 | |
| 40 | /** Whether the handler never reads the error it receives. */ |
| 41 | function ignoresError(handler: FunctionNode, sourceCode: SourceCode): boolean { |
| 42 | const [parameter] = handler.params; |
| 43 | if (parameter === undefined) return true; |
| 44 | if (parameter.type !== 'Identifier') return false; |
| 45 | const variable = sourceCode |
| 46 | .getDeclaredVariables(handler) |
| 47 | .find(candidate => candidate.identifiers.some(identifier => identifier === parameter)); |
| 48 | return variable !== undefined && variable.references.length === 0; |
| 49 | } |
| 50 | |
| 51 | /** `new X(...)` or `X.make(...)` for a capitalized `X` that is not an Effect module. */ |
| 52 | function isErrorConstruction( |
| 53 | node: ESTree.Node, |
| 54 | names: EffectModuleNames |
| 55 | ): node is ESTree.NewExpression | ESTree.CallExpression { |
| 56 | if (node.type === 'NewExpression') |
| 57 | return ( |
| 58 | unwrapNode(node.callee).type === 'Identifier' || |
| 59 | unwrapNode(node.callee).type === 'MemberExpression' |
| 60 | ); |
| 61 | if (node.type !== 'CallExpression') return false; |
| 62 | const callee = unwrapNode(node.callee); |
| 63 | if ( |
| 64 | callee.type !== 'MemberExpression' || |
| 65 | callee.computed || |
| 66 | callee.property.type !== 'Identifier' || |
| 67 | callee.property.name !== 'make' |
| 68 | ) { |
| 69 | return false; |
| 70 | } |
| 71 | const owner = unwrapNode(callee.object); |
| 72 | const ownerName = |
| 73 | owner.type === 'Identifier' |
| 74 | ? owner.name |
| 75 | : owner.type === 'MemberExpression' && owner.property.type === 'Identifier' |
| 76 | ? owner.property.name |
| 77 | : null; |
| 78 | if (ownerName === null || !/^[A-Z]/u.test(ownerName)) return false; |
| 79 | return !effectModuleNamesList.some(module => moduleMemberName(callee, names, module) !== null); |
| 80 | } |
| 81 | |
| 82 | /** Whether any argument is an object literal with a `cause` property or a spread that may supply one. */ |
| 83 | function passesCause(node: ESTree.NewExpression | ESTree.CallExpression): boolean { |
| 84 | return node.arguments.some(argument => { |
| 85 | const expression = unwrapNode(argument); |
| 86 | return ( |
| 87 | expression.type === 'ObjectExpression' && |
| 88 | expression.properties.some( |
| 89 | property => |
| 90 | property.type === 'SpreadElement' || |
| 91 | (!property.computed && keyName(property.key) === 'cause') |
| 92 | ) |
| 93 | ); |
| 94 | }); |
| 95 | } |
| 96 | |
| 97 | /** The constructed errors a handler produces without descending into nested functions. */ |
| 98 | function constructedErrors( |
| 99 | handler: FunctionNode, |
| 100 | names: EffectModuleNames |
| 101 | ): readonly (ESTree.NewExpression | ESTree.CallExpression)[] { |
| 102 | const found: (ESTree.NewExpression | ESTree.CallExpression)[] = []; |
| 103 | const consider = (node: ESTree.Node) => { |
| 104 | const expression = unwrapNode(node); |
| 105 | if (expression.type === 'YieldExpression' && expression.argument !== null) { |
| 106 | consider(expression.argument); |
| 107 | return; |
| 108 | } |
| 109 | if (expression.type === 'ConditionalExpression') { |
| 110 | consider(expression.consequent); |
| 111 | consider(expression.alternate); |
| 112 | return; |
| 113 | } |
| 114 | if (expression.type === 'LogicalExpression') { |
| 115 | // An object constructor is truthy, so && cannot return its left operand. |
| 116 | if (expression.operator !== '&&') consider(expression.left); |
| 117 | consider(expression.right); |
| 118 | return; |
| 119 | } |
| 120 | if (expression.type === 'SequenceExpression') { |
| 121 | const last = expression.expressions.at(-1); |
| 122 | if (last !== undefined) consider(last); |
| 123 | return; |
| 124 | } |
| 125 | if (isErrorConstruction(expression, names)) found.push(expression); |
| 126 | }; |
| 127 | for (const returned of returnedExpressions(handler)) consider(returned); |
| 128 | if (handler.body === null) return found; |
| 129 | walk(handler.body, node => { |
| 130 | // An Effect.gen generator runs as the handler's own effect; other nested functions run later, if at all. |
| 131 | if (isFunction(node)) |
| 132 | return node.type === 'FunctionExpression' && genFunction(node.parent, names) === node; |
| 133 | if (moduleCallName(node, names, 'Effect') === 'fail' && node.type === 'CallExpression') { |
| 134 | const [argument] = node.arguments; |
| 135 | if (argument !== undefined) consider(argument); |
| 136 | } |
| 137 | if (node.type === 'YieldExpression' && node.delegate && node.argument !== null) |
| 138 | consider(node.argument); |
| 139 | return true; |
| 140 | }); |
| 141 | return [...new Set(found)]; |
| 142 | } |
| 143 | |
| 144 | /** Whether `node` is a call of a tap operator, or the operator itself. */ |
| 145 | function isTapStep(node: ESTree.Node, names: EffectModuleNames): boolean { |
| 146 | const expression = unwrapNode(node); |
| 147 | const member = |
| 148 | moduleCallName(expression, names, 'Effect') ?? moduleMemberName(expression, names, 'Effect'); |
| 149 | return member !== null && tapOperators.has(member); |
| 150 | } |
| 151 | |
| 152 | /** Require narrowing handlers that replace an error to keep the original as `cause`. */ |
| 153 | export const requireCauseWhenNarrowingRule = defineRule({ |
| 154 | meta: { |
| 155 | type: 'problem', |
| 156 | docs: { |
| 157 | description: |
| 158 | 'Require Effect.mapError/catch/catchAll/catchCause/orElse handlers that construct a new error to keep the original error as `cause`.', |
| 159 | }, |
| 160 | messages: { |
| 161 | missingCause: |
| 162 | "This {{operator}} handler discards the original error and constructs a new one without it. Name the handler's parameter and pass it as `cause` (`(error) => new {{error}}({ ..., cause: error })`), or log it first with `Effect.tapError(Effect.logError)` before narrowing.", |
| 163 | }, |
| 164 | }, |
| 165 | create(context) { |
| 166 | const names = collectEffectModuleNames(context.sourceCode); |
| 167 | |
| 168 | return { |
| 169 | CallExpression(node) { |
| 170 | const operator = moduleCallName(node, names, 'Effect'); |
| 171 | if (operator === null || !narrowingOperators.has(operator)) return; |
| 172 | const handler = node.arguments.at(-1); |
| 173 | if (handler === undefined || !isFunction(handler)) return; |
| 174 | if (!ignoresError(handler, context.sourceCode)) return; |
| 175 | const constructed = constructedErrors(handler, names).find( |
| 176 | construction => !passesCause(construction) |
| 177 | ); |
| 178 | if (constructed === undefined) return; |
| 179 | const dataFirstSource = node.arguments.length > 1 ? node.arguments[0] : undefined; |
| 180 | const earlier = dataFirstSource === undefined ? precedingSteps(node) : [dataFirstSource]; |
| 181 | if (earlier.some(step => isTapStep(step, names))) return; |
| 182 | const callee = unwrapNode(constructed.callee); |
| 183 | const errorName = |
| 184 | callee.type === 'MemberExpression' |
| 185 | ? context.sourceCode.getText(callee.object) |
| 186 | : context.sourceCode.getText(callee); |
| 187 | context.report({ |
| 188 | node: constructed, |
| 189 | messageId: 'missingCause', |
| 190 | data: { operator: `Effect.${operator}`, error: errorName }, |
| 191 | }); |
| 192 | }, |
| 193 | }; |
| 194 | }, |
| 195 | }); |