@eagleoutice/eslint-config-flowr 2.0.2 → 2.1.3

package/pattern-type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/patterns.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`, `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[];
+export = patterns;

package/patterns.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * 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`, `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.<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]`;
+/** the `x.types & T` on the left of such a comparison */
+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 } = {}) => ({
+    id,
+    selector: `BinaryExpression[operator="${negated ? '!==' : '==='}"]`
+        + (destructured ? `[left.type="Identifier"][left.name="types"]${rightIs('EdgeType')}` : `${types('left')}:not([right.type="Literal"])`),
+    capture: destructured ? { type: 'right' } : { edge: 'left.object', type: 'right' },
+    replace: `${negated ? '!' : ''}DfEdge.isOnlyType(${destructured ? '{ types }' : '{{edge}}'}, {{type}})`,
+    declaredIn: destructured ? { 'right.object': EDGE } : { 'left.property': EDGE },
+    message: `\`${destructured ? '' : 'x.'}types ${negated ? '!==' : '==='} T\` `
+        + (negated ? 'holds as soon as any other type is set' : 'holds only if T is the *only* type')
+        + `; say so with \`${negated ? '!' : ''}DfEdge.isOnlyType\`, or use \`DfEdge.${negated ? 'doesNotIncludeType' : 'includesType'}\` for "${negated ? 'has not' : 'has'} this type".`
+        + (destructured ? destructuringHint : '')
+});
+/** `(x.types & T) !== 0` and its inverse */
+const edgeMask = (id, helper, nonZero) => ({
+    id,
+    selector: `${versusZero(nonZero)}${mask}${types('left.left')}`,
+    capture: { edge: 'left.left.object', type: 'left.right' },
+    replace: `DfEdge.${helper}({{edge}}, {{type}})`,
+    declaredIn: { 'left.left.property': EDGE },
+    message: `Use \`DfEdge.${helper}\` instead of testing the bitmask by hand.`
+});
+/** `x.types !== 0`, the literal-0 comparisons {@link edgeIsOnly} leaves out */
+const edgeStates = (id, helper, what, nonZero) => ({
+    id,
+    selector: `${versusZero(nonZero)}${types('left')}`,
+    capture: { edge: 'left.object' },
+    replace: `DfEdge.${helper}({{edge}})`,
+    declaredIn: { 'left.property': EDGE },
+    message: `Use \`DfEdge.${helper}\` to ask whether the edge states ${what}.`
+});
+/**
+ * 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'}"]${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.`
+    };
+};
+/** `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="&&"]${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: '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'),
+    edgeIsOnly('edge-is-not-only-type', { negated: true }),
+    edgeIsOnly('edge-is-only-type-destructured', { destructured: true }),
+    edgeIsOnly('edge-is-not-only-type-destructured', { negated: true, destructured: true }),
+    edgeStates('edge-has-any-type', 'hasAnyType', 'anything', true),
+    edgeStates('edge-has-no-type', 'hasNoType', 'nothing', false),
+    edgeMask('edge-includes-type', 'includesType', true),
+    edgeMask('edge-does-not-include-type', 'doesNotIncludeType', false),
+    {
+        id: 'edge-includes-type-truthy',
+        selector: `:matches(IfStatement, ConditionalExpression, WhileStatement, DoWhileStatement, LogicalExpression, UnaryExpression[operator="!"], ArrowFunctionExpression) > BinaryExpression[operator="&"]${types('left')}`,
+        capture: { edge: 'left.object', type: 'right' },
+        replace: 'DfEdge.includesType({{edge}}, {{type}})',
+        declaredIn: { 'left.property': EDGE },
+        message: 'Do not rely on the bitmask being truthy, `DfEdge.includesType` says what is meant.'
+    },
+    {
+        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',
+        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`.'
+    },
+    vertexIs('vertex-is'),
+    vertexIs('vertex-is-not', { negated: true }),
+    vertexIs('vertex-is-optional', { 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/plugin.d.ts

@@ -0,0 +1,10 @@
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        'use-instead': import("eslint").Rule.RuleModule;
+        'replacement-pattern': import("eslint").Rule.RuleModule;
+    };
+};
+export = plugin;

package/plugin.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/** The flowR-specific rules, see the README for the tags they read. */
+const replacement_pattern_1 = __importDefault(require("./rules/replacement-pattern"));
+const use_instead_1 = __importDefault(require("./rules/use-instead"));
+const plugin = {
+    meta: { name: '@eagleoutice/eslint-config-flowr' },
+    rules: {
+        'use-instead': use_instead_1.default,
+        'replacement-pattern': replacement_pattern_1.default
+    }
+};
+module.exports = plugin;

package/rules/replacement-pattern.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;

package/rules/replacement-pattern.js

@@ -0,0 +1,145 @@
+"use strict";
+const util_1 = require("./util");
+/** Resolves a dotted path (`left.object`) relative to the matched node. */
+function resolvePath(node, path) {
+    let current = node;
+    for (const step of path.split('.')) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[step];
+    }
+    return (current ?? undefined);
+}
+/**
+ * Fills `{{name}}` with the source text of a capture and `{{name|last}}` with the part behind its
+ * last dot. Returns `undefined` if a capture is missing.
+ */
+function render(template, captures, node, sourceCode) {
+    let failed = false;
+    const filled = template.replace(/\{\{\s*([A-Za-z0-9_]+)\s*(?:\|\s*(last)\s*)?\}\}/g, (_all, name, filter) => {
+        const captured = captures[name] === undefined ? undefined : resolvePath(node, captures[name]);
+        if (captured === undefined) {
+            failed = true;
+            return '';
+        }
+        const text = sourceCode.getText(captured);
+        return filter === 'last' ? text.slice(text.lastIndexOf('.') + 1) : text;
+    });
+    return failed ? undefined : filled;
+}
+const rule = {
+    meta: {
+        type: 'suggestion',
+        fixable: 'code',
+        hasSuggestions: true,
+        docs: {
+            description: 'suggest the flowR helper that replaces a hand-written pattern',
+            url: 'https://github.com/flowr-analysis/flowr-lint#flowrreplacement-pattern'
+        },
+        schema: [{
+                type: 'object',
+                properties: {
+                    patterns: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                /** identifies the pattern in `@lintIgnore` and in the message */
+                                id: { type: 'string' },
+                                /** esquery selector, the language `no-restricted-syntax` uses */
+                                selector: { type: 'string' },
+                                message: { type: 'string' },
+                                /** capture name to a path relative to the match */
+                                capture: { type: 'object', additionalProperties: { type: 'string' } },
+                                /** replacement template, filled from the captures */
+                                replace: { type: 'string' },
+                                /** path to a substring of the file its symbol must be declared in, this is what keeps the pattern flowR-specific */
+                                declaredIn: { type: 'object', additionalProperties: { type: 'string' } },
+                                /** pairs of paths that have to spell the same code, esquery has no back-references */
+                                sameText: { type: 'array', items: { type: 'array', items: { type: 'string' }, minItems: 2, maxItems: 2 } },
+                                /** `true` forces the autofix, `false` forces a suggestion; by default it is fixed when the replacement is already in scope */
+                                fix: { type: 'boolean' }
+                            },
+                            required: ['selector', 'replace'],
+                            additionalProperties: false
+                        }
+                    }
+                },
+                additionalProperties: false
+            }],
+        messages: {
+            replacement: '{{message}}',
+            suggest: 'Replace with `{{replacement}}`.'
+        }
+    },
+    create(context) {
+        const sourceCode = context.sourceCode;
+        const services = (0, util_1.typeServices)(context);
+        const checker = services?.program.getTypeChecker();
+        const patterns = context.options[0]?.patterns ?? [];
+        /* several patterns may share a selector, so they are grouped instead of overwriting each other */
+        const bySelector = new Map();
+        for (const pattern of patterns) {
+            const group = bySelector.get(pattern.selector);
+            if (group) {
+                group.push(pattern);
+            }
+            else {
+                bySelector.set(pattern.selector, [pattern]);
+            }
+        }
+        /**
+         * The match only counts if every named node resolves to a declaration of the expected flowR file.
+         * The declaring file itself is exempt, it is where the helper is built.
+         */
+        function isFlowr(node, pattern) {
+            if (!pattern.declaredIn) {
+                return true;
+            }
+            else if (!services || !checker) {
+                return false;
+            }
+            return Object.entries(pattern.declaredIn).every(([path, expected]) => {
+                const file = (0, util_1.declarationFile)((0, util_1.symbolOf)(resolvePath(node, path), services, checker));
+                return file !== undefined && file !== context.filename && file.replaceAll('\\', '/').includes(expected);
+            });
+        }
+        /** esquery cannot demand that two sub-nodes are the same, so the pattern names the pairs itself */
+        function agrees(node, pattern) {
+            return (pattern.sameText ?? []).every(([a, b]) => {
+                const left = resolvePath(node, a), right = resolvePath(node, b);
+                return left !== undefined && right !== undefined && sourceCode.getText(left) === sourceCode.getText(right);
+            });
+        }
+        function check(node, pattern) {
+            const ids = [pattern.id, 'replacement-pattern'].filter(id => id !== undefined);
+            if (!agrees(node, pattern) || !isFlowr(node, pattern) || (0, util_1.suppressed)(context, node, ids)) {
+                return;
+            }
+            const captures = pattern.capture ?? {};
+            const replacement = render(pattern.replace, captures, node, sourceCode);
+            const message = (pattern.message === undefined ? undefined : render(pattern.message, captures, node, sourceCode))
+                ?? (replacement ? `Use \`${replacement}\` here.` : `\`${pattern.id ?? pattern.selector}\` has a helper replacement.`);
+            if (replacement === undefined) {
+                context.report({ node, messageId: 'replacement', data: { message } });
+                return;
+            }
+            const fix = (fixer) => fixer.replaceText(node, replacement);
+            /* fixed on the spot where the helper is already in scope, offered as a suggestion otherwise */
+            const applicable = pattern.fix ?? (0, util_1.isApplicable)(context, node, replacement);
+            context.report({
+                node,
+                messageId: 'replacement',
+                data: { message },
+                ...applicable ? { fix } : { suggest: [{ messageId: 'suggest', data: { replacement }, fix }] }
+            });
+        }
+        const listeners = {};
+        for (const [selector, group] of bySelector) {
+            listeners[selector] = (node) => group.forEach(pattern => check(node, pattern));
+        }
+        return listeners;
+    }
+};
+module.exports = rule;

package/rules/ts-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The slice of the TypeScript compiler API the rules touch, spelled out structurally so that
+ * `typescript` stays out of this package's dependencies.
+ */
+export interface TsSourceFile {
+    fileName: string;
+}
+export interface TsDeclaration {
+    getSourceFile(): TsSourceFile | undefined;
+}
+export interface TsJsDocTag {
+    name: string;
+    text?: readonly {
+        text: string;
+    }[];
+}
+export interface TsSymbol {
+    flags: number;
+    declarations?: readonly TsDeclaration[];
+    getName(): string;
+    getJsDocTags(checker: TsTypeChecker): readonly TsJsDocTag[];
+}
+export interface TsType {
+    getProperties(): readonly TsSymbol[];
+}
+export interface TsTypeChecker {
+    getSymbolAtLocation(node: unknown): TsSymbol | undefined;
+    getAliasedSymbol(symbol: TsSymbol): TsSymbol;
+    getTypeOfSymbolAtLocation(symbol: TsSymbol, location: TsDeclaration): TsType;
+}
+/** What typescript-eslint hands to a type-aware rule. */
+export interface TypeServices {
+    program: {
+        getTypeChecker(): TsTypeChecker;
+    };
+    esTreeNodeToTSNodeMap: {
+        get(node: unknown): unknown;
+    };
+}

package/rules/ts-types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * The slice of the TypeScript compiler API the rules touch, spelled out structurally so that
+ * `typescript` stays out of this package's dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/rules/use-instead.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;

package/rules/use-instead.js

@@ -0,0 +1,161 @@
+"use strict";
+const util_1 = require("./util");
+/** documentation is read once per symbol and reused for every reference */
+const tagCache = new WeakMap();
+/** the `@useInstead` tags of all members of a helper object, keyed by the object's symbol */
+const memberCache = new WeakMap();
+function cachedTag(symbol, checker) {
+    let tag = tagCache.get(symbol);
+    if (tag === undefined) {
+        tag = (0, util_1.useInsteadOf)(symbol, checker) ?? null;
+        tagCache.set(symbol, tag);
+    }
+    return tag;
+}
+function cachedMemberTags(symbol, checker) {
+    const cached = memberCache.get(symbol);
+    if (cached) {
+        return cached;
+    }
+    const tags = new Map();
+    const declaration = symbol.declarations?.[0];
+    if (declaration) {
+        try {
+            for (const property of checker.getTypeOfSymbolAtLocation(symbol, declaration).getProperties()) {
+                const tag = (0, util_1.useInsteadOf)(property, checker);
+                if (tag !== undefined) {
+                    tags.set(property.getName(), tag);
+                }
+            }
+        }
+        catch {
+            /* nothing to check without a resolvable type */
+        }
+    }
+    memberCache.set(symbol, tags);
+    return tags;
+}
+/** `{@link Resolve.toValue}` becomes `Resolve.toValue`, owned by `Resolve`. */
+function parseTarget(tag) {
+    const display = tag.replace(/^\{\s*@link\s*/, '').replace(/\s*\|.*$/, '').replace(/\s*\}\s*$/, '').trim();
+    return { display, owner: display.split('.')[0] };
+}
+/** The references that build the replacement in the first place: helper-object wiring and re-exports. */
+function isWiring(identifier) {
+    const parent = identifier.parent;
+    switch (parent?.type) {
+        case 'Property':
+            return parent.value === identifier && parent.parent?.type === 'ObjectExpression';
+        case 'SpreadElement':
+            return parent.parent?.type === 'ObjectExpression';
+        case 'ExportSpecifier':
+        case 'ImportSpecifier':
+        case 'ImportDefaultSpecifier':
+        case 'ImportNamespaceSpecifier':
+            return true;
+        default:
+            return false;
+    }
+}
+const rule = {
+    meta: {
+        type: 'suggestion',
+        fixable: 'code',
+        hasSuggestions: true,
+        docs: {
+            description: 'enforce the replacement named by the `@useInstead` documentation tag',
+            url: 'https://github.com/flowr-analysis/flowr-lint#flowruse-instead'
+        },
+        schema: [{
+                type: 'object',
+                properties: { helperObjectPattern: { type: 'string' } },
+                additionalProperties: false
+            }],
+        messages: {
+            useInstead: 'Do not use `{{name}}` directly, use `{{replacement}}` instead.',
+            useInsteadPlain: 'Do not use `{{name}}` directly, see its documentation for the replacement.',
+            suggest: 'Replace with `{{replacement}}`.'
+        }
+    },
+    create(context) {
+        const services = (0, util_1.typeServices)(context);
+        if (!services) {
+            return {};
+        }
+        const checker = services.program.getTypeChecker();
+        const sourceCode = context.sourceCode;
+        /* helper objects are PascalCase, so member checks stay cheap */
+        const helperObjectPattern = new RegExp(context.options[0]?.helperObjectPattern ?? '^[A-Z]');
+        const candidates = new Map();
+        /** the helper objects declared here, a file may use what it wraps */
+        const owned = new Set();
+        function report(node, name, tag) {
+            const { display, owner } = parseTarget(tag);
+            if (owned.has(owner) || (0, util_1.suppressed)(context, node, ['use-instead'])) {
+                return;
+            }
+            const fix = (fixer) => fixer.replaceText(node, display);
+            /* fixed on the spot where the helper is already in scope, offered as a suggestion otherwise */
+            const applicable = display !== '' && (0, util_1.isApplicable)(context, node, display);
+            context.report({
+                node,
+                messageId: display ? 'useInstead' : 'useInsteadPlain',
+                data: { name, replacement: display },
+                ...display === '' ? {} : applicable ? { fix } : { suggest: [{ messageId: 'suggest', data: { replacement: display }, fix }] }
+            });
+        }
+        return {
+            Program() {
+                const global = sourceCode.scopeManager.globalScope;
+                const module = global?.childScopes.find(s => s.type === 'module') ?? global;
+                const foreign = [];
+                for (const variable of module?.variables ?? []) {
+                    const declaration = variable.defs[0]?.name;
+                    if (declaration?.type !== 'Identifier') {
+                        continue;
+                    }
+                    const symbol = (0, util_1.symbolOf)(declaration, services, checker);
+                    if (!symbol) {
+                        continue;
+                    }
+                    else if ((0, util_1.declarationFile)(symbol) === context.filename) {
+                        /* a declaration may always use itself */
+                        owned.add(variable.name);
+                        continue;
+                    }
+                    if (helperObjectPattern.test(variable.name)) {
+                        candidates.set(variable.name, symbol);
+                    }
+                    const tag = cachedTag(symbol, checker);
+                    if (tag !== null) {
+                        foreign.push([variable, declaration, tag]);
+                    }
+                }
+                for (const [variable, declaration, tag] of foreign) {
+                    for (const { identifier } of variable.references) {
+                        if (identifier !== declaration) {
+                            const node = identifier;
+                            if (!isWiring(node)) {
+                                report(node, variable.name, tag);
+                            }
+                        }
+                    }
+                }
+            },
+            MemberExpression(node) {
+                if (node.computed || node.object.type !== 'Identifier' || node.property.type !== 'Identifier') {
+                    return;
+                }
+                const symbol = candidates.get(node.object.name);
+                if (!symbol) {
+                    return;
+                }
+                const tag = cachedMemberTags(symbol, checker).get(node.property.name);
+                if (tag !== undefined) {
+                    report(node, `${node.object.name}.${node.property.name}`, tag);
+                }
+            }
+        };
+    }
+};
+module.exports = rule;