@blumintinc/eslint-plugin-blumint 1.20.153 → 1.20.154

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.153',
+        version: '1.20.154',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/parallelize-async-operations.js

@@ -1127,9 +1127,54 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
             return variable.defs.every((definition) => definition.name.range[0] >= root.range[0] &&
                 definition.name.range[1] <= root.range[1]);
         }
+        /**
+         * Records the instance slot a method call MUTATES THROUGH ITS RECEIVER.
+         * `this.accumulated.set(doc, 1)` publishes to `this.accumulated` exactly as
+         * `this.accumulated = next` does, but it is a CallExpression rather than an
+         * assignment, so the assignment-shaped visit below never sees it. A sweep
+         * that fills an accumulator through the accumulator's own API then reads as
+         * writing nothing, a later await that reads that slot is classified
+         * independent, and the rewrite runs the read against the still-empty
+         * accumulator. (#2017)
+         *
+         * ANY method invoked on the slot counts, rather than a list of known
+         * mutators. The receiver is already the unit barrier 7 treats as ordered,
+         * and a domain `append`/`record`/`write` mutates its receiver exactly as
+         * `set` does, so naming a subset would leave the same silent reorder
+         * reachable under a different spelling. Over-recording a pure
+         * `this.cache.size()` costs only a missed parallelization, which is the
+         * trade this rule takes everywhere.
+         *
+         * Only calls in DEFERRED position qualify -- those the traversal reaches by
+         * crossing into a callback or a resolved callee body. A call spelled in the
+         * operand's own text already carries a receiver key, so barriers 7 and 12
+         * order it with carve-outs calibrated against exactly this: they return no
+         * key for a call-produced receiver (`this.realtimeDb.ref(pathA).remove()`)
+         * or a varying subscript (`this.handlers[0].read()`), which is what keeps
+         * two argument-disambiguated operations on one handle parallelizable.
+         * Recording those same calls here would mint a write on the shared prefix
+         * and silently override that calibration. Behind a callback no receiver key
+         * exists at the operand level at all, so nothing is overridden -- that is
+         * the blind spot, and its whole extent.
+         *
+         * The BARE instance (`this.storeAll()`) is excluded for the same reason:
+         * recording it would mint a wildcard write overlapping every slot, turning
+         * the precise treatment those barriers give it into a blanket one.
+         */
+        function collectMutatedReceiver(call, targets) {
+            const callee = unwrapExpression(call.callee);
+            if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+                return;
+            }
+            const receiverPath = getInstancePathKey(callee.object);
+            if (receiverPath !== null && receiverPath !== INSTANCE_RECEIVER_KEY) {
+                targets.instancePaths.push(receiverPath);
+            }
+        }
         /**
          * Collects the state an awaited expression WRITES: the identifier names it
-         * assigns, and the instance paths (`this.mutator`) it assigns. (#1924)
+         * assigns, and the instance paths (`this.mutator`) it assigns or mutates
+         * through a method call. (#1924, #2017)
          *
          * The traversal deliberately crosses function boundaries, which is the
          * opposite of what containsSuspendingAwait needs: the write that matters
@@ -1144,7 +1189,7 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
          */
         function getAssignedState(node) {
             const targets = { identifiers: [], instancePaths: [] };
-            const visit = (current) => {
+            const visit = (current, deferred) => {
                 if (current.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
                     collectAssignmentTarget(current.left, targets);
                 }
@@ -1158,6 +1203,10 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     // iteration; only the declaration form introduces a fresh local.
                     collectAssignmentTarget(current.left, targets);
                 }
+                else if (deferred && current.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                    collectMutatedReceiver(current, targets);
+                }
+                const childrenDeferred = deferred || FUNCTION_BOUNDARY_TYPES.has(current.type);
                 for (const key in current) {
                     if (key === 'parent' || key === 'range' || key === 'loc')
                         continue;
@@ -1167,16 +1216,19 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     if (Array.isArray(child)) {
                         for (const item of child) {
                             if (item && typeof item === 'object' && 'type' in item) {
-                                visit(item);
+                                visit(item, childrenDeferred);
                             }
                         }
                     }
                     else if ('type' in child) {
-                        visit(child);
+                        visit(child, childrenDeferred);
                     }
                 }
             };
-            visit(node);
+            // A resolved callee body is itself deferred relative to the run, and
+            // entering it crosses its own function boundary, so the flag lifts here
+            // exactly as it does for a callback. (#1989, #2017)
+            visit(node, false);
             const names = new Set();
             for (const target of targets.identifiers) {
                 if (!isDeclaredWithin(target, node)) {
@@ -1445,11 +1497,26 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     ]),
                 };
             });
+            //
+            // The READ side resolves the callee body for the same reason the write
+            // side does, and the omission was the other half of #2017: `await
+            // this.storeAll()` spells only the slot `this.storeAll`, so a preceding
+            // write to `this.accumulated` -- the slot `storeAll` actually reads --
+            // compares as disjoint and the pair parallelizes. Reading the resolved
+            // body restores the edge. An unresolvable callee (inherited, computed,
+            // imported) yields null and leaves the operand keyed on its own text, as
+            // before.
             const readInstancePaths = awaitNodes.map((node) => {
                 const awaitExpr = getAwaitExpression(node);
-                return awaitExpr
-                    ? getInstancePathKeys(awaitExpr.argument)
-                    : new Set();
+                if (!awaitExpr) {
+                    return new Set();
+                }
+                const read = getInstancePathKeys(awaitExpr.argument);
+                const calleeFunction = resolveCalleeFunction(awaitExpr);
+                if (!calleeFunction) {
+                    return read;
+                }
+                return new Set([...read, ...getInstancePathKeys(calleeFunction)]);
             });
             for (let i = 1; i < awaitNodes.length; i++) {
                 const currentIds = allIdentifiers[i];

package/lib/utils/docsFixtures.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared machinery for reading the documented examples out of `docs/rules/*.md`
+ * and linting them.
+ *
+ * Extracted so that more than one guard can ask a question of the SAME parsed
+ * corpus. `docs-examples-conformance` asks whether a block satisfies its own
+ * rule; `docs-correct-block-regression` asks whether the blocks #1982 fixed
+ * still satisfy the OTHER rule that used to report on them. Hand-rolling the
+ * fence walker or the candidate-filename list a second time is how two guards
+ * come to disagree about which blocks exist — the failure `fixtureCorpus.ts`
+ * exists to prevent on the RuleTester side, and the reason four guards there
+ * inherited the same two silent losses (#1984).
+ *
+ * The filename list in particular is load-bearing and must not be duplicated:
+ * many rules key off the path, so judging a block under a path the rule was
+ * never meant to see manufactures a failure.
+ */
+export declare const PREFIX = "@blumintinc/blumint/";
+export declare const DOCS_DIR: string;
+export declare const pageExists: (rule: string) => boolean;
+export declare const readPage: (rule: string) => string | null;
+/** Fence languages that hold lintable TypeScript. */
+export declare const LINTABLE_LANGS: Set<string>;
+/**
+ * Candidate filenames, tried in order. Many rules key off the path (cloud
+ * function entry points, test-file exemptions, component directories), so a
+ * single hard-coded filename would make correct examples report for reasons the
+ * doc never claimed.
+ */
+export declare const TS_CANDIDATES: string[];
+export declare const TSX_CANDIDATES: string[];
+/**
+ * Rules that match on path segments need a rooted path — `functions/src/types/x.ts`
+ * relative does not satisfy the same check that `/repo/functions/src/types/x.ts`
+ * does, which would fail a doc example for a reason the doc never claimed.
+ */
+export declare const ROOT = "/repo/";
+export declare const anchor: (p: string) => string;
+export type Block = {
+    /**
+     * `null` for a fence under no example heading. Such blocks are kept rather
+     * than dropped: a page whose fences all come back unlabelled is a detection
+     * failure, and dropping them made it indistinguishable from a page that
+     * documents no examples at all (#1499).
+     */
+    polarity: 'correct' | 'incorrect' | null;
+    lang: string;
+    code: string;
+    line: number;
+};
+/**
+ * Classify an example heading.
+ *
+ * Only H2+ headings count: the H1 title ends with the rule id, and rule names
+ * routinely contain `prefer`, `valid`, or `no`, which would otherwise classify
+ * every block in the intro prose. The rule-id parenthetical is stripped for the
+ * same reason.
+ *
+ * Order matters — "incorrect" contains "correct" and "invalid" contains "valid",
+ * so the negative spellings must be tested first.
+ */
+export declare function headingPolarity(line: string): Block['polarity'] | null;
+/**
+ * Pull every fenced code block, tagged with the polarity of the example heading
+ * it sits under (`null` when it sits under none).
+ *
+ * Polarity is inherited by DEEPER headings, because docs routinely split an
+ * example section into named cases (`#### Option 1: …` under `### Examples of
+ * correct code`). Treating such a sub-heading as the end of the section dropped
+ * every block beneath it, which is how three whole pages asserted nothing.
+ */
+export declare function extractBlocks(md: string): Block[];
+/**
+ * Docs declare the context a snippet assumes inside the snippet itself:
+ * `// File: functions/src/...` (or a bare path comment) for path-sensitive
+ * rules, and `// eslint-options: {...}` for an example that only holds under a
+ * non-default option. Honouring both is what lets every correct block be
+ * enforced without exempting the awkward ones.
+ */
+export declare function filenameHint(code: string): string | null;
+export declare function optionsHint(code: string): unknown | null;
+export type LintResult = {
+    reports: string[];
+    /** 1-based lines of the same reports, for segment attribution (#1622). */
+    reportLines: number[];
+    skipped: boolean;
+    reason?: string;
+};
+export declare function lintBlock(ruleName: string, filename: string, code: string, options: unknown | null): LintResult;

package/lib/utils/docsFixtures.js

@@ -0,0 +1,244 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintBlock = exports.optionsHint = exports.filenameHint = exports.extractBlocks = exports.headingPolarity = exports.anchor = exports.ROOT = exports.TSX_CANDIDATES = exports.TS_CANDIDATES = exports.LINTABLE_LANGS = exports.readPage = exports.pageExists = exports.DOCS_DIR = exports.PREFIX = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const eslint_1 = require("eslint");
+/* eslint-disable @typescript-eslint/no-var-requires */
+const plugin = require('../index');
+const tsParser = require('@typescript-eslint/parser');
+/* eslint-enable @typescript-eslint/no-var-requires */
+/**
+ * Shared machinery for reading the documented examples out of `docs/rules/*.md`
+ * and linting them.
+ *
+ * Extracted so that more than one guard can ask a question of the SAME parsed
+ * corpus. `docs-examples-conformance` asks whether a block satisfies its own
+ * rule; `docs-correct-block-regression` asks whether the blocks #1982 fixed
+ * still satisfy the OTHER rule that used to report on them. Hand-rolling the
+ * fence walker or the candidate-filename list a second time is how two guards
+ * come to disagree about which blocks exist — the failure `fixtureCorpus.ts`
+ * exists to prevent on the RuleTester side, and the reason four guards there
+ * inherited the same two silent losses (#1984).
+ *
+ * The filename list in particular is load-bearing and must not be duplicated:
+ * many rules key off the path, so judging a block under a path the rule was
+ * never meant to see manufactures a failure.
+ */
+exports.PREFIX = '@blumintinc/blumint/';
+exports.DOCS_DIR = path_1.default.join(__dirname, '../../docs/rules');
+const pageExists = (rule) => fs_1.default.existsSync(path_1.default.join(exports.DOCS_DIR, `${rule}.md`));
+exports.pageExists = pageExists;
+const readPage = (rule) => (0, exports.pageExists)(rule)
+    ? fs_1.default.readFileSync(path_1.default.join(exports.DOCS_DIR, `${rule}.md`), 'utf8')
+    : null;
+exports.readPage = readPage;
+/** Fence languages that hold lintable TypeScript. */
+exports.LINTABLE_LANGS = new Set([
+    'ts',
+    'tsx',
+    'js',
+    'jsx',
+    'typescript',
+    'javascript',
+    '',
+]);
+/**
+ * Candidate filenames, tried in order. Many rules key off the path (cloud
+ * function entry points, test-file exemptions, component directories), so a
+ * single hard-coded filename would make correct examples report for reasons the
+ * doc never claimed.
+ */
+exports.TS_CANDIDATES = [
+    'src/util/helper.ts',
+    'functions/src/callable/handler.f.ts',
+    'functions/src/util/helper.ts',
+    'src/util/helper.test.ts',
+    'src/components/Widget.tsx',
+];
+exports.TSX_CANDIDATES = [
+    'src/components/Widget.tsx',
+    'src/pages/index.tsx',
+];
+/**
+ * Rules that match on path segments need a rooted path — `functions/src/types/x.ts`
+ * relative does not satisfy the same check that `/repo/functions/src/types/x.ts`
+ * does, which would fail a doc example for a reason the doc never claimed.
+ */
+exports.ROOT = '/repo/';
+const anchor = (p) => (p.startsWith('/') ? p : exports.ROOT + p);
+exports.anchor = anchor;
+/**
+ * Classify an example heading.
+ *
+ * Only H2+ headings count: the H1 title ends with the rule id, and rule names
+ * routinely contain `prefer`, `valid`, or `no`, which would otherwise classify
+ * every block in the intro prose. The rule-id parenthetical is stripped for the
+ * same reason.
+ *
+ * Order matters — "incorrect" contains "correct" and "invalid" contains "valid",
+ * so the negative spellings must be tested first.
+ */
+function headingPolarity(line) {
+    if (!/^#{2,6}\s/.test(line))
+        return null;
+    const text = line
+        .replace(/^#{2,6}\s*/, '')
+        .replace(/\(`?@blumintinc\/blumint\/[^)]*`?\)/g, '')
+        .toLowerCase();
+    if (/❌|👎|\bincorrect\b|\binvalid\b|\bbad\b|\bwrong\b/.test(text))
+        return 'incorrect';
+    if (/✅|👍|\bcorrect\b|\bvalid\b|\bgood\b/.test(text))
+        return 'correct';
+    return null;
+}
+exports.headingPolarity = headingPolarity;
+/**
+ * Pull every fenced code block, tagged with the polarity of the example heading
+ * it sits under (`null` when it sits under none).
+ *
+ * Polarity is inherited by DEEPER headings, because docs routinely split an
+ * example section into named cases (`#### Option 1: …` under `### Examples of
+ * correct code`). Treating such a sub-heading as the end of the section dropped
+ * every block beneath it, which is how three whole pages asserted nothing.
+ */
+function extractBlocks(md) {
+    const lines = md.split('\n');
+    const blocks = [];
+    let polarity = null;
+    let polarityDepth = 0;
+    let fence = null;
+    let buf = [];
+    let lang = '';
+    let startLine = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const fenceMatch = /^\s*(`{3,}|~{3,})(.*)$/.exec(line);
+        if (fence) {
+            if (fenceMatch &&
+                fenceMatch[1][0] === fence[0] &&
+                fenceMatch[1].length >= fence.length) {
+                blocks.push({
+                    polarity,
+                    lang: lang.trim().toLowerCase(),
+                    code: buf.join('\n'),
+                    line: startLine,
+                });
+                fence = null;
+                buf = [];
+            }
+            else {
+                buf.push(line);
+            }
+            continue;
+        }
+        const heading = /^(#{1,6})\s/.exec(line);
+        if (heading) {
+            const depth = heading[1].length;
+            const own = headingPolarity(line);
+            if (own) {
+                polarity = own;
+                polarityDepth = depth;
+            }
+            else if (!(polarity && depth > polarityDepth)) {
+                // A sibling or shallower heading ends the example section; a deeper one
+                // is a named case inside it and keeps the section's polarity.
+                polarity = null;
+                polarityDepth = 0;
+            }
+            continue;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1];
+            lang = fenceMatch[2] || '';
+            startLine = i + 1;
+            buf = [];
+        }
+    }
+    return blocks;
+}
+exports.extractBlocks = extractBlocks;
+/**
+ * Docs declare the context a snippet assumes inside the snippet itself:
+ * `// File: functions/src/...` (or a bare path comment) for path-sensitive
+ * rules, and `// eslint-options: {...}` for an example that only holds under a
+ * non-default option. Honouring both is what lets every correct block be
+ * enforced without exempting the awkward ones.
+ */
+function filenameHint(code) {
+    const explicit = /^\s*(?:\/\/|\/\*)\s*File:\s*([^\s*]+)/im.exec(code);
+    if (explicit)
+        return (0, exports.anchor)(explicit[1].replace(/^\.\//, ''));
+    const firstLine = code.split('\n').find((l) => l.trim().length > 0) || '';
+    const bare = /^\s*\/\/\s*((?:[\w.-]+\/)+[\w.-]+\.tsx?)\b/.exec(firstLine);
+    return bare ? (0, exports.anchor)(bare[1]) : null;
+}
+exports.filenameHint = filenameHint;
+function optionsHint(code) {
+    const m = /^\s*\/\/\s*eslint-options:\s*(\{.*\})\s*$/im.exec(code);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        throw new Error(`malformed // eslint-options: ${m[1]}`);
+    }
+}
+exports.optionsHint = optionsHint;
+const linter = new eslint_1.Linter();
+for (const [name, rule] of Object.entries(plugin.rules)) {
+    linter.defineRule(exports.PREFIX + name, rule);
+}
+linter.defineParser('ts', tsParser);
+function lintBlock(ruleName, filename, code, options) {
+    const config = {
+        parser: 'ts',
+        parserOptions: {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            ecmaFeatures: { jsx: filename.endsWith('.tsx') },
+        },
+        rules: {
+            [exports.PREFIX + ruleName]: options
+                ? ['error', options]
+                : 'error',
+        },
+    };
+    let messages;
+    try {
+        messages = linter.verify(code, config, { filename });
+    }
+    catch (error) {
+        // A rule needing type information throws without `parserOptions.project`,
+        // which the RuleTester cannot supply; such rules are out of scope here.
+        return {
+            reports: [],
+            reportLines: [],
+            skipped: true,
+            reason: `the rule threw: ${error.message}`,
+        };
+    }
+    // A block that does not parse never ran the rule. That is not a pass — see
+    // UNCHECKABLE_BLOCKS.
+    const fatal = messages.find((m) => m.fatal);
+    if (fatal) {
+        return {
+            reports: [],
+            reportLines: [],
+            skipped: true,
+            reason: `parse failure at block line ${fatal.line}: ${fatal.message}`,
+        };
+    }
+    const mine = messages.filter((m) => m.ruleId === exports.PREFIX + ruleName);
+    return {
+        reports: mine.map((m) => `line ${m.line}: ${m.message}`),
+        reportLines: mine.map((m) => m.line),
+        skipped: false,
+    };
+}
+exports.lintBlock = lintBlock;
+//# sourceMappingURL=docsFixtures.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.153",
+  "version": "1.20.154",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.20.154",
+    "date": "2026-08-15T03:47:51.570Z",
+    "rules": [
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          2017
+        ],
+        "summary": "order callback-deferred instance mutations against later reads (closes #2017)"
+      }
+    ]
+  },
   {
     "version": "1.20.153",
     "date": "2026-08-14T20:21:23.691Z",