@eagleoutice/eslint-config-flowr 2.1.10 → 2.1.11

package/README.md

@@ -27,6 +27,7 @@ below `test/`.
 | :-- | :-- | :-- |
 | `flowr/use-instead` | the `@useInstead` tag | a reference to what a helper object replaced |
 | `flowr/replacement-pattern` | [`patterns.ts`](patterns.ts) | a shape of code with a helper equivalent |
+| `flowr/no-semantic-widening` | the types | a value of a `__brand`ed type (`NodeId`, `BrandedIdentifier`, ...) that silently becomes a plain `string` or `number`, also within `string[]`, `Set<string>`, or `Map<string, ...>` |
 
 Both fix in place when every name the replacement needs is already in scope, and offer an editor suggestion otherwise,
 since a fixer cannot add the missing import. A type-only binding of the right name does not count.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/eslint-config-flowr",
-  "version": "2.1.10",
+  "version": "2.1.11",
   "description": "Linting rules for flowr and friends",
   "license": "ISC",
   "repository": {

package/plugin.d.ts

@@ -6,6 +6,7 @@ declare const plugin: {
         'use-instead': import("eslint").Rule.RuleModule;
         'replacement-pattern': import("eslint").Rule.RuleModule;
         'file-naming': import("eslint").Rule.RuleModule;
+        'no-semantic-widening': import("eslint").Rule.RuleModule;
     };
 };
 export = plugin;

package/plugin.js

@@ -6,12 +6,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const replacement_pattern_1 = __importDefault(require("./rules/replacement-pattern"));
 const use_instead_1 = __importDefault(require("./rules/use-instead"));
 const file_naming_1 = __importDefault(require("./rules/file-naming"));
+const no_semantic_widening_1 = __importDefault(require("./rules/no-semantic-widening"));
 const plugin = {
     meta: { name: '@eagleoutice/eslint-config-flowr' },
     rules: {
         'use-instead': use_instead_1.default,
         'replacement-pattern': replacement_pattern_1.default,
-        'file-naming': file_naming_1.default
+        'file-naming': file_naming_1.default,
+        'no-semantic-widening': no_semantic_widening_1.default
     }
 };
 module.exports = plugin;

package/rules/no-semantic-widening.d.ts

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

package/rules/no-semantic-widening.js

@@ -0,0 +1,108 @@
+"use strict";
+const util_1 = require("./util");
+/* ts.TypeFlags and ts.SymbolFlags, spelled out to keep typescript out of the dependencies */
+const StringFlag = 1 << 2;
+const NumberFlag = 1 << 3;
+const UndefinedFlag = 1 << 15;
+const NullFlag = 1 << 16;
+const TypeParameterFlag = 1 << 18;
+const BrandProperty = '__brand';
+const Collections = new Set(['Array', 'ReadonlyArray', 'Set', 'ReadonlySet', 'Map', 'ReadonlyMap', 'DefaultMap']);
+function membersOf(type) {
+    return (type.isUnion() ? type.types : [type]).filter(t => (t.flags & (UndefinedFlag | NullFlag)) === 0);
+}
+/** A semantic type carries a brand: `string & { __brand?: 'node-id' }`. */
+function isSemantic(type, checker) {
+    const members = membersOf(type);
+    return members.length > 0 && members.every(t => checker.getPropertyOfType(t, BrandProperty) !== undefined);
+}
+function isPlainPrimitive(type, checker) {
+    const members = membersOf(type);
+    return members.length > 0 && members.every(t => (t.flags & (StringFlag | NumberFlag)) !== 0 && checker.getPropertyOfType(t, BrandProperty) === undefined);
+}
+function collectionArguments(type, checker) {
+    const [member] = membersOf(type);
+    const name = member?.getSymbol()?.getName();
+    return name !== undefined && Collections.has(name) ? checker.getTypeArguments(member) : undefined;
+}
+/** Whether a value of type `source` loses its meaning in a place of type `target`, on its own or inside a collection. */
+function widens(source, target, checker) {
+    if (isSemantic(source, checker)) {
+        return isPlainPrimitive(target, checker);
+    }
+    const from = collectionArguments(source, checker);
+    const to = collectionArguments(target, checker);
+    return from !== undefined && to !== undefined && from.some((f, i) => to[i] !== undefined && widens(f, to[i], checker));
+}
+/** A parameter a library declares as a plain string takes any string, while one of a collection (`Set<string>`) states what the code chose. */
+function acceptedByLibrary(call, argument, tsCall, checker) {
+    if (call.type !== 'CallExpression' && call.type !== 'NewExpression') {
+        return false;
+    }
+    const declaration = checker.getResolvedSignature(tsCall)?.declaration;
+    if (declaration?.getSourceFile()?.fileName.includes('/node_modules/') !== true) {
+        return false;
+    }
+    const parameters = declaration.parameters;
+    const parameter = parameters?.[Math.min(call.arguments.indexOf(argument), parameters.length - 1)];
+    return parameter !== undefined && (checker.getTypeAtLocation(parameter).flags & TypeParameterFlag) === 0;
+}
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'a value of a semantic type (NodeId, BrandedIdentifier, ...) must not silently become a plain string or number' },
+        messages: {
+            widens: 'This turns a {{source}} into a plain {{target}}. Use a semantic type for what receives it, or cast explicitly if the meaning really ends here.'
+        },
+        schema: []
+    },
+    create(context) {
+        const services = (0, util_1.typeServices)(context);
+        if (!services) {
+            return {};
+        }
+        const checker = services.program.getTypeChecker();
+        const check = (node) => {
+            if (!node || node.type === 'SpreadElement') {
+                return;
+            }
+            const tsNode = services.esTreeNodeToTSNodeMap.get(node);
+            const target = checker.getContextualType(tsNode);
+            if (target === undefined) {
+                return;
+            }
+            const source = checker.getTypeAtLocation(tsNode);
+            if (!widens(source, target, checker) || (0, util_1.suppressed)(context, node, ['no-semantic-widening'])) {
+                return;
+            }
+            const parent = node.parent;
+            if (acceptedByLibrary(parent, node, services.esTreeNodeToTSNodeMap.get(parent), checker)) {
+                return;
+            }
+            context.report({ node, messageId: 'widens', data: { source: checker.typeToString(source), target: checker.typeToString(target) } });
+        };
+        const checkArguments = (call) => call.arguments.forEach(check);
+        return {
+            CallExpression: checkArguments,
+            NewExpression: checkArguments,
+            ReturnStatement: node => check(node.argument),
+            VariableDeclarator(node) {
+                check(node.init);
+            },
+            AssignmentExpression(node) {
+                if (node.operator === '=') {
+                    check(node.right);
+                }
+            },
+            Property(node) {
+                check(node.value);
+            },
+            ArrowFunctionExpression(node) {
+                if (node.body.type !== 'BlockStatement') {
+                    check(node.body);
+                }
+            }
+        };
+    }
+};
+module.exports = rule;

package/rules/ts-types.d.ts

@@ -23,12 +23,30 @@ export interface TsSymbol {
     getJsDocTags(checker: TsTypeChecker): readonly TsJsDocTag[];
 }
 export interface TsType {
+    flags: number;
+    types?: readonly TsType[];
     getProperties(): readonly TsSymbol[];
+    getSymbol(): TsSymbol | undefined;
+    isUnion(): this is TsType & {
+        types: readonly TsType[];
+    };
+}
+/** What a call resolves to, its parameters only for a declaration in code. */
+export interface TsSignature {
+    declaration?: TsDeclaration & {
+        parameters?: readonly unknown[];
+    };
 }
 export interface TsTypeChecker {
     getSymbolAtLocation(node: unknown): TsSymbol | undefined;
     getAliasedSymbol(symbol: TsSymbol): TsSymbol;
     getTypeOfSymbolAtLocation(symbol: TsSymbol, location: TsDeclaration): TsType;
+    getTypeAtLocation(node: unknown): TsType;
+    getContextualType(node: unknown): TsType | undefined;
+    getPropertyOfType(type: TsType, name: string): TsSymbol | undefined;
+    getTypeArguments(type: TsType): readonly TsType[];
+    getResolvedSignature(node: unknown): TsSignature | undefined;
+    typeToString(type: TsType): string;
     /** what a module exports, its symbol taken from the source file */
     getExportsOfModule(module: TsSymbol): readonly TsSymbol[];
     /** the variable a shorthand property `{ framesOf }` stands for */