@eagleoutice/eslint-config-flowr 2.0.2 → 2.1.1

package/patterns.js

@@ -0,0 +1,113 @@
+"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`, and `NoEdges` in `dataflow/graph/graph`.
+ */
+const EDGE = 'dataflow/graph/edge';
+const VERTEX = 'dataflow/graph/vertex';
+const GRAPH = 'dataflow/graph/graph';
+/** `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 */
+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}"]`;
+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}.`
+});
+/** `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';
+    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.'
+    };
+};
+/** `FunctionCallVertex.is(v) && v.origin.includes(T)`, the body of `hasOrigin` written out */
+const hasOrigin = (id) => ({
+    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 */
+    fix: false,
+    message: 'Use `FunctionCallVertex.hasOrigin`, it is exactly this check. Check the narrowing first, `hasOrigin` returns a plain boolean.'
+});
+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.'
+    },
+    hasOrigin('vertex-has-origin'),
+    {
+        /* 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 })
+];
+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;

package/rules/util.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers of the flowR rules.
+ * Tags: `@useInstead <target>` names a replacement, `@performanceCritical` and `@lintIgnore [ids]` silence the rules.
+ */
+import type { Rule } from 'eslint';
+import type { Node } from 'estree';
+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.
+ */
+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. */
+export declare function symbolOf(node: Node | undefined, services: TypeServices, checker: TsTypeChecker): TsSymbol | undefined;
+/** The file a symbol is declared in. */
+export declare function declarationFile(symbol: TsSymbol | undefined): string | undefined;
+/** The text of the `@useInstead` tag of a symbol, `undefined` if it carries none. */
+export declare function useInsteadOf(symbol: TsSymbol, checker: TsTypeChecker): string | undefined;
+/**
+ * Whether the replacement can be applied on the spot: every name it adds over the matched code has to be
+ * bound already and usable as a value, a fixer cannot add the import that would be missing otherwise.
+ */
+export declare function isApplicable(context: Rule.RuleContext, node: Node, replacement: string): boolean;

package/rules/util.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeServices = typeServices;
+exports.suppressed = suppressed;
+exports.symbolOf = symbolOf;
+exports.declarationFile = declarationFile;
+exports.useInsteadOf = useInsteadOf;
+exports.isApplicable = isApplicable;
+const USE_INSTEAD_TAG = 'useInstead';
+const SUPPRESS_TAGS = ['@performanceCritical', '@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. */
+function typeServices(context) {
+    const services = context.sourceCode.parserServices;
+    return services?.program && services.esTreeNodeToTSNodeMap ? services : undefined;
+}
+function isDocComment(comment) {
+    return comment.type === 'Block' && comment.value.startsWith('*');
+}
+/** Whether the documentation comment silences the given rule or pattern id. */
+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;
+    }
+    const listed = ignore[1].split(/[\s,]+/).filter(s => s.length > 0);
+    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.
+ */
+function suppressed(context, node, ids) {
+    const sourceCode = context.sourceCode;
+    if (!SUPPRESS_TAGS.some(tag => sourceCode.text.includes(tag))) {
+        return false;
+    }
+    /* a header comment marks the whole file: above the imports, or separated by a blank line */
+    const first = sourceCode.getAllComments()[0];
+    const top = sourceCode.ast.body[0];
+    if (first?.range && top?.range && first.range[1] < top.range[0]
+        && (top.type === 'ImportDeclaration' || /\n\s*\n/.test(sourceCode.text.slice(first.range[1], top.range[0])))
+        && silences(first, ids)) {
+        return true;
+    }
+    for (let current = node; current; current = current.parent) {
+        /* `export function f()` carries its documentation on the export */
+        const parent = current.parent;
+        const documented = parent?.type === 'ExportNamedDeclaration' || parent?.type === 'ExportDefaultDeclaration' ? parent : current;
+        if (sourceCode.getCommentsBefore(documented).some(c => silences(c, ids))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Resolves import aliases so the documentation of the original declaration is read. */
+function resolveAlias(symbol, checker) {
+    return (symbol.flags & ALIAS_FLAG) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+}
+/** The symbol an ESTree node resolves to, with import aliases followed. */
+function symbolOf(node, services, checker) {
+    const tsNode = node ? services.esTreeNodeToTSNodeMap.get(node) : undefined;
+    const symbol = tsNode ? checker.getSymbolAtLocation(tsNode) : undefined;
+    return symbol ? resolveAlias(symbol, checker) : undefined;
+}
+/** The file a symbol is declared in. */
+function declarationFile(symbol) {
+    return symbol?.declarations?.[0]?.getSourceFile()?.fileName;
+}
+/** The text of the `@useInstead` tag of a symbol, `undefined` if it carries none. */
+function useInsteadOf(symbol, checker) {
+    for (const tag of symbol.getJsDocTags(checker)) {
+        if (tag.name === USE_INSTEAD_TAG) {
+            return (tag.text ?? []).map(p => p.text).join('').trim();
+        }
+    }
+    return undefined;
+}
+/** the names a chunk of code depends on: the root of every member chain, `a.b(c)` gives `a` and `c` */
+function rootNames(text) {
+    const names = new Set();
+    for (const [, name] of text.matchAll(/(?:^|[^\w$.])([A-Za-z_$][\w$]*)/g)) {
+        names.add(name);
+    }
+    return names;
+}
+function isValueInScope(sourceCode, node, name) {
+    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+        const variable = scope.set.get(name);
+        if (variable) {
+            /* a type-only binding of the same name is in scope but cannot be used as a value */
+            /* `Type` is typescript-eslint's own definition kind, which eslint's types do not know about */
+            return variable.defs.some(d => d.type !== 'Type'
+                && !(d.type === 'ImportBinding' && (isTypeOnly(d.node) || isTypeOnly(d.parent))));
+        }
+    }
+    return false;
+}
+function isTypeOnly(node) {
+    return node?.importKind === 'type';
+}
+/**
+ * Whether the replacement can be applied on the spot: every name it adds over the matched code has to be
+ * bound already and usable as a value, a fixer cannot add the import that would be missing otherwise.
+ */
+function isApplicable(context, node, replacement) {
+    const present = rootNames(context.sourceCode.getText(node));
+    return [...rootNames(replacement)].every(name => present.has(name) || isValueInScope(context.sourceCode, node, name));
+}

package/tsdoc.json

@@ -0,0 +1,17 @@
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+   "tagDefinitions": [
+      {
+         "tagName": "@useInstead",
+         "syntaxKind": "block"
+      },
+      {
+         "tagName": "@performanceCritical",
+         "syntaxKind": "modifier"
+      },
+      {
+         "tagName": "@lintIgnore",
+         "syntaxKind": "block"
+      }
+   ]
+}