@ethisyscore/eslint-plugin-coreconnect 1.141.5 → 1.142.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/eslint-plugin-coreconnect",
-  "version": "1.141.5",
+  "version": "1.142.1",
   "description": "ESLint rules enforcing EthisysCore plugin frontend conventions. Published so a new rule reaches every plugin on a version bump, rather than being copied into each scaffold and drifting.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -10,6 +10,7 @@ import noLocalInProgressBanner from "./rules/no-local-in-progress-banner.js";
 import noLocalMappingEditor from "./rules/no-local-mapping-editor.js";
 import noLocalSearchInput from "./rules/no-local-search-input.js";
 import noParamInNavPath from "./rules/no-param-in-nav-path.js";
+import noPluginQueryClient from "./rules/no-plugin-query-client.js";
 import noSecondMarkdownRenderer, {
   MARKDOWN_RESTRICTED_IMPORTS,
 } from "./rules/no-second-markdown-renderer.js";
@@ -27,6 +28,7 @@ const rules = {
   "no-local-mapping-editor": noLocalMappingEditor,
   "no-local-search-input": noLocalSearchInput,
   "no-param-in-nav-path": noParamInNavPath,
+  "no-plugin-query-client": noPluginQueryClient,
   "no-second-markdown-renderer": noSecondMarkdownRenderer,
 };
 

package/src/rules/no-plugin-query-client.js

@@ -0,0 +1,188 @@
+/**
+ * Disallow a plugin building its own react-query client, reaching into a client's caches, or passing the
+ * PlatformReact definers' `queryClient` override.
+ *
+ * PBI 5626 settled how a plugin caches in the browser (the rules the engineering skills publish):
+ *
+ *   R1. Each plugin gets its own cache from the host. The host builds ONE client per plugin, shared by
+ *       all that plugin's pages and overlays, with the host's error toasts, retries and 401 handling,
+ *       and clears it on sign-out and on an organisation or identity switch.
+ *   R2. A plugin cannot refresh another plugin's cached data. Another plugin's keys live in that
+ *       plugin's own client; invalidating them here is a no-op, so there is nothing to write.
+ *   R3. Cross-plugin updates come from backend pushes: the definers' `cacheSubscriptions` option.
+ *
+ * Each pattern below breaks one of them, invisibly at runtime:
+ *
+ *   - `new QueryClient(...)` in shipped code is a second cache. The bug that started PBI 5626 was exactly
+ *     this: one client per page bundle, so a delete on the detail page never reached the list page. It
+ *     also misses the host's clearing, so a surface on it can show the previous organisation's data.
+ *   - The definers' `queryClient` option is that same second client, handed to the definer. The SDK now
+ *     ignores it while the host provides the plugin's own client; this makes the dead option visible.
+ *   - `getQueryCache()` / `getMutationCache()` reach under react-query's public API into the whole cache,
+ *     the route to clearing or rewriting entries wholesale rather than invalidating the plugin's own keys.
+ *
+ * Test files are exempt (`isTestFile`): a test builds a client per case, by design.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+import { isTestFile } from "./testFiles.js";
+
+const DEFINERS = new Set([
+  "definePlatformReactPluginPage",
+  "definePlatformReactPluginOverlay",
+  "createPluginPageDefiner",
+  "createPluginOverlayDefiner",
+]);
+
+const CACHE_ACCESSORS = new Set(["getQueryCache", "getMutationCache"]);
+
+const REACT_QUERY = "@tanstack/react-query";
+
+/** How many `...spread` levels of a definer's options are followed back to an object literal. */
+const MAX_SPREAD_DEPTH = 3;
+
+/** The name a call or `new` targets: `f(...)`, `ns.f(...)`. */
+function targetName(callee) {
+  if (callee.type === "Identifier") return callee.name;
+  if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier") {
+    return callee.property.name;
+  }
+  return null;
+}
+
+function isQueryClientKey(property) {
+  if (property.type !== "Property" || property.computed) return false;
+  const { key } = property;
+  return (key.type === "Identifier" && key.name === "queryClient") || (key.type === "Literal" && key.value === "queryClient");
+}
+
+/** The exported name an import specifier binds: `{ QueryClient as QC }` and `{ "QueryClient" as QC }` alike. */
+function importedName(specifier) {
+  return specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow a plugin-built QueryClient, the definers' queryClient override, and getQueryCache/getMutationCache - each plugin runs on the one client the host gives it",
+    },
+    messages: {
+      newQueryClient:
+        "A plugin must not build its own QueryClient: it splits the plugin's cache and escapes the host's clearing on sign-out and organisation switch. Every page and overlay runs on the client the host provides; read it with useQueryClient(). To react to another app's change, map its canonical topic in the definer's cacheSubscriptions.",
+      definerOverride:
+        "The '{{name}}' queryClient option is deprecated and ignored while the host provides the plugin's own client (any host with per-plugin clients). Remove it; set staleTime or retry on the queries themselves.",
+      cacheAccessor:
+        "'{{name}}()' reaches into the whole react-query cache. Invalidate or update this plugin's own keys through the QueryClient API (invalidateQueries, setQueryData, removeQueries) instead.",
+    },
+    schema: [],
+  },
+  create(context) {
+    // Test scaffolding is exempt: a test builds a client per case, by design.
+    if (isTestFile(context.filename ?? context.getFilename?.())) {
+      return {};
+    }
+
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    /** The variable a read of `identifier` resolves to, through ESLint's scope manager; undefined for a global. */
+    const variableOf = (identifier) => {
+      for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name);
+        if (variable) return variable;
+      }
+      return undefined;
+    };
+
+    /**
+     * Whether `new <identifier>(...)` builds react-query's client. The binding decides: an import of
+     * `QueryClient` from react-query under any local name. A local class or an import from elsewhere
+     * that happens to be called `QueryClient` is something else. Only an unbound `QueryClient`, which
+     * this file cannot trace, is judged by its name.
+     */
+    const isQueryClientConstructor = (identifier) => {
+      const def = variableOf(identifier)?.defs[0];
+      if (def === undefined) return identifier.name === "QueryClient";
+      return (
+        def?.type === "ImportBinding" &&
+        def.node.type === "ImportSpecifier" &&
+        def.parent.source.value === REACT_QUERY &&
+        importedName(def.node) === "QueryClient"
+      );
+    };
+
+    /**
+     * Whether `new <ns>.QueryClient(...)` builds react-query's client. Yes unless `ns` is imported from
+     * another package (`import * as Vendor from "vendor"`): a namespace of react-query, or one this file
+     * cannot trace, is reported, as the rule did before it resolved bindings.
+     */
+    const isQueryClientMember = (callee) => {
+      if (targetName(callee) !== "QueryClient") return false;
+      if (callee.object.type !== "Identifier") return true;
+      const def = variableOf(callee.object)?.defs[0];
+      // A namespace import of react-query is the client; any other binding in this file (a local object,
+      // another package's namespace) is something else. An unbound name is out of reach, so it is reported.
+      if (def === undefined) return true;
+      return def.type === "ImportBinding" && def.parent.source.value === REACT_QUERY;
+    };
+
+    /**
+     * The object literal a definer's options argument is: written inline, or held in a `const` of this file.
+     * Options imported from another module are out of reach; the definers ignore the option on every host
+     * that provides a client anyway, so this rule makes the common forms visible rather than all of them.
+     */
+    const objectLiteralOf = (node) => {
+      if (node.type === "ObjectExpression") return node;
+      if (node.type !== "Identifier") return null;
+      const variable = variableOf(node);
+      const def = variable?.defs.length === 1 ? variable.defs[0] : undefined;
+      return def?.type === "Variable" && def.parent.kind === "const" && def.node.init?.type === "ObjectExpression"
+        ? def.node.init
+        : null;
+    };
+
+    // A `const` of options shared by two definer calls is one offence, reported once.
+    const reported = new Set();
+
+    const reportOverrides = (options, name, depth) => {
+      for (const property of options.properties) {
+        if (isQueryClientKey(property)) {
+          if (!reported.has(property)) {
+            reported.add(property);
+            context.report({ node: property, messageId: "definerOverride", data: { name } });
+          }
+        } else if (property.type === "SpreadElement" && depth < MAX_SPREAD_DEPTH) {
+          const spread = objectLiteralOf(property.argument);
+          if (spread) reportOverrides(spread, name, depth + 1);
+        }
+      }
+    };
+
+    return {
+      NewExpression(node) {
+        const { callee } = node;
+        const builds = callee.type === "Identifier" ? isQueryClientConstructor(callee) : isQueryClientMember(callee);
+        if (builds) {
+          context.report({ node, messageId: "newQueryClient" });
+        }
+      },
+      CallExpression(node) {
+        const name = targetName(node.callee);
+        if (name === null) return;
+
+        if (node.callee.type === "MemberExpression" && CACHE_ACCESSORS.has(name)) {
+          context.report({ node, messageId: "cacheAccessor", data: { name } });
+          return;
+        }
+
+        if (DEFINERS.has(name)) {
+          for (const argument of node.arguments) {
+            const options = objectLiteralOf(argument);
+            if (options) reportOverrides(options, name, 0);
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/testFiles.js

@@ -2,8 +2,9 @@
  * Whether a file is test scaffolding rather than shipped code.
  *
  * Used by the two STRUCTURAL rules - `no-inline-object-type` and `no-inline-string-union` - and by
- * nothing else. Both exist to stop an unnamed shape being re-written slightly differently by the
- * next person who needs it, and that argument does not reach a test file: the shape belongs to one
+ * `no-plugin-query-client`, whose ban on building a QueryClient cannot reach a test: a test builds a
+ * client per case, by design. The two structural rules exist to stop an unnamed shape being re-written
+ * slightly differently by the next person who needs it, and that argument does not reach a test file: the shape belongs to one
  * mock in one file, nobody imports it, and it is deleted when the test is.
  *
  * Measured before adding this: 80 of the estate's convention findings sit in test files, 74 of them