@eagleoutice/eslint-config-flowr 2.1.3 → 2.1.4

package/README.md

@@ -80,11 +80,13 @@ 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 |
+| `vertex-is*`, `vertex-has-origin` | `v.tag === VertexType.X`, `Vertex.isFunctionCall(v) && v.origin.includes(o)` | `Vertex` |
 | `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` |
+| `graph-edges-from`, `graph-edges-to` | `g.outgoingEdges(id) ?? []` / `?? NoEdges`, a fallback the total accessors already are | `edgesFrom` / `edgesTo` |
+| `location-range-hop`, `location-at-node`, `accessor-undefined-guard`, `identifier-tostring-fallback` | an unwrap, a positional destructure, or an absent-value guard in front of a reader that passes `undefined` through by itself | `SourceLocation`, `Identifier` |
+| `some-instead-of-filter-length`, `array-sum` | a full walk where a helper does it once | `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

package/index.js

@@ -85,7 +85,40 @@ const config = [
             ],
             '@stylistic/comma-dangle': ['error', 'only-multiline'],
             '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
+            /*
+             * spacing that is already all but settled in flowR, pinned so it stays that way; every one of these
+             * is autofixable, so a violation costs nobody a thought
+             */
+            '@stylistic/array-bracket-spacing': ['error', 'never'],
+            '@stylistic/computed-property-spacing': ['error', 'never'],
+            '@stylistic/space-in-parens': ['error', 'never'],
+            '@stylistic/block-spacing': ['error', 'always'],
+            '@stylistic/space-before-blocks': ['error', 'always'],
+            '@stylistic/rest-spread-spacing': ['error', 'never'],
+            '@stylistic/template-curly-spacing': ['error', 'never'],
+            '@stylistic/switch-colon-spacing': ['error', { before: false, after: true }],
+            '@stylistic/no-whitespace-before-property': 'error',
+            '@stylistic/space-unary-ops': ['error', { words: true, nonwords: false }],
+            '@stylistic/semi-spacing': ['error', { before: false, after: true }],
+            '@stylistic/comma-style': ['error', 'last'],
+            '@stylistic/dot-location': ['error', 'property'],
+            '@stylistic/no-extra-semi': 'error',
             'jsdoc/check-alignment': 'error',
+            /*
+             * the same alignment `key-spacing` asks of object values, asked of tsdoc: the `-` of every `@param`
+             * in a block lines up, so the names read as a column instead of as prose
+             */
+            'jsdoc/check-line-alignment': ['error', 'always'],
+            /* `@param name - what it is`, the spelling the codebase already uses everywhere */
+            'jsdoc/require-hyphen-before-param-description': ['error', 'always'],
+            'jsdoc/no-multi-asterisks': 'error',
+            'jsdoc/require-asterisk-prefix': 'error',
+            'jsdoc/no-blank-blocks': 'error',
+            'jsdoc/check-property-names': 'error',
+            'jsdoc/empty-tags': 'error',
+            'jsdoc/require-returns-check': 'error',
+            /* a block reads top down: what it is, what it takes, what it answers, then the pointers */
+            'jsdoc/sort-tags': ['error', { linesBetween: 0 }],
             'jsdoc/check-indentation': 'off',
             'jsdoc/no-types': 'error',
             'jsdoc/no-undefined-types': 'off',

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@eagleoutice/eslint-config-flowr",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Linting rules for flowr and friends",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowr-analysis/flowr-lint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flowr-analysis/flowr-lint/issues"
+  },
+  "homepage": "https://github.com/flowr-analysis/flowr-lint#readme",
   "main": "index.js",
   "files": [
     "index.js",

package/patterns.js

@@ -13,6 +13,8 @@ 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';
+const RANGE = 'util/range';
+const IDENTIFIER = 'dataflow/environments/identifier';
 /** `x.types` under the given path */
 const types = (prefix) => `[${prefix}.type="MemberExpression"][${prefix}.computed=false][${prefix}.property.name="types"]`;
 /** `x.<name>` under the given path, without asserting the node kind, which the caller pins down */
@@ -27,6 +29,9 @@ const mask = '[left.type="BinaryExpression"][left.operator="&"]';
 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]`;
+/** the same call as the match itself rather than below it */
+const rootHelperCall = (helper, property) => `CallExpression[callee.type="MemberExpression"][callee.computed=false][callee.property.name="${property}"]`
+    + `[callee.object.name="${helper}"][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.';
@@ -67,21 +72,24 @@ const edgeStates = (id, helper, what, nonZero) => ({
  * `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 discriminatorIs = (id, { property, enumName, enumFile, propertyFile, helper, member: name = 'is', hint }, { negated = false, optional = false } = {}) => {
     const left = optional ? 'left.expression' : 'left';
     return {
         id,
         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}})`,
+        replace: `${negated ? '!' : ''}${helper}.${name}({{subject}})`,
         declaredIn: { 'right.object': enumFile, ...propertyFile ? { [`${left}.property`]: propertyFile } : {} },
-        message: `${hint} (\`${helper}.is\`), it narrows the type as well.`
+        message: `${hint} (\`${helper}.${name}\`), it narrows the type as well.`
     };
 };
-/** `v.tag === VertexType.X`, with `{{type|last}}` spelling the name of the matching helper */
+/**
+ * `v.tag === VertexType.X`. One `Vertex` helper answers for every kind, and its members are named after the
+ * enum, so `{{type|last}}` spells the check without a table: `VertexType.Use` to `Vertex.isUse`.
+ */
 const vertexIs = (id, options) => discriminatorIs(id, {
     property: 'tag', enumName: 'VertexType', enumFile: VERTEX, propertyFile: VERTEX,
-    helper: '{{type|last}}Vertex', hint: 'Compare through the vertex helper'
+    helper: 'Vertex', member: 'is{{type|last}}', 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`
@@ -121,6 +129,22 @@ const symbolName = (id, negated) => ({
     fix: false,
     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.'
 });
+/** an empty-array or `NoEdges` fallback, the two ways the absent case used to be written out */
+const emptyEdges = ':matches([right.type="ArrayExpression"][right.elements.length=0], [right.type="Identifier"][right.name="NoEdges"])';
+/**
+ * `graph.outgoingEdges(id) ?? <nothing>`, which `edgesFrom()`/`edgesTo()` already are: they answer with the
+ * shared empty map for a vertex without edges, so the fallback is dead weight and an `[]` one allocates on
+ * every miss besides. One pattern per direction, as the replacement names the method.
+ */
+const edgesFallback = (id, raw, total) => ({
+    id,
+    selector: `LogicalExpression[operator="??"]${emptyEdges}[left.type="CallExpression"]`
+        + `[left.callee.type="MemberExpression"][left.callee.computed=false][left.callee.property.name="${raw}"][left.arguments.length=1]`,
+    capture: { graph: 'left.callee.object', id: 'left.arguments.0' },
+    replace: `{{graph}}.${total}({{id}})`,
+    declaredIn: { 'left.callee.property': GRAPH },
+    message: `\`${total}\` is \`${raw}\` without the fallback: it answers with the shared empty map itself.`
+});
 const patterns = [
     edgeIsOnly('edge-is-only-type'),
     edgeIsOnly('edge-is-not-only-type', { negated: true }),
@@ -130,6 +154,61 @@ const patterns = [
     edgeStates('edge-has-no-type', 'hasNoType', 'nothing', false),
     edgeMask('edge-includes-type', 'includesType', true),
     edgeMask('edge-does-not-include-type', 'doesNotIncludeType', false),
+    {
+        /*
+         * `SourceLocation.fromNode(n) ?? []` only exists so the positional destructure below it survives an
+         * absent location; the view reads the same places by name and combines with `?.`
+         */
+        id: 'location-at-node',
+        selector: `LogicalExpression[operator="??"][right.type="ArrayExpression"][right.elements.length=0]${helperCall('left', 'SourceLocation', 'fromNode')}`,
+        capture: { node: 'left.arguments.0' },
+        replace: 'SourceLocation.at({{node}})',
+        declaredIn: { 'left.callee.object': RANGE },
+        /* the destructure around it has to become property reads, which is the author's call */
+        fix: false,
+        message: '`SourceLocation.at({{node}})` answers with a view: `.startLine`, `.file`, and `?.` for the absent case, so the `?? []` and the positional destructure both go away.'
+    },
+    {
+        /*
+         * every source range is a source location without a file, so the range readers take a location as it
+         * is and `SourceLocation` re-exports them under its own name
+         */
+        id: 'location-range-hop',
+        selector: 'CallExpression[callee.type="MemberExpression"][callee.computed=false]'
+            + '[callee.object.name=/^Source(Range|Location)$/][arguments.length=1]'
+            + `${helperCall('arguments.0', 'SourceLocation', 'getRange')}`,
+        capture: { reader: 'callee.property', location: 'arguments.0.arguments.0' },
+        replace: 'SourceLocation.{{reader}}({{location}})',
+        declaredIn: { 'callee.object': RANGE, 'arguments.0.callee.object': RANGE },
+        message: 'Drop the `getRange` hop, `SourceLocation.{{reader}}` reads the location directly.'
+    },
+    {
+        /* the readers answer `undefined` for an absent input, so the guard repeats what the type already says */
+        id: 'accessor-undefined-guard',
+        selector: `ConditionalExpression${versusUndefined('test', false)}`
+            + '[consequent.type="Identifier"][consequent.name="undefined"]'
+            + '[alternate.type="CallExpression"][alternate.callee.type="MemberExpression"][alternate.callee.computed=false]'
+            + '[alternate.callee.property.name=/^(get|format|view|at)/]'
+            + '[alternate.callee.object.name=/^Source(Range|Location)$/][alternate.arguments.length=1]',
+        capture: { call: 'alternate' },
+        replace: '{{call}}',
+        sameText: [['test.left', 'alternate.arguments.0']],
+        declaredIn: { 'alternate.callee.object': RANGE },
+        message: 'The reader passes an absent input through, the `=== undefined` guard says nothing on top of it.'
+    },
+    {
+        /* `Identifier.toString` answers `undefined` for an absent identifier, an empty name is a different thing */
+        id: 'identifier-tostring-fallback',
+        selector: `${rootHelperCall('Identifier', 'toString')}`
+            + '[arguments.0.type="LogicalExpression"][arguments.0.operator="??"]'
+            + '[arguments.0.right.type="Literal"][arguments.0.right.value=""]',
+        capture: { id: 'arguments.0.left' },
+        replace: 'Identifier.toString({{id}})',
+        declaredIn: { 'callee.object': IDENTIFIER },
+        /* an empty string and `undefined` read differently downstream, so this is offered rather than applied */
+        fix: false,
+        message: '`Identifier.toString` passes an absent identifier through; the `?? \'\'` turns "no name" into the name `""`.'
+    },
     {
         id: 'edge-includes-type-truthy',
         selector: `:matches(IfStatement, ConditionalExpression, WhileStatement, DoWhileStatement, LogicalExpression, UnaryExpression[operator="!"], ArrowFunctionExpression) > BinaryExpression[operator="&"]${types('left')}`,
@@ -141,25 +220,18 @@ const patterns = [
     {
         id: 'vertex-has-origin',
         selector: 'LogicalExpression[operator="&&"]'
-            + `${helperCall('left', 'FunctionCallVertex', 'is')}`
+            + `${helperCall('left', 'Vertex', 'isFunctionCall')}`
             + `${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}})',
+        replace: 'Vertex.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',
-        selector: 'LogicalExpression[operator="??"][right.type="ArrayExpression"][right.elements.length=0][left.type="CallExpression"][left.callee.type="MemberExpression"][left.callee.property.name=/^(outgoingEdges|ingoingEdges)$/]',
-        capture: { edges: 'left' },
-        replace: '{{edges}} ?? NoEdges',
-        declaredIn: { 'left.callee.property': GRAPH },
-        message: 'The `[]` fallback allocates on every miss, use the shared `NoEdges`.'
+        message: 'Use `Vertex.hasOrigin`, it is exactly this check. Check the narrowing first, `hasOrigin` returns a plain boolean.'
     },
+    edgesFallback('graph-edges-from', 'outgoingEdges', 'edgesFrom'),
+    edgesFallback('graph-edges-to', 'ingoingEdges', 'edgesTo'),
     vertexIs('vertex-is'),
     vertexIs('vertex-is-not', { negated: true }),
     vertexIs('vertex-is-optional', { optional: true }),