@blumintinc/eslint-plugin-blumint 1.16.2 → 1.17.1

package/lib/rules/prefer-flat-transform-each-keys.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferFlatTransformEachKeys = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+// Propagation strategy shape signals: an object literal with one of these
+// properties (besides transformEach) is treated as a propagation strategy.
+const STRATEGY_SHAPE_KEYS = new Set([
+    'resolveAll',
+    'queryResolveAll',
+    'numericFieldPathConfig',
+    'upsert',
+    'sourceDeletionOverride',
+]);
+function isObjectExpression(node) {
+    return !!node && node.type === utils_1.AST_NODE_TYPES.ObjectExpression;
+}
+function isProperty(node) {
+    return node.type === utils_1.AST_NODE_TYPES.Property;
+}
+// Return the string name of a non-computed property key, or null.
+function getStaticKeyName(prop) {
+    if (prop.computed)
+        return null;
+    if (prop.key.type === utils_1.AST_NODE_TYPES.Identifier)
+        return prop.key.name;
+    if (prop.key.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof prop.key.value === 'string')
+        return prop.key.value;
+    return null;
+}
+// A key is a "dot-notation key" if it contains a dot (e.g., 'foo.bar').
+// Such keys represent leaf paths — their values can be any shape.
+function isDotNotationKey(keyName) {
+    return keyName.includes('.');
+}
+// Determine whether an object-expression property key is a computed key.
+// Computed keys (bracket notation, including template literals) represent
+// dynamic leaf paths and are therefore exempt from the flat-key requirement.
+// Template literal keys always have `computed: true` in the AST, so a single
+// check on `prop.computed` is sufficient.
+function isComputedKey(prop) {
+    return prop.computed;
+}
+// Find a direct Property child by name inside an ObjectExpression.
+function findProp(obj, name) {
+    for (const p of obj.properties) {
+        if (!isProperty(p))
+            continue;
+        const k = getStaticKeyName(p);
+        if (k === name)
+            return p;
+    }
+    return null;
+}
+// Determine whether an ObjectExpression looks like a propagation strategy:
+// it has a `transformEach` property AND at least one of the known strategy
+// shape keys.
+function isStrategyObject(obj) {
+    let hasTransformEach = false;
+    let hasStrategyKey = false;
+    for (const p of obj.properties) {
+        if (!isProperty(p))
+            continue;
+        const k = getStaticKeyName(p);
+        if (!k)
+            continue;
+        if (k === 'transformEach')
+            hasTransformEach = true;
+        if (STRATEGY_SHAPE_KEYS.has(k))
+            hasStrategyKey = true;
+    }
+    return hasTransformEach && hasStrategyKey;
+}
+// Return true if the strategy uses resolveSelf (deleted-source short-circuit,
+// so nested objects are safe). Checks: resolveAll's value is an Identifier
+// named 'resolveSelf'.
+function usesResolveSelf(obj) {
+    const resolveAllProp = findProp(obj, 'resolveAll');
+    if (!resolveAllProp)
+        return false;
+    const val = resolveAllProp.value;
+    return val.type === utils_1.AST_NODE_TYPES.Identifier && val.name === 'resolveSelf';
+}
+// Extract the effective "data" object from a return value:
+// - If the returned object has an `afterData` property, return its value
+//   (since the outer object is a structural wrapper, not a propagation map).
+// - Otherwise return the object itself.
+function getDataObject(obj) {
+    const afterDataProp = findProp(obj, 'afterData');
+    if (afterDataProp) {
+        const val = afterDataProp.value;
+        if (isObjectExpression(val))
+            return val;
+        // afterData exists but its value isn't a literal (e.g. a variable) — skip.
+        return null;
+    }
+    return obj;
+}
+// Check whether a variable-binding return follows the pattern:
+//   const result = { ... };
+//   return result;
+// Returns the initialiser ObjectExpression if found, otherwise null.
+function resolveVariableBinding(returnArg, funcBody) {
+    if (returnArg.type !== utils_1.AST_NODE_TYPES.Identifier)
+        return null;
+    const varName = returnArg.name;
+    // Walk the statements in the function body looking for a single const/let
+    // initialisation whose id matches varName.
+    for (const stmt of funcBody.body) {
+        if (stmt.type !== utils_1.AST_NODE_TYPES.VariableDeclaration)
+            continue;
+        for (const decl of stmt.declarations) {
+            if (decl.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                decl.id.name === varName &&
+                decl.init &&
+                isObjectExpression(decl.init)) {
+                return decl.init;
+            }
+        }
+    }
+    return null;
+}
+// Report nested-object properties in a data object (the actual propagation
+// map, after afterData unwrapping). A property is flagged when:
+//   - its key is a simple non-dot-notation identifier/string
+//   - its value is an ObjectExpression
+function checkDataObject(dataObj, report) {
+    for (const prop of dataObj.properties) {
+        if (!isProperty(prop))
+            continue;
+        if (isComputedKey(prop))
+            continue;
+        const keyName = getStaticKeyName(prop);
+        if (keyName === null)
+            continue;
+        // Dot-notation string keys represent leaf paths — their values may be
+        // any shape (the value IS the leaf data).
+        if (isDotNotationKey(keyName))
+            continue;
+        // Flag when the value is a nested object literal.
+        if (isObjectExpression(prop.value)) {
+            report(prop);
+        }
+    }
+}
+// Analyse a function body (BlockStatement) for return statements that produce
+// nested objects, and report each violation.
+function analyzeBlockBody(body, report) {
+    for (const stmt of body.body) {
+        if (stmt.type !== utils_1.AST_NODE_TYPES.ReturnStatement)
+            continue;
+        if (!stmt.argument)
+            continue;
+        let retObj = null;
+        if (isObjectExpression(stmt.argument)) {
+            retObj = stmt.argument;
+        }
+        else {
+            // Try single-binding pattern: const x = {...}; return x;
+            retObj = resolveVariableBinding(stmt.argument, body);
+        }
+        if (!retObj)
+            continue;
+        const dataObj = getDataObject(retObj);
+        if (!dataObj)
+            continue;
+        checkDataObject(dataObj, report);
+    }
+}
+exports.preferFlatTransformEachKeys = (0, createRule_1.createRule)({
+    name: 'prefer-flat-transform-each-keys',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Warn when transformEach in a propagation strategy returns nested object values instead of flat dot-notation keys.',
+            recommended: 'warn',
+        },
+        fixable: undefined,
+        schema: [],
+        messages: {
+            preferFlatTransformEachKeys: "Avoid returning nested objects from transformEach. Use flat dot-notation keys instead (e.g., 'parent.child.key' instead of { parent: { child: { key } } }). Nested objects cause FieldValue.delete() at the parent key on source deletion, wiping the entire sub-tree instead of just the propagated fields. If nesting is intentional (e.g., wiping an entire sub-tree), disable this rule with a comment explaining why.",
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        // Core detection is purely syntactic and works without type info.
+        // The parserServices guard below mirrors no-entire-object-hook-deps.ts so
+        // the rule degrades gracefully in test environments without parserOptions.project.
+        // Currently only the syntactic path is exercised; type-aware enhancement
+        // (e.g. resolving identifier types) can be wired in here when needed.
+        void context.parserServices; // accessed for future type-aware enhancement
+        return {
+            // Visit every ObjectExpression. If it looks like a propagation strategy,
+            // find the transformEach function and check its return values.
+            ObjectExpression(node) {
+                if (!isStrategyObject(node))
+                    return;
+                if (usesResolveSelf(node))
+                    return;
+                const transformEachProp = findProp(node, 'transformEach');
+                if (!transformEachProp)
+                    return;
+                const fn = transformEachProp.value;
+                const report = (violatingNode) => {
+                    context.report({
+                        node: violatingNode,
+                        messageId: 'preferFlatTransformEachKeys',
+                    });
+                };
+                if (fn.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    fn.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+                    const body = fn.body;
+                    if (isObjectExpression(body)) {
+                        // Arrow function with implicit return: () => ({ ... })
+                        const dataObj = getDataObject(body);
+                        if (dataObj)
+                            checkDataObject(dataObj, report);
+                    }
+                    else if (body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                        analyzeBlockBody(body, report);
+                    }
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=prefer-flat-transform-each-keys.js.map

package/lib/rules/prefer-getter-over-parameterless-method.d.ts

@@ -1,6 +1,7 @@
 type OptionShape = {
     stripPrefixes?: string[];
     ignoredMethods?: string[];
+    factoryMethods?: string[];
     ignoreAsync?: boolean;
     ignoreVoidReturn?: boolean;
     ignoreAbstract?: boolean;

package/lib/rules/prefer-getter-over-parameterless-method.js

@@ -34,10 +34,17 @@ const DEFAULT_IGNORED_METHODS = [
     'parse',
     'stringify',
 ];
+/**
+ * Builder/factory terminal methods whose external callers (in other files)
+ * would break if converted to getters. These are imperative actions, not
+ * computed properties — per origin issue #990 edge case #4.
+ */
+const DEFAULT_FACTORY_METHODS = ['build', 'create', 'make'];
 const SIDE_EFFECT_TAGS = ['sideEffect', 'sideEffects', 'mutates'];
 const DEFAULT_OPTIONS = {
     stripPrefixes: DEFAULT_PREFIXES,
     ignoredMethods: DEFAULT_IGNORED_METHODS,
+    factoryMethods: DEFAULT_FACTORY_METHODS,
     ignoreAsync: true,
     ignoreVoidReturn: true,
     ignoreAbstract: true,
@@ -166,6 +173,10 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                         type: 'array',
                         items: { type: 'string' },
                     },
+                    factoryMethods: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
                     ignoreAsync: {
                         type: 'boolean',
                     },
@@ -199,8 +210,10 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
             ...userOptions,
             stripPrefixes: userOptions.stripPrefixes ?? DEFAULT_OPTIONS.stripPrefixes,
             ignoredMethods: userOptions.ignoredMethods ?? DEFAULT_OPTIONS.ignoredMethods,
+            factoryMethods: userOptions.factoryMethods ?? DEFAULT_OPTIONS.factoryMethods,
         };
         const ignoredMethods = new Set(config.ignoredMethods);
+        const factoryMethods = new Set(config.factoryMethods);
         const prefixList = config.stripPrefixes;
         const sourceCode = context.getSourceCode();
         const ignoredTraversalKeys = new Set(['parent', 'loc', 'range']);
@@ -357,6 +370,28 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * Returns true when the method body contains a ThrowStatement that is
+         * directly in the method's own scope (not inside a nested function/arrow).
+         * A method that can throw at the top level is an imperative assertion, not
+         * a computed property, so it must not become a getter.
+         */
+        function containsTopLevelThrow(body) {
+            const stack = [...body.body];
+            while (stack.length) {
+                const current = stack.pop();
+                // Do not descend into nested function-like scopes — a throw there is
+                // that nested function's concern, not the method's.
+                if (isFunctionLikeNode(current)) {
+                    continue;
+                }
+                if (current.type === utils_1.AST_NODE_TYPES.ThrowStatement) {
+                    return true;
+                }
+                pushChildNodes(current, stack);
+            }
+            return false;
+        }
         function suggestName(name) {
             for (const prefix of prefixList) {
                 if (name.startsWith(prefix) &&
@@ -562,6 +597,11 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                 const name = node.key.name;
                 if (ignoredMethods.has(name))
                     return;
+                // Factory/builder terminal methods are imperative actions (issue #990 #4).
+                // Exemption takes precedence over stripPrefixes so names like "build"
+                // are never prefix-stripped into a getter candidate.
+                if (factoryMethods.has(name))
+                    return;
                 if (hasOverloadSignatures(node))
                     return;
                 const body = node.value.body;
@@ -572,6 +612,10 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                     return;
                 if (config.respectJsDocSideEffects && hasSideEffectTag(node))
                     return;
+                // A method that throws at the top level is an imperative assertion or
+                // command, not a computed property — getters must be pure/non-throwing.
+                if (containsTopLevelThrow(body))
+                    return;
                 const sideEffectReason = analyzeMutations(body);
                 const suggestedName = suggestName(name);
                 candidates.push({ node, sideEffectReason, suggestedName });

package/lib/rules/prefer-spread-over-reassembly.d.ts

@@ -0,0 +1,5 @@
+type Options = [{
+    minFields?: number;
+}];
+export declare const preferSpreadOverReassembly: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferSpread", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};