|
| 1 | +// Boolean assertions like `assert(value)` and `assert.ok(value)` produce a useless failure message |
| 2 | +// ("Expected true, got false") when no second-argument message is provided. That makes debugging |
| 3 | +// flaky tests painful: you know the expression was falsy, but not what value it actually had. |
| 4 | +// |
| 5 | +// This rule requires a message argument whenever the first argument is "non-trivial" — i.e. an |
| 6 | +// expression whose failure mode would not, on its own, tell you what was being asserted on. |
| 7 | +// Trivial (allowed without a message) shapes are those whose source line is fully self-describing: |
| 8 | +// |
| 9 | +// - Literals and references: `true`, `'foo'`, `isReady`, `obj.prop.sub`, `arr[0]`, `obj?.prop` |
| 10 | +// - Logical/structural unary ops on a trivial operand: `!x`, `!!x`, `typeof x`, `delete obj.k` |
| 11 | +// - `in` / `instanceof` with trivial operands: `'foo' in carrier`, `err instanceof Error` |
| 12 | +// - Calls where the callee and all arguments are trivial: `arr.includes('foo')`, |
| 13 | +// `Array.isArray(x)`, `carrier.hasOwnProperty('x-datadog-trace-id')` |
| 14 | +// - Zero-argument method calls in a chain (callee is a MemberExpression): `span.context()`, |
| 15 | +// `arr.entries()`. These act as getter-style navigation and are treated as part of a path. |
| 16 | +// |
| 17 | +// Non-trivial shapes (require a message) include value comparisons (`x > 5`, `x === 'foo'`), |
| 18 | +// logical combinations (`x && y`), dynamic indexing (`arr[i]`), zero-argument plain function |
| 19 | +// calls (`getResult()`), and anything whose actual value would be useful for debugging the |
| 20 | +// failure. |
| 21 | + |
| 22 | +/** @typedef {import('estree').Node} Node */ |
| 23 | +/** @typedef {import('estree').CallExpression} CallExpression */ |
| 24 | + |
| 25 | +const ASSERT_CALL_NAMES = ['assert', 'assert.ok'] |
| 26 | + |
| 27 | +// Unary operators that don't hide a "value of interest": they just transform a reference into a |
| 28 | +// boolean/type/undefined. `+`, `-`, `~` are excluded — those hide numeric value differences. |
| 29 | +const TRIVIAL_UNARY_OPERATORS = new Set(['!', 'typeof', 'void', 'delete']) |
| 30 | + |
| 31 | +// Binary operators that ask a structural yes/no question with both operands inspectable from |
| 32 | +// source. Excludes value comparisons (`===`, `==`, `<`, `>`, etc.) which hide the actual value. |
| 33 | +const TRIVIAL_BINARY_OPERATORS = new Set(['in', 'instanceof']) |
| 34 | + |
| 35 | +export default { |
| 36 | + meta: { |
| 37 | + type: 'problem', |
| 38 | + docs: { |
| 39 | + description: |
| 40 | + 'Require a message argument on boolean assertions (`assert(value)` / `assert.ok(value)`) ' + |
| 41 | + 'whose first argument is a non-trivial expression, so failure messages reveal what was asserted.', |
| 42 | + recommended: true, |
| 43 | + }, |
| 44 | + schema: [], |
| 45 | + messages: { |
| 46 | + missingMessage: |
| 47 | + '`{{name}}(...)` with a non-trivial first argument should pass a descriptive message as the ' + |
| 48 | + 'second argument. Without it, failures only report "Expected true, got false" without any ' + |
| 49 | + 'context about the actual value (e.g. `{{name}}({{expr}}, `expected …, got ${actual}`)`).', |
| 50 | + }, |
| 51 | + }, |
| 52 | + |
| 53 | + create (context) { |
| 54 | + return { |
| 55 | + CallExpression (node) { |
| 56 | + const calleeName = getMatchedAssertName(node.callee) |
| 57 | + if (calleeName === undefined) return |
| 58 | + |
| 59 | + if (node.arguments.length === 0) return |
| 60 | + |
| 61 | + const firstArg = node.arguments[0] |
| 62 | + |
| 63 | + if (firstArg.type === 'SpreadElement') return |
| 64 | + |
| 65 | + if (node.arguments.length >= 2) return |
| 66 | + |
| 67 | + if (isTrivialExpression(firstArg)) return |
| 68 | + |
| 69 | + const sourceCode = context.getSourceCode() |
| 70 | + |
| 71 | + context.report({ |
| 72 | + node, |
| 73 | + messageId: 'missingMessage', |
| 74 | + data: { |
| 75 | + name: calleeName, |
| 76 | + expr: sourceCode.getText(firstArg), |
| 77 | + }, |
| 78 | + }) |
| 79 | + }, |
| 80 | + } |
| 81 | + }, |
| 82 | +} |
| 83 | + |
| 84 | +/** |
| 85 | + * @param {Node} callee |
| 86 | + * @returns {string | undefined} |
| 87 | + */ |
| 88 | +function getMatchedAssertName (callee) { |
| 89 | + for (const name of ASSERT_CALL_NAMES) { |
| 90 | + const parts = name.split('.') |
| 91 | + |
| 92 | + if (parts.length === 1) { |
| 93 | + if (callee.type === 'Identifier' && callee.name === parts[0]) { |
| 94 | + return name |
| 95 | + } |
| 96 | + } else if ( |
| 97 | + callee.type === 'MemberExpression' && |
| 98 | + !callee.computed && |
| 99 | + !callee.optional && |
| 100 | + callee.object.type === 'Identifier' && |
| 101 | + callee.object.name === parts[0] && |
| 102 | + callee.property.type === 'Identifier' && |
| 103 | + callee.property.name === parts[1] |
| 104 | + ) { |
| 105 | + return name |
| 106 | + } |
| 107 | + } |
| 108 | + |
| 109 | + return undefined |
| 110 | +} |
| 111 | + |
| 112 | +/** |
| 113 | + * A "trivial" expression is one whose source text already describes what is being asserted on, |
| 114 | + * so a failure of "Expected true, got false" is informative enough on its own. See the file |
| 115 | + * header for the full taxonomy. |
| 116 | + * |
| 117 | + * @param {Node} node |
| 118 | + * @returns {boolean} |
| 119 | + */ |
| 120 | +function isTrivialExpression (node) { |
| 121 | + if (node.type === 'ChainExpression') { |
| 122 | + return isTrivialExpression(node.expression) |
| 123 | + } |
| 124 | + |
| 125 | + if ( |
| 126 | + node.type === 'Literal' || |
| 127 | + node.type === 'Identifier' || |
| 128 | + node.type === 'ThisExpression' || |
| 129 | + node.type === 'Super' |
| 130 | + ) { |
| 131 | + return true |
| 132 | + } |
| 133 | + |
| 134 | + if (node.type === 'MemberExpression') { |
| 135 | + if (node.computed) { |
| 136 | + if (node.property.type !== 'Literal') return false |
| 137 | + } else if (node.property.type !== 'Identifier') { |
| 138 | + return false |
| 139 | + } |
| 140 | + |
| 141 | + return isTrivialExpression(node.object) |
| 142 | + } |
| 143 | + |
| 144 | + if (node.type === 'UnaryExpression') { |
| 145 | + return TRIVIAL_UNARY_OPERATORS.has(node.operator) && isTrivialExpression(node.argument) |
| 146 | + } |
| 147 | + |
| 148 | + if (node.type === 'BinaryExpression') { |
| 149 | + return TRIVIAL_BINARY_OPERATORS.has(node.operator) && |
| 150 | + isTrivialExpression(node.left) && |
| 151 | + isTrivialExpression(node.right) |
| 152 | + } |
| 153 | + |
| 154 | + if (node.type === 'CallExpression') { |
| 155 | + // A zero-arg plain function call (`getResult()`) is opaque — there's nothing in the source |
| 156 | + // line that hints at the returned value. But a zero-arg call whose callee is a member access |
| 157 | + // (`span.context()`, `arr.entries()`) typically acts as getter-style navigation in a chain |
| 158 | + // and is treated as part of the path. |
| 159 | + if (node.arguments.length === 0) { |
| 160 | + return getCalleeBody(node.callee).type === 'MemberExpression' && isTrivialExpression(node.callee) |
| 161 | + } |
| 162 | + |
| 163 | + for (const arg of node.arguments) { |
| 164 | + if (arg.type === 'SpreadElement') return false |
| 165 | + if (!isTrivialExpression(arg)) return false |
| 166 | + } |
| 167 | + |
| 168 | + return isTrivialExpression(node.callee) |
| 169 | + } |
| 170 | + |
| 171 | + return false |
| 172 | +} |
| 173 | + |
| 174 | +/** |
| 175 | + * Strips a leading optional-chain wrapper to expose the underlying callee, so `foo?.bar` is seen |
| 176 | + * as a MemberExpression (not a ChainExpression) when we're classifying a `CallExpression`. |
| 177 | + * |
| 178 | + * @param {Node} callee |
| 179 | + * @returns {Node} |
| 180 | + */ |
| 181 | +function getCalleeBody (callee) { |
| 182 | + return callee.type === 'ChainExpression' ? callee.expression : callee |
| 183 | +} |
0 commit comments