@eagleoutice/eslint-config-flowr 2.0.2 → 2.1.3

package/rules/util.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers of the flowR rules.
+ * Tags: `@useInstead <target>` names a replacement, `@lintIgnore [ids]` silences 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 `@lintIgnore`, or in a file whose header comment
+ * carries it. Guarded by one string search, so untagged files pay nothing.
+ */
+export declare function suppressed(context: Rule.RuleContext, node: Rule.Node, ids: readonly string[]): boolean;
+/** The symbol an ESTree node resolves to, with import aliases followed. */
+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,113 @@
+"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_TAG = '@lintIgnore';
+/* ts.SymbolFlags.Alias, spelled out to keep typescript out of the dependencies */
+const ALIAS_FLAG = 1 << 21;
+/** The type-aware services, or `undefined` if the file is parsed without a program. */
+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;
+    }
+    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 `@lintIgnore`, or in a file whose header comment
+ * carries it. Guarded by one string search, so untagged files pay nothing.
+ */
+function suppressed(context, node, ids) {
+    const sourceCode = context.sourceCode;
+    if (!sourceCode.text.includes(SUPPRESS_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,13 @@
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+   "tagDefinitions": [
+      {
+         "tagName": "@useInstead",
+         "syntaxKind": "block"
+      },
+      {
+         "tagName": "@lintIgnore",
+         "syntaxKind": "block"
+      }
+   ]
+}