@eagleoutice/eslint-config-flowr 2.1.8 → 2.1.10

package/rules/replacement-pattern.js

@@ -28,6 +28,20 @@ function render(template, captures, node, sourceCode) {
     });
     return failed ? undefined : filled;
 }
+/** per program, whether one of its files matches a `helperIn` path; every file of a run shares the program */
+const helperFiles = new WeakMap();
+function programHas(program, path) {
+    let known = helperFiles.get(program);
+    if (known === undefined) {
+        helperFiles.set(program, known = new Map());
+    }
+    let has = known.get(path);
+    if (has === undefined) {
+        has = program.getSourceFiles().some(file => file.fileName.replaceAll('\\', '/').includes(path));
+        known.set(path, has);
+    }
+    return has;
+}
 const rule = {
     meta: {
         type: 'suggestion',
@@ -56,6 +70,8 @@ const rule = {
                                 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' } },
+                                /** path to a substring of the file the replacement's helper lives in, the pattern is silent in a program without it */
+                                helperIn: { 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 */
@@ -89,12 +105,12 @@ const rule = {
                 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.
-         */
+        /** The match only counts if every named node resolves to a declaration of the expected flowR file. */
         function isFlowr(node, pattern) {
-            if (!pattern.declaredIn) {
+            if (pattern.helperIn !== undefined && (!services || !programHas(services.program, pattern.helperIn))) {
+                return false;
+            }
+            else if (!pattern.declaredIn) {
                 return true;
             }
             else if (!services || !checker) {
@@ -102,7 +118,7 @@ const rule = {
             }
             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);
+                return file !== undefined && file.replaceAll('\\', '/').includes(expected);
             });
         }
         /** esquery cannot demand that two sub-nodes are the same, so the pattern names the pairs itself */
@@ -121,7 +137,10 @@ const rule = {
             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) {
+            if (replacement !== undefined && (0, util_1.insideReplacement)(node, replacement, sourceCode, services)) {
+                return;
+            }
+            else if (replacement === undefined) {
                 context.report({ node, messageId: 'replacement', data: { message } });
                 return;
             }

package/rules/ts-types.d.ts

@@ -7,6 +7,8 @@ export interface TsSourceFile {
 }
 export interface TsDeclaration {
     getSourceFile(): TsSourceFile | undefined;
+    /** what a property or variable is set to, `frames: framesOf` binds `framesOf` */
+    initializer?: unknown;
 }
 export interface TsJsDocTag {
     name: string;
@@ -27,11 +29,16 @@ export interface TsTypeChecker {
     getSymbolAtLocation(node: unknown): TsSymbol | undefined;
     getAliasedSymbol(symbol: TsSymbol): TsSymbol;
     getTypeOfSymbolAtLocation(symbol: TsSymbol, location: TsDeclaration): TsType;
+    /** what a module exports, its symbol taken from the source file */
+    getExportsOfModule(module: TsSymbol): readonly TsSymbol[];
+    /** the variable a shorthand property `{ framesOf }` stands for */
+    getShorthandAssignmentValueSymbol(declaration: TsDeclaration): TsSymbol | undefined;
 }
 /** What typescript-eslint hands to a type-aware rule. */
 export interface TypeServices {
     program: {
         getTypeChecker(): TsTypeChecker;
+        getSourceFiles(): readonly TsSourceFile[];
     };
     esTreeNodeToTSNodeMap: {
         get(node: unknown): unknown;

package/rules/use-instead.js

@@ -35,10 +35,16 @@ function cachedMemberTags(symbol, checker) {
     memberCache.set(symbol, tags);
     return tags;
 }
-/** `{@link Resolve.toValue}` becomes `Resolve.toValue`, owned by `Resolve`. */
+/** `X.member` around a reference to `X`, with the member it reads */
+function memberRead(node) {
+    const parent = node.parent;
+    return parent?.type === 'MemberExpression' && parent.object === node && !parent.computed && parent.property.type === 'Identifier'
+        ? { node: parent, member: parent.property.name } : undefined;
+}
+/** `{@link Resolve.toValue}` becomes `Resolve.toValue`. */
 function parseTarget(tag) {
     const display = tag.replace(/^\{\s*@link\s*/, '').replace(/\s*\|.*$/, '').replace(/\s*\}\s*$/, '').trim();
-    return { display, owner: display.split('.')[0] };
+    return { display };
 }
 /** The references that build the replacement in the first place: helper-object wiring and re-exports. */
 function isWiring(identifier) {
@@ -74,6 +80,7 @@ const rule = {
         messages: {
             useInstead: 'Do not use `{{name}}` directly, use `{{replacement}}` instead.',
             useInsteadPlain: 'Do not use `{{name}}` directly, see its documentation for the replacement.',
+            useInsteadMissing: 'Do not use `{{name}}` directly, use `{{replacement}}` instead, which has no counterpart of `{{member}}` yet.',
             suggest: 'Replace with `{{replacement}}`.'
         }
     },
@@ -87,21 +94,28 @@ const rule = {
         /* 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'])) {
+            const { display } = parseTarget(tag);
+            /* only the wrapper itself may use what it wraps, anywhere else the replacement holds */
+            if ((0, util_1.insideReplacement)(node, display, sourceCode, services) || (0, util_1.suppressed)(context, node, ['use-instead'])) {
+                return;
+            }
+            /* `Old.member` moves to the member of the replacement that takes its place, which may be named differently */
+            const access = memberRead(node);
+            const counterpart = display === '' || access === undefined || !services ? null : (0, util_1.counterpartOf)(node, access.member, display, sourceCode, services);
+            if (counterpart === undefined) {
+                context.report({ node, messageId: 'useInsteadMissing', data: { name, replacement: display, member: access?.member ?? '' } });
                 return;
             }
-            const fix = (fixer) => fixer.replaceText(node, display);
+            const [target, text] = counterpart === null || access === undefined ? [node, display] : [access.node, `${display}.${counterpart}`];
+            const fix = (fixer) => fixer.replaceText(target, text);
             /* 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 }] }
+                data: { name, replacement: text },
+                ...display === '' ? {} : applicable ? { fix } : { suggest: [{ messageId: 'suggest', data: { replacement: text }, fix }] }
             });
         }
         return {
@@ -111,18 +125,15 @@ const rule = {
                 const foreign = [];
                 for (const variable of module?.variables ?? []) {
                     const declaration = variable.defs[0]?.name;
-                    if (declaration?.type !== 'Identifier') {
+                    /* only what is imported is someone else's to replace, the file's own declarations may use themselves;
+                       asked of the code rather than of file paths, which differ between systems */
+                    if (declaration?.type !== 'Identifier' || variable.defs[0]?.type !== 'ImportBinding') {
                         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);
                     }

package/rules/util.d.ts

@@ -2,7 +2,7 @@
  * Shared helpers of the flowR rules.
  * Tags: `@useInstead <target>` names a replacement, `@lintIgnore [ids]` silences the rules.
  */
-import type { Rule } from 'eslint';
+import type { Rule, SourceCode } 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. */
@@ -14,6 +14,18 @@ export declare function typeServices(context: Rule.RuleContext): TypeServices |
 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 member of `replacement` that takes the place of `member` of `original`: the one of the same name, else the one
+ * bound to the same function under another name. `undefined` if the replacement has none, `null` if it cannot be told.
+ */
+export declare function counterpartOf(original: Node, member: string, replacement: string, sourceCode: SourceCode, services: TypeServices): string | undefined | null;
+/**
+ * Whether `node` sits in a function the replacement would call, where putting the replacement in would make that
+ * function call itself. A replacement can only call what it names: a function is excluded if it is declared or bound
+ * under one of those names, or, with types, if one of them resolves to it, wired up under another name or in another
+ * file. Both ask the code alone, never file paths, which differ between systems and how a file was opened.
+ */
+export declare function insideReplacement(node: Node, replacement: string, sourceCode: SourceCode, services?: TypeServices): boolean;
 /** 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. */

package/rules/util.js

@@ -3,13 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.typeServices = typeServices;
 exports.suppressed = suppressed;
 exports.symbolOf = symbolOf;
+exports.counterpartOf = counterpartOf;
+exports.insideReplacement = insideReplacement;
 exports.declarationFile = declarationFile;
 exports.useInsteadOf = useInsteadOf;
 exports.isApplicable = isApplicable;
-const USE_INSTEAD_TAG = 'useInstead';
-const SUPPRESS_TAG = '@lintIgnore';
+const UseInsteadTag = 'useInstead';
+const SuppressTag = '@lintIgnore';
 /* ts.SymbolFlags.Alias, spelled out to keep typescript out of the dependencies */
-const ALIAS_FLAG = 1 << 21;
+const AliasFlag = 1 << 21;
 /** The type-aware services, or `undefined` if the file is parsed without a program. */
 function typeServices(context) {
     const services = context.sourceCode.parserServices;
@@ -36,7 +38,7 @@ function silences(comment, ids) {
  */
 function suppressed(context, node, ids) {
     const sourceCode = context.sourceCode;
-    if (!sourceCode.text.includes(SUPPRESS_TAG)) {
+    if (!sourceCode.text.includes(SuppressTag)) {
         return false;
     }
     /* a header comment marks the whole file: above the imports, or separated by a blank line */
@@ -59,7 +61,7 @@ function suppressed(context, node, ids) {
 }
 /** 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;
+    return (symbol.flags & AliasFlag) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
 }
 /** The symbol an ESTree node resolves to, with import aliases followed. */
 function symbolOf(node, services, checker) {
@@ -67,6 +69,109 @@ function symbolOf(node, services, checker) {
     const symbol = tsNode ? checker.getSymbolAtLocation(tsNode) : undefined;
     return symbol ? resolveAlias(symbol, checker) : undefined;
 }
+/** the name node a function is declared or bound under: a declaration, a member of an object or class, a variable, or an assignment */
+function nameOf(fn, parent) {
+    if ((fn.type === 'FunctionDeclaration' || fn.type === 'FunctionExpression') && fn.id) {
+        return fn.id;
+    }
+    switch (parent?.type) {
+        case 'Property':
+        case 'MethodDefinition':
+        case 'PropertyDefinition':
+            return parent.key;
+        case 'VariableDeclarator':
+            return parent.id;
+        case 'AssignmentExpression':
+            return parent.left.type === 'MemberExpression' ? parent.left.property : parent.left;
+        default:
+            return undefined;
+    }
+}
+/** a symbol together with what it is bound to, so `frames` of `{ frames: framesOf }` also stands for `framesOf` */
+function boundTo(symbol, checker) {
+    if (symbol === undefined) {
+        return [];
+    }
+    const declaration = symbol.declarations?.[0];
+    const value = declaration?.initializer === undefined ? declaration && checker.getShorthandAssignmentValueSymbol(declaration) : checker.getSymbolAtLocation(declaration.initializer);
+    return value === undefined ? [symbol] : [symbol, resolveAlias(value, checker)];
+}
+/* per program, what its modules export under a name, for a replacement the file does not import yet */
+const exportedNames = new WeakMap();
+/** what `name` stands for at `node`: what is in scope there, else what a module of the program exports under it */
+function rootSymbol(name, node, sourceCode, services) {
+    const checker = services.program.getTypeChecker();
+    let scope = sourceCode.getScope(node);
+    while (scope && !scope.set.has(name)) {
+        scope = scope.upper;
+    }
+    if (scope) {
+        return symbolOf(scope.set.get(name)?.defs[0]?.name, services, checker);
+    }
+    let known = exportedNames.get(services.program);
+    if (known === undefined) {
+        exportedNames.set(services.program, known = new Map());
+    }
+    if (!known.has(name)) {
+        const modules = services.program.getSourceFiles().map(file => checker.getSymbolAtLocation(file)).filter(m => m !== undefined);
+        known.set(name, modules.flatMap(m => checker.getExportsOfModule(m)).find(e => e.getName() === name));
+    }
+    return known.get(name);
+}
+/** the properties of what a symbol holds */
+function propertiesOf(symbol, checker) {
+    const declaration = symbol?.declarations?.[0];
+    return symbol === undefined || declaration === undefined ? [] : checker.getTypeOfSymbolAtLocation(symbol, declaration).getProperties();
+}
+/** each link of a dotted name, `Dataflow.origin`, as the symbols it resolves to: the name and what it is bound to */
+function resolveChain(chain, node, sourceCode, services) {
+    const checker = services.program.getTypeChecker();
+    const [root, ...members] = chain.split('.');
+    const links = [boundTo(rootSymbol(root, node, sourceCode, services), checker)];
+    for (const member of members) {
+        links.push(boundTo(propertiesOf(links[links.length - 1][0], checker).find(p => p.getName() === member), checker));
+    }
+    return links;
+}
+/** Every symbol the dotted names of a replacement resolve to, `REnvironment.frames` to `REnvironment`, its `frames`, and the function that member is bound to. */
+function symbolsNamedBy(replacement, node, sourceCode, services) {
+    return new Set((replacement.match(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/g) ?? []).flatMap(chain => resolveChain(chain, node, sourceCode, services).flat()));
+}
+/**
+ * The member of `replacement` that takes the place of `member` of `original`: the one of the same name, else the one
+ * bound to the same function under another name. `undefined` if the replacement has none, `null` if it cannot be told.
+ */
+function counterpartOf(original, member, replacement, sourceCode, services) {
+    const checker = services.program.getTypeChecker();
+    const target = resolveChain(replacement, original, sourceCode, services).at(-1)?.[0];
+    if (target === undefined) {
+        return null;
+    }
+    const offered = propertiesOf(target, checker);
+    const was = boundTo(propertiesOf(symbolOf(original, services, checker), checker).find(p => p.getName() === member), checker);
+    return (offered.find(p => p.getName() === member) ?? offered.find(p => boundTo(p, checker).some(s => was.includes(s))))?.getName();
+}
+/**
+ * Whether `node` sits in a function the replacement would call, where putting the replacement in would make that
+ * function call itself. A replacement can only call what it names: a function is excluded if it is declared or bound
+ * under one of those names, or, with types, if one of them resolves to it, wired up under another name or in another
+ * file. Both ask the code alone, never file paths, which differ between systems and how a file was opened.
+ */
+function insideReplacement(node, replacement, sourceCode, services) {
+    const names = new Set(replacement.match(/[A-Za-z_$][\w$]*/g) ?? []);
+    const ancestors = sourceCode.getAncestors(node);
+    const functions = ancestors.flatMap((fn, i) => fn.type === 'FunctionDeclaration' || fn.type === 'FunctionExpression' || fn.type === 'ArrowFunctionExpression' ? [nameOf(fn, ancestors[i - 1])] : [])
+        .filter((name) => name !== undefined);
+    if (functions.some(name => name.type === 'Identifier' && names.has(name.name))) {
+        return true;
+    }
+    if (services === undefined || functions.length === 0) {
+        return false;
+    }
+    const called = symbolsNamedBy(replacement, node, sourceCode, services);
+    const checker = services.program.getTypeChecker();
+    return functions.some(name => boundTo(symbolOf(name, services, checker), checker).some(symbol => called.has(symbol)));
+}
 /** The file a symbol is declared in. */
 function declarationFile(symbol) {
     return symbol?.declarations?.[0]?.getSourceFile()?.fileName;
@@ -74,7 +179,7 @@ function declarationFile(symbol) {
 /** 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) {
+        if (tag.name === UseInsteadTag) {
             return (tag.text ?? []).map(p => p.text).join('').trim();
         }
     }