@eagleoutice/eslint-config-flowr 2.1.1 → 2.1.3

package/README.md

@@ -75,6 +75,22 @@ To add one, append to [`patterns.ts`](patterns.ts):
 | `fix` | `true` always fixes, `false` always suggests, which is right when the replacement can change type narrowing. Omitted, it fixes when the replacement is in scope |
 | `id` | names the pattern in `@lintIgnore` and in the message |
 
+The shipped set groups into families:
+
+| family | shape it finds | helper it points at |
+| :-- | :-- | :-- |
+| `edge-*` | `e.types === T`, `(e.types & T) !== 0`, and the bitmask spellings around them | `DfEdge` |
+| `vertex-is*`, `vertex-has-origin` | `v.tag === VertexType.X`, `FunctionCallVertex.is(v) && v.origin.includes(o)` | the `*Vertex` objects |
+| `node-is*` | `n.type === RType.X`, negated and through `?.` | `RSymbol`, `RFunctionCall`, and the rest of the `R*` node objects |
+| `argument-is-*`, `call-is-*`, `list-is-implicit` | a guard written out, `RFunctionCall.is(n) && n.named` | the narrower guard of the same object |
+| `symbol-name-comparison*` | `symbol.content === 'name'`, which misses `pkg::name` because an identifier with a namespace is an array | `Identifier.getName` / `Identifier.matches` |
+| `graph-edges-no-alloc`, `some-instead-of-filter-length`, `array-sum` | an allocation or a full walk where a shared constant or a helper does it once | `NoEdges`, `some`, `arraySum` |
+
+A pattern is exempt in the file `declaredIn` resolves to, which is why a shape only earns a place here when the
+match names a flowR symbol: without one the rule cannot tell the helper's own body apart from a call site, and
+`@lintIgnore` on the declaration would be papering over that. A guard that *is* the raw comparison
+(`RSymbol.is` compares `type` against `RType.Symbol`) is the case the tag is actually for.
+
 An own `patterns` array replaces the defaults rather than merging with them. To propose one, open an issue with the
 [replacement pattern template](.github/ISSUE_TEMPLATE/replacement-pattern.yaml).
 
@@ -83,8 +99,7 @@ An own `patterns` array replaces the defaults rather than merging with them. To
 | | silences |
 | :-- | :-- |
 | `// eslint-disable-next-line` | the next line, as usual |
-| `@performanceCritical` | a hot path that has to keep the raw form |
-| `@lintIgnore <ids>` | the named rules or pattern ids, all of them when given none |
+| `@lintIgnore <ids>` | the named rules or pattern ids, all of them when given none (put the reason in the prose above it) |
 
 A tag on a declaration covers everything below it, a header comment above the imports covers the file. The lookup is
 guarded by a single string search, so files without either tag pay nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/eslint-config-flowr",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Linting rules for flowr and friends",
   "license": "ISC",
   "main": "index.js",

package/patterns.d.ts

@@ -1,7 +1,8 @@
 /**
  * Default patterns of `flowr/replacement-pattern`, see the README for the format.
  * The helpers they point at live in flowR: `DfEdge` in `dataflow/graph/edge`, the vertex helpers in
- * `dataflow/graph/vertex`, and `NoEdges` in `dataflow/graph/graph`.
+ * `dataflow/graph/vertex`, `NoEdges` in `dataflow/graph/graph`, the `RNode` helpers in
+ * `r-bridge/lang-4.x/ast/model`, and the collection helpers in `util/collections`.
  */
 import type { ReplacementPattern } from './pattern-type';
 declare const patterns: readonly ReplacementPattern[];

package/patterns.js

@@ -2,16 +2,22 @@
 /**
  * Default patterns of `flowr/replacement-pattern`, see the README for the format.
  * The helpers they point at live in flowR: `DfEdge` in `dataflow/graph/edge`, the vertex helpers in
- * `dataflow/graph/vertex`, and `NoEdges` in `dataflow/graph/graph`.
+ * `dataflow/graph/vertex`, `NoEdges` in `dataflow/graph/graph`, the `RNode` helpers in
+ * `r-bridge/lang-4.x/ast/model`, and the collection helpers in `util/collections`.
  */
 const EDGE = 'dataflow/graph/edge';
 const VERTEX = 'dataflow/graph/vertex';
 const GRAPH = 'dataflow/graph/graph';
+const RTYPE = 'r-bridge/lang-4.x/ast/model/type';
+const CALL_NODE = 'r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+const ARGUMENT_NODE = 'r-bridge/lang-4.x/ast/model/nodes/r-argument';
+const SYMBOL_NODE = 'r-bridge/lang-4.x/ast/model/nodes/r-symbol';
+const LIST_NODE = 'r-bridge/lang-4.x/ast/model/nodes/r-expression-list';
 /** `x.types` under the given path */
 const types = (prefix) => `[${prefix}.type="MemberExpression"][${prefix}.computed=false][${prefix}.property.name="types"]`;
-/** `x.tag` under the given path */
-const tag = (prefix) => `[${prefix}.computed=false][${prefix}.property.name="tag"]`;
-/** `EdgeType.<Member>` / `VertexType.<Member>` on the right */
+/** `x.<name>` under the given path, without asserting the node kind, which the caller pins down */
+const member = (prefix, name) => `[${prefix}.computed=false][${prefix}.property.name="${name}"]`;
+/** `EdgeType.<Member>` / `VertexType.<Member>` / `RType.<Member>` on the right */
 const rightIs = (name) => `[right.type="MemberExpression"][right.computed=false][right.object.name="${name}"]`;
 /** compared against the literal `0`, either for "some bit is set" or for "none is" */
 const versusZero = (nonZero) => `BinaryExpression[operator=${nonZero ? '/^(!==|>)$/' : '"==="'}][right.type="Literal"][right.value=0]`;
@@ -19,6 +25,10 @@ const versusZero = (nonZero) => `BinaryExpression[operator=${nonZero ? '/^(!==|>
 const mask = '[left.type="BinaryExpression"][left.operator="&"]';
 /** a call of `<prefix>.<property>(...)` */
 const call = (prefix, property) => `[${prefix}.type="CallExpression"][${prefix}.callee.type="MemberExpression"][${prefix}.callee.property.name="${property}"]`;
+/** a call of `<Helper>.<property>(<one argument>)` under the given path */
+const helperCall = (prefix, helper, property) => `${call(prefix, property)}[${prefix}.callee.object.name="${helper}"][${prefix}.arguments.length=1]`;
+/** `x === undefined` / `x !== undefined` under the given path */
+const versusUndefined = (prefix, set) => `[${prefix}.type="BinaryExpression"][${prefix}.operator="${set ? '!==' : '==='}"][${prefix}.right.type="Identifier"][${prefix}.right.name="undefined"]`;
 const destructuringHint = ' Prefer keeping the edge over destructuring `types`, the helpers take it directly and the wrapper object goes away.';
 /** `x.types === T`, on the edge itself or on a destructured `types` */
 const edgeIsOnly = (id, { negated = false, destructured = false } = {}) => ({
@@ -51,32 +61,65 @@ const edgeStates = (id, helper, what, nonZero) => ({
     declaredIn: { 'left.property': EDGE },
     message: `Use \`DfEdge.${helper}\` to ask whether the edge states ${what}.`
 });
-/** `v.tag === VertexType.X`, with `{{type|last}}` spelling the name of the matching helper */
-const vertexIs = (id, { negated = false, optional = false } = {}) => {
-    const vertex = optional ? 'left.expression.object' : 'left.object';
+/**
+ * A discriminator compared against its enum, `v.tag === VertexType.X` and `n.type === RType.X`.
+ * `optional` covers the `?.` spelling, which parses as a chain around the same member expression.
+ * `declaring` maps a path of the match to the file its symbol has to come from; the enum on the right is
+ * always pinned, the property on the left only where one file declares it for every case.
+ */
+const discriminatorIs = (id, { property, enumName, enumFile, propertyFile, helper, hint }, { negated = false, optional = false } = {}) => {
     const left = optional ? 'left.expression' : 'left';
     return {
         id,
-        selector: `BinaryExpression[operator="${negated ? '!==' : '==='}"][left.type="${optional ? 'ChainExpression' : 'MemberExpression'}"]${tag(left)}${rightIs('VertexType')}`,
-        capture: { vertex, type: 'right' },
-        replace: `${negated ? '!' : ''}{{type|last}}Vertex.is({{vertex}})`,
-        declaredIn: { [`${left}.property`]: VERTEX, 'right.object': VERTEX },
-        message: 'Compare through the vertex helper (`{{type|last}}Vertex.is`), it narrows the type as well.'
+        selector: `BinaryExpression[operator="${negated ? '!==' : '==='}"][left.type="${optional ? 'ChainExpression' : 'MemberExpression'}"]${member(left, property)}${rightIs(enumName)}`,
+        capture: { subject: `${left}.object`, type: 'right' },
+        replace: `${negated ? '!' : ''}${helper}.is({{subject}})`,
+        declaredIn: { 'right.object': enumFile, ...propertyFile ? { [`${left}.property`]: propertyFile } : {} },
+        message: `${hint} (\`${helper}.is\`), it narrows the type as well.`
     };
 };
-/** `FunctionCallVertex.is(v) && v.origin.includes(T)`, the body of `hasOrigin` written out */
-const hasOrigin = (id) => ({
+/** `v.tag === VertexType.X`, with `{{type|last}}` spelling the name of the matching helper */
+const vertexIs = (id, options) => discriminatorIs(id, {
+    property: 'tag', enumName: 'VertexType', enumFile: VERTEX, propertyFile: VERTEX,
+    helper: '{{type|last}}Vertex', hint: 'Compare through the vertex helper'
+}, options);
+/**
+ * `n.type === RType.X`. Every `RType` member has a helper object of the same name prefixed with `R`
+ * (`RType.Symbol` to `RSymbol`), so `{{type|last}}` names it without a table.
+ * Only the enum is pinned to its file: `type` is declared once per node interface, and on the `RNode`
+ * union it resolves to a synthesized symbol, so demanding a declaring file for it would match nothing.
+ */
+const nodeIs = (id, options) => discriminatorIs(id, {
+    property: 'type', enumName: 'RType', enumFile: RTYPE,
+    helper: 'R{{type|last}}', hint: 'Ask the AST node helper'
+}, options);
+/**
+ * `<Helper>.is(x) && <extra check on x>`, the body of a more specific guard written out.
+ * `guard` pins down the right-hand side, `subject` is the path of the operand it repeats.
+ */
+const guardWrittenOut = ({ id, helper, member: narrower, file, guard, subject, message, fix }) => ({
     id,
-    selector: 'LogicalExpression[operator="&&"]'
-        + `${call('left', 'is')}[left.callee.object.name="FunctionCallVertex"]`
-        + `${call('right', 'includes')}[right.callee.object.type="MemberExpression"][right.callee.object.property.name="origin"]`,
-    capture: { vertex: 'left.arguments.0', origin: 'right.arguments.0' },
-    replace: 'FunctionCallVertex.hasOrigin({{vertex}}, {{origin}})',
-    declaredIn: { 'left.callee.object': VERTEX, 'right.callee.object.property': VERTEX },
-    sameText: [['left.arguments.0', 'right.callee.object.object']],
-    /* `hasOrigin` is no type predicate, so the replacement can drop a narrowing the code below relies on */
+    selector: `LogicalExpression[operator="&&"]${helperCall('left', helper, 'is')}${guard}`,
+    capture: { node: 'left.arguments.0' },
+    replace: `${helper}.${narrower}({{node}})`,
+    declaredIn: { 'left.callee.object': file },
+    sameText: [['left.arguments.0', subject]],
+    ...fix === undefined ? {} : { fix },
+    message
+});
+/**
+ * `symbol.content === 'name'`. `content` of an {@link RSymbol} is an `Identifier`, which carries a namespace
+ * and turns into an array once it has one, so `===` against a bare name silently misses `pkg::name`.
+ */
+const symbolName = (id, negated) => ({
+    id,
+    selector: `BinaryExpression[operator="${negated ? '!==' : '==='}"][left.type="MemberExpression"]${member('left', 'content')}[right.type="Literal"][right.value=type(string)]`,
+    capture: { symbol: 'left.object', name: 'right' },
+    replace: `Identifier.getName({{symbol}}.content) ${negated ? '!==' : '==='} {{name}}`,
+    declaredIn: { 'left.property': SYMBOL_NODE },
+    /* which of the two is meant is the author's call, so this is offered rather than applied */
     fix: false,
-    message: 'Use `FunctionCallVertex.hasOrigin`, it is exactly this check. Check the narrowing first, `hasOrigin` returns a plain boolean.'
+    message: 'An `Identifier` is not its name: `pkg::{{name}}` is an array and never `===` a string. Compare `Identifier.getName({{symbol}}.content)`, or `Identifier.matches` when the namespace should count.'
 });
 const patterns = [
     edgeIsOnly('edge-is-only-type'),
@@ -95,7 +138,19 @@ const patterns = [
         declaredIn: { 'left.property': EDGE },
         message: 'Do not rely on the bitmask being truthy, `DfEdge.includesType` says what is meant.'
     },
-    hasOrigin('vertex-has-origin'),
+    {
+        id: 'vertex-has-origin',
+        selector: 'LogicalExpression[operator="&&"]'
+            + `${helperCall('left', 'FunctionCallVertex', 'is')}`
+            + `${call('right', 'includes')}[right.callee.object.type="MemberExpression"][right.callee.object.property.name="origin"]`,
+        capture: { vertex: 'left.arguments.0', origin: 'right.arguments.0' },
+        replace: 'FunctionCallVertex.hasOrigin({{vertex}}, {{origin}})',
+        declaredIn: { 'left.callee.object': VERTEX, 'right.callee.object.property': VERTEX },
+        sameText: [['left.arguments.0', 'right.callee.object.object']],
+        /* `hasOrigin` is no type predicate, so the replacement can drop a narrowing the code below relies on */
+        fix: false,
+        message: 'Use `FunctionCallVertex.hasOrigin`, it is exactly this check. Check the narrowing first, `hasOrigin` returns a plain boolean.'
+    },
     {
         /* the `[]` fallback allocates on every miss, and these sit in traversal loops */
         id: 'graph-edges-no-alloc',
@@ -108,6 +163,76 @@ const patterns = [
     vertexIs('vertex-is'),
     vertexIs('vertex-is-not', { negated: true }),
     vertexIs('vertex-is-optional', { optional: true }),
-    vertexIs('vertex-is-not-optional', { negated: true, optional: true })
+    vertexIs('vertex-is-not-optional', { negated: true, optional: true }),
+    nodeIs('node-is'),
+    nodeIs('node-is-not', { negated: true }),
+    nodeIs('node-is-optional', { optional: true }),
+    nodeIs('node-is-not-optional', { negated: true, optional: true }),
+    guardWrittenOut({
+        id: 'call-is-named', helper: 'RFunctionCall', member: 'isNamed', file: CALL_NODE,
+        guard: `[right.type="MemberExpression"]${member('right', 'named')}`,
+        subject: 'right.object',
+        message: 'Use `RFunctionCall.isNamed`, it is this check and narrows to `RNamedFunctionCall`.'
+    }),
+    guardWrittenOut({
+        id: 'call-is-named-strict', helper: 'RFunctionCall', member: 'isNamed', file: CALL_NODE,
+        guard: `[right.type="BinaryExpression"][right.operator="==="][right.right.type="Literal"][right.right.value=true]${member('right.left', 'named')}`,
+        subject: 'right.left.object',
+        message: 'Use `RFunctionCall.isNamed`, it is this check and narrows to `RNamedFunctionCall`.'
+    }),
+    guardWrittenOut({
+        id: 'call-is-unnamed', helper: 'RFunctionCall', member: 'isUnnamed', file: CALL_NODE,
+        guard: `[right.type="UnaryExpression"][right.operator="!"][right.argument.type="MemberExpression"]${member('right.argument', 'named')}`,
+        subject: 'right.argument.object',
+        message: 'Use `RFunctionCall.isUnnamed`, it is this check and narrows to `RUnnamedFunctionCall`.'
+    }),
+    guardWrittenOut({
+        id: 'argument-is-named', helper: 'RArgument', member: 'isNamed', file: ARGUMENT_NODE,
+        guard: `${versusUndefined('right', true)}${member('right.left', 'name')}`,
+        subject: 'right.left.object',
+        message: 'Use `RArgument.isNamed`, it is this check and keeps the `name` non-optional afterwards.'
+    }),
+    guardWrittenOut({
+        id: 'argument-is-with-value', helper: 'RArgument', member: 'isWithValue', file: ARGUMENT_NODE,
+        guard: `${versusUndefined('right', true)}${member('right.left', 'value')}`,
+        subject: 'right.left.object',
+        message: 'Use `RArgument.isWithValue`, it is this check and keeps the `value` non-optional afterwards.'
+    }),
+    guardWrittenOut({
+        id: 'list-is-implicit', helper: 'RExpressionList', member: 'isImplicit', file: LIST_NODE,
+        guard: `${versusUndefined('right', false)}${member('right.left', 'grouping')}`,
+        subject: 'right.left.object',
+        message: 'Use `RExpressionList.isImplicit`, an expression list without `grouping` is exactly the implicit one.'
+    }),
+    symbolName('symbol-name-comparison', false),
+    symbolName('symbol-name-comparison-not', true),
+    {
+        id: 'array-sum',
+        selector: 'CallExpression[callee.type="MemberExpression"][callee.property.name="reduce"][arguments.length=2]'
+            + '[arguments.1.type="Literal"][arguments.1.value=0]'
+            + '[arguments.0.type="ArrowFunctionExpression"][arguments.0.params.length=2]'
+            + '[arguments.0.body.type="BinaryExpression"][arguments.0.body.operator="+"]',
+        capture: { array: 'callee.object' },
+        replace: 'arraySum({{array}})',
+        sameText: [['arguments.0.params.0', 'arguments.0.body.left'], ['arguments.0.params.1', 'arguments.0.body.right']],
+        message: 'Use `arraySum`, summing a list is not a place to spell out a fold.'
+    },
+    {
+        /* `filter` walks the whole list and allocates the matches only to ask whether there is one */
+        id: 'some-instead-of-filter-length',
+        selector: `${versusZero(true)}[left.type="MemberExpression"]${member('left', 'length')}`
+            + `${call('left.object', 'filter')}[left.object.arguments.length=1]`,
+        capture: { array: 'left.object.callee.object', predicate: 'left.object.arguments.0' },
+        replace: '{{array}}.some({{predicate}})',
+        message: '`filter(...).length > 0` walks the whole list and allocates the matches, `some` stops at the first hit.'
+    },
+    {
+        id: 'none-instead-of-filter-length',
+        selector: `${versusZero(false)}[left.type="MemberExpression"]${member('left', 'length')}`
+            + `${call('left.object', 'filter')}[left.object.arguments.length=1]`,
+        capture: { array: 'left.object.callee.object', predicate: 'left.object.arguments.0' },
+        replace: '!{{array}}.some({{predicate}})',
+        message: '`filter(...).length === 0` walks the whole list and allocates the matches, `!some` stops at the first hit.'
+    }
 ];
 module.exports = patterns;

package/rules/util.d.ts

@@ -1,6 +1,6 @@
 /**
  * Shared helpers of the flowR rules.
- * Tags: `@useInstead <target>` names a replacement, `@performanceCritical` and `@lintIgnore [ids]` silence the rules.
+ * Tags: `@useInstead <target>` names a replacement, `@lintIgnore [ids]` silences the rules.
  */
 import type { Rule } from 'eslint';
 import type { Node } from 'estree';
@@ -8,8 +8,8 @@ import type { TsSymbol, TsTypeChecker, TypeServices } from './ts-types';
 /** The type-aware services, or `undefined` if the file is parsed without a program. */
 export declare function typeServices(context: Rule.RuleContext): TypeServices | undefined;
 /**
- * Whether `node` sits below a declaration documented with a suppressing tag, or in a file whose
- * header comment carries one. Guarded by one string search, so untagged files pay nothing.
+ * Whether `node` sits below a declaration documented with `@lintIgnore`, or in a file whose header comment
+ * carries it. Guarded by one string search, so untagged files pay nothing.
  */
 export declare function suppressed(context: Rule.RuleContext, node: Rule.Node, ids: readonly string[]): boolean;
 /** The symbol an ESTree node resolves to, with import aliases followed. */

package/rules/util.js

@@ -7,7 +7,7 @@ exports.declarationFile = declarationFile;
 exports.useInsteadOf = useInsteadOf;
 exports.isApplicable = isApplicable;
 const USE_INSTEAD_TAG = 'useInstead';
-const SUPPRESS_TAGS = ['@performanceCritical', '@lintIgnore'];
+const SUPPRESS_TAG = '@lintIgnore';
 /* ts.SymbolFlags.Alias, spelled out to keep typescript out of the dependencies */
 const ALIAS_FLAG = 1 << 21;
 /** The type-aware services, or `undefined` if the file is parsed without a program. */
@@ -23,9 +23,6 @@ function silences(comment, ids) {
     if (!isDocComment(comment)) {
         return false;
     }
-    else if (comment.value.includes('@performanceCritical')) {
-        return true;
-    }
     const ignore = /@lintIgnore([^\n@*]*)/.exec(comment.value);
     if (!ignore) {
         return false;
@@ -34,12 +31,12 @@ function silences(comment, ids) {
     return listed.length === 0 || listed.some(id => ids.includes(id));
 }
 /**
- * Whether `node` sits below a declaration documented with a suppressing tag, or in a file whose
- * header comment carries one. Guarded by one string search, so untagged files pay nothing.
+ * Whether `node` sits below a declaration documented with `@lintIgnore`, or in a file whose header comment
+ * carries it. Guarded by one string search, so untagged files pay nothing.
  */
 function suppressed(context, node, ids) {
     const sourceCode = context.sourceCode;
-    if (!SUPPRESS_TAGS.some(tag => sourceCode.text.includes(tag))) {
+    if (!sourceCode.text.includes(SUPPRESS_TAG)) {
         return false;
     }
     /* a header comment marks the whole file: above the imports, or separated by a blank line */

package/tsdoc.json

@@ -5,10 +5,6 @@
          "tagName": "@useInstead",
          "syntaxKind": "block"
       },
-      {
-         "tagName": "@performanceCritical",
-         "syntaxKind": "modifier"
-      },
       {
          "tagName": "@lintIgnore",
          "syntaxKind": "block"