eslint-plugin-no-mistakes 0.48.0 → 0.48.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-no-mistakes",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "description": "ESLint and Oxlint rules for deterministic no-mistakes code analysis",
   "license": "MIT",
   "repository": {

package/src/index.js

@@ -29,6 +29,7 @@ const rules = {
   "playwright-selector-priority": require("./rules/playwright-selector-priority"),
   "react-no-iife-in-jsx": require("./rules/react-no-iife-in-jsx"),
   "playwright-unique": require("./rules/playwright-unique"),
+  "postgres-cursor-call-contract": require("./rules/postgres-cursor-call-contract"),
   "postgres-no-manual-transaction": require("./rules/postgres-no-manual-transaction"),
   "postgres-no-unbounded-query-fanout": require("./rules/postgres-no-unbounded-query-fanout"),
   "react-no-nullish-react-node": require("./rules/react-no-nullish-react-node"),

package/src/rules/postgres-cursor-append.js

@@ -0,0 +1,23 @@
+"use strict";
+
+function appendCall(node, helpers, transparentParent) {
+  const object = transparentParent(node);
+  const member = object.parent;
+  if (member?.type !== "MemberExpression" || member.object !== object) return null;
+  if (member.computed || helpers.propertyName(member) !== "append") return null;
+  const callee = transparentParent(member);
+  const call = callee.parent;
+  return call?.type === "CallExpression" && call.callee === callee ? call : null;
+}
+
+function isDiscardedSqlStatementAppend(identifier, helpers, transparentParent) {
+  let call = appendCall(identifier, helpers, transparentParent);
+  while (call) {
+    const result = transparentParent(call);
+    if (result.parent?.type === "ExpressionStatement") return true;
+    call = appendCall(call, helpers, transparentParent);
+  }
+  return false;
+}
+
+module.exports = { isDiscardedSqlStatementAppend };

package/src/rules/postgres-cursor-ast.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const WRAPPERS = new Set([
+  "ChainExpression",
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSTypeAssertion",
+  "TSNonNullExpression",
+]);
+
+function unwrap(node) {
+  let current = node;
+  while (current && WRAPPERS.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function findVariable(context, identifier) {
+  if (typeof identifier?.name !== "string") return null;
+  let scope = context.sourceCode.getScope(identifier);
+  while (scope) {
+    const variable =
+      (typeof scope.set?.get === "function" && scope.set.get(identifier.name)) ||
+      scope.variables?.find((candidate) => candidate.name === identifier.name);
+    if (variable) return variable;
+    scope = scope.upper;
+  }
+  return null;
+}
+
+function literalName(value) {
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    typeof value === "bigint"
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function staticPropertyName(node) {
+  const value = unwrap(node);
+  if (value?.type === "Literal") return literalName(value.value);
+  if (value?.type === "TemplateLiteral" && (value.expressions ?? []).length === 0) {
+    const quasi = (value.quasis ?? [])[0];
+    return quasi?.value?.cooked ?? quasi?.value?.raw ?? null;
+  }
+  return null;
+}
+
+function propertyName(member) {
+  if (member?.type !== "MemberExpression") return null;
+  const property = member.property;
+  if (!member.computed && property?.type === "Identifier" && typeof property.name === "string") {
+    return property.name;
+  }
+  return member.computed ? staticPropertyName(property) : null;
+}
+
+function normalizeFilename(context) {
+  const filename = String(context.filename ?? "").replaceAll("\\", "/");
+  const cwd = context.cwd?.replaceAll("\\", "/").replace(/\/$/, "");
+  return cwd && filename.startsWith(`${cwd}/`) ? filename.slice(cwd.length + 1) : filename;
+}
+
+module.exports = {
+  findVariable,
+  normalizeFilename,
+  propertyName,
+  unwrap,
+};

package/src/rules/postgres-cursor-call-contract.js

@@ -0,0 +1,145 @@
+"use strict";
+
+const { rule } = require("../helpers");
+const { findVariable, propertyName, unwrap } = require("./postgres-cursor-ast");
+const { matchesCursorFile, resolveCursorContractOptions } = require("./postgres-cursor-options");
+const {
+  isCursorExecutor,
+  isCursorModule,
+  namedCursorImport,
+  namespaceCursorImport,
+  namespaceCursorMember,
+  namespaceImportMember,
+} = require("./postgres-cursor-imports");
+const {
+  directCallParent,
+  isTypeQuery,
+  queryHead,
+  transparentParent,
+} = require("./postgres-cursor-query");
+
+const helpers = { findVariable, propertyName, unwrap };
+
+function isTypeOnlyExport(identifier) {
+  const specifier = identifier.parent;
+  return (
+    specifier?.type === "ExportSpecifier" &&
+    (specifier.exportKind === "type" || specifier.parent?.exportKind === "type")
+  );
+}
+
+function reExportsCursor(node, config) {
+  if (!isCursorModule(node.source?.value, config) || node.exportKind === "type") return false;
+  if (node.type === "ExportAllDeclaration") return true;
+  return (
+    node.specifiers?.some((specifier) => {
+      const name = specifier.local?.name ?? specifier.local?.value;
+      return specifier.exportKind !== "type" && isCursorExecutor(name, config);
+    }) === true
+  );
+}
+
+function visitCursorIdentifier(context, node, options, reportedDirectUses) {
+  const namedImport = namedCursorImport(context, node, helpers, options);
+  const namespaceImport = namespaceCursorImport(context, node, helpers, options);
+  if (!namedImport && !namespaceImport) return;
+  if (
+    node.parent?.type === "ImportSpecifier" ||
+    node.parent?.type === "ImportNamespaceSpecifier" ||
+    isTypeQuery(node) ||
+    isTypeOnlyExport(node)
+  ) {
+    return;
+  }
+  const variable = helpers.findVariable(context, node);
+  if (!variable?.references.some((reference) => reference.identifier === node)) return;
+  const expression = transparentParent(node);
+  if (namespaceImport && namespaceImportMember(context, expression.parent, helpers, options)) {
+    return;
+  }
+  if (!directCallParent(node) && !reportedDirectUses.has(node)) {
+    reportedDirectUses.add(node);
+    context.report({ messageId: "directUse", node });
+  }
+}
+
+function visitNamespaceMember(context, node, options) {
+  const namespaceMember = namespaceImportMember(context, node, helpers, options);
+  if (!namespaceMember || isTypeQuery(node)) return;
+  if (namespaceMember.computed && helpers.propertyName(namespaceMember) == null) {
+    context.report({ messageId: "staticNamespaceMember", node });
+    return;
+  }
+  if (namespaceCursorMember(context, node, helpers, options) && !directCallParent(node)) {
+    context.report({ messageId: "directUse", node });
+  }
+}
+
+module.exports = rule(
+  {
+    type: "problem",
+    docs: {
+      description: "require direct cursor calls with statically annotated SQL",
+      recommended: false,
+    },
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          modules: { type: "array", items: { type: "string" } },
+          executors: { type: "array", items: { type: "string" } },
+          include: { type: "array", items: { type: "string" } },
+          exclude: { type: "array", items: { type: "string" } },
+          includeFiles: { type: "array", items: { type: "string" } },
+          annotation: { type: "string" },
+          sqlTagModules: { type: "array", items: { type: "string" } },
+        },
+      },
+    ],
+    messages: {
+      annotation: "PostgreSQL cursor SQL must start with a static /* name */ annotation.",
+      directUse: "PostgreSQL cursor helpers must be called directly so their SQL can be verified.",
+      staticQuery:
+        "PostgreSQL cursor SQL must be visible at the callsite or in one immutable local binding.",
+      staticNamespaceMember:
+        "PostgreSQL namespace members must use a static property name so cursor use can be verified.",
+    },
+  },
+  (context) => {
+    const options = resolveCursorContractOptions(context.options[0]);
+    if (!options || !matchesCursorFile(context, options)) return {};
+    const reportedDirectUses = new WeakSet();
+    return {
+      CallExpression(node) {
+        const callee = helpers.unwrap(node.callee);
+        const executor =
+          namedCursorImport(context, callee, helpers, options) ||
+          namespaceCursorMember(context, callee, helpers, options);
+        if (!executor) return;
+        const argument = node.arguments?.[0];
+        const reportNode = argument ?? node;
+        const head = argument ? queryHead(context, argument, helpers, options) : null;
+        if (head === null) {
+          context.report({ messageId: "staticQuery", node: reportNode });
+          return;
+        }
+        if (!options.annotation.test(head)) {
+          context.report({ messageId: "annotation", node: reportNode });
+        }
+      },
+      Identifier(node) {
+        visitCursorIdentifier(context, node, options, reportedDirectUses);
+      },
+      MemberExpression(node) {
+        visitNamespaceMember(context, node, options);
+      },
+      ExportAllDeclaration(node) {
+        if (reExportsCursor(node, options)) context.report({ messageId: "directUse", node });
+      },
+      ExportNamedDeclaration(node) {
+        if (reExportsCursor(node, options)) context.report({ messageId: "directUse", node });
+      },
+    };
+  },
+);

package/src/rules/postgres-cursor-imports.js

@@ -0,0 +1,71 @@
+"use strict";
+
+function isCursorModule(name, config) {
+  return typeof name === "string" && config.modules.has(name);
+}
+
+function isCursorExecutor(name, config) {
+  return typeof name === "string" && config.executors.has(name);
+}
+
+function importDefinition(variable, specifierType, config) {
+  return variable?.defs.find((definition) => {
+    const specifier = definition.node;
+    const declaration = definition.parent || specifier.parent;
+    return (
+      definition.type === "ImportBinding" &&
+      specifier.type === specifierType &&
+      specifier.importKind !== "type" &&
+      declaration?.type === "ImportDeclaration" &&
+      declaration.importKind !== "type" &&
+      isCursorModule(declaration.source?.value, config)
+    );
+  });
+}
+
+function namedCursorImport(context, identifier, helpers, config) {
+  if (identifier?.type !== "Identifier") return null;
+  const imported = importDefinition(
+    helpers.findVariable(context, identifier),
+    "ImportSpecifier",
+    config,
+  )?.node.imported;
+  const name = imported?.name ?? imported?.value;
+  return isCursorExecutor(name, config) ? String(name) : null;
+}
+
+function namespaceCursorImport(context, identifier, helpers, config) {
+  return (
+    identifier?.type === "Identifier" &&
+    Boolean(
+      importDefinition(
+        helpers.findVariable(context, identifier),
+        "ImportNamespaceSpecifier",
+        config,
+      ),
+    )
+  );
+}
+
+function namespaceImportMember(context, node, helpers, config) {
+  const member = helpers.unwrap(node);
+  if (member?.type !== "MemberExpression") return null;
+  const object = helpers.unwrap(member.object);
+  if (object?.type !== "Identifier") return null;
+  return namespaceCursorImport(context, object, helpers, config) ? member : null;
+}
+
+function namespaceCursorMember(context, node, helpers, config) {
+  const member = namespaceImportMember(context, node, helpers, config);
+  const name = member && helpers.propertyName(member);
+  return isCursorExecutor(name, config) ? String(name) : null;
+}
+
+module.exports = {
+  isCursorExecutor,
+  isCursorModule,
+  namedCursorImport,
+  namespaceCursorImport,
+  namespaceCursorMember,
+  namespaceImportMember,
+};

package/src/rules/postgres-cursor-options.js

@@ -0,0 +1,83 @@
+"use strict";
+
+const { stringMatches } = require("./module-mock-helpers");
+const { normalizeFilename } = require("./postgres-cursor-ast");
+
+const DEFAULT_CURSOR_INCLUDE = ["**/*.{ts,mts,tsx,js,mjs}"];
+const DEFAULT_CURSOR_ANNOTATION = "^\\s*/\\*\\s*\\S[^]*?\\*/";
+const DEFAULT_SQL_TAG_MODULES = ["sql-template-strings"];
+
+function expandBraces(pattern) {
+  const start = pattern.indexOf("{");
+  const end = pattern.indexOf("}", start + 1);
+  if (start === -1 || end === -1) return [pattern];
+  const prefix = pattern.slice(0, start);
+  const suffix = pattern.slice(end + 1);
+  return pattern
+    .slice(start + 1, end)
+    .split(",")
+    .flatMap((alt) => expandBraces(`${prefix}${alt}${suffix}`));
+}
+
+function globListMatches(filename, patterns) {
+  return patterns.some((pattern) => stringMatches(filename, expandBraces(pattern)));
+}
+
+function stringArray(value) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) return undefined;
+  return value;
+}
+
+function optionalStringArray(value, present) {
+  if (!present) return undefined;
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : null;
+}
+
+function resolveCursorContractOptions(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const modules = stringArray(raw.modules);
+  const executors = stringArray(raw.executors);
+  if (!modules?.length || !executors?.length) return null;
+  if (raw.annotation !== undefined && typeof raw.annotation !== "string") return null;
+  const include = optionalStringArray(raw.include, raw.include !== undefined);
+  const exclude = optionalStringArray(raw.exclude, raw.exclude !== undefined);
+  const includeFiles = optionalStringArray(raw.includeFiles, raw.includeFiles !== undefined);
+  const sqlTagModules = optionalStringArray(raw.sqlTagModules, raw.sqlTagModules !== undefined);
+  if (include === null || exclude === null || includeFiles === null || sqlTagModules === null) {
+    return null;
+  }
+  let annotation;
+  try {
+    annotation = new RegExp(
+      typeof raw.annotation === "string" ? raw.annotation : DEFAULT_CURSOR_ANNOTATION,
+    );
+  } catch {
+    throw new Error(
+      `postgres-cursor-call-contract annotation is not a valid regular expression: ${String(raw.annotation)}`,
+    );
+  }
+  return {
+    modules: new Set(modules),
+    executors: new Set(executors),
+    include: include ?? DEFAULT_CURSOR_INCLUDE,
+    exclude: exclude ?? [],
+    includeFiles: (includeFiles ?? []).map((file) => file.replace(/^(?:\.\/)+/, "")),
+    sqlTagModules: new Set(sqlTagModules ?? DEFAULT_SQL_TAG_MODULES),
+    annotation,
+  };
+}
+
+function matchesCursorFile(context, options) {
+  const filename = normalizeFilename(context).replace(/^(?:\.\/)+/, "");
+  if (options.includeFiles.includes(filename)) return true;
+  if (options.exclude.length > 0 && globListMatches(filename, options.exclude)) return false;
+  return globListMatches(filename, options.include);
+}
+
+module.exports = {
+  DEFAULT_CURSOR_INCLUDE,
+  DEFAULT_SQL_TAG_MODULES,
+  matchesCursorFile,
+  resolveCursorContractOptions,
+};

package/src/rules/postgres-cursor-query.js

@@ -0,0 +1,122 @@
+"use strict";
+
+const { isDiscardedSqlStatementAppend } = require("./postgres-cursor-append");
+const { namedCursorImport, namespaceCursorMember } = require("./postgres-cursor-imports");
+
+function transparentParent(node) {
+  let current = node;
+  while (
+    current.parent &&
+    (current.parent.type === "ChainExpression" ||
+      current.parent.type === "TSAsExpression" ||
+      current.parent.type === "TSSatisfiesExpression" ||
+      current.parent.type === "TSTypeAssertion" ||
+      current.parent.type === "TSNonNullExpression") &&
+    current.parent.expression === current
+  ) {
+    current = current.parent;
+  }
+  return current;
+}
+
+function directCallParent(node) {
+  const current = transparentParent(node);
+  return current.parent?.type === "CallExpression" && current.parent.callee === current
+    ? current.parent
+    : null;
+}
+
+function isTypeQuery(node) {
+  let current = transparentParent(node);
+  while (current.parent?.type === "TSQualifiedName") current = current.parent;
+  return current.parent?.type === "TSTypeQuery";
+}
+
+function firstQuasiText(template, allowRaw) {
+  const quasi = template?.quasis?.[0];
+  if (!quasi) return null;
+  return quasi.value?.cooked ?? (allowRaw ? (quasi.value?.raw ?? null) : null);
+}
+
+function exactSqlTag(context, tag, helpers, config) {
+  const identifier = helpers.unwrap(tag);
+  if (identifier?.type !== "Identifier") return false;
+  const variable = helpers.findVariable(context, identifier);
+  const definition = variable?.defs.find((candidate) => {
+    const specifier = candidate.node;
+    const declaration = candidate.parent || specifier.parent;
+    const source = declaration?.source?.value;
+    return (
+      candidate.type === "ImportBinding" &&
+      specifier.type === "ImportDefaultSpecifier" &&
+      specifier.importKind !== "type" &&
+      declaration?.type === "ImportDeclaration" &&
+      declaration.importKind !== "type" &&
+      typeof source === "string" &&
+      config.sqlTagModules.has(source)
+    );
+  });
+  return Boolean(
+    definition && variable && !variable.references.some((reference) => reference.isWrite()),
+  );
+}
+
+function directQueryHead(context, node, helpers, config) {
+  const value = helpers.unwrap(node);
+  if (value?.type === "Literal") return typeof value.value === "string" ? value.value : null;
+  if (value?.type === "TemplateLiteral") return firstQuasiText(value, true);
+  if (
+    value?.type === "TaggedTemplateExpression" &&
+    exactSqlTag(context, value.tag, helpers, config)
+  ) {
+    return firstQuasiText(value.quasi, false);
+  }
+  return null;
+}
+
+function isCursorQueryArgument(context, identifier, helpers, config) {
+  const argument = transparentParent(identifier);
+  const call = argument.parent;
+  if (call?.type !== "CallExpression" || call.arguments?.[0] !== argument) return false;
+  const callee = helpers.unwrap(call.callee);
+  return Boolean(
+    namedCursorImport(context, callee, helpers, config) ||
+    namespaceCursorMember(context, callee, helpers, config),
+  );
+}
+
+function queryHead(context, node, helpers, config) {
+  const direct = directQueryHead(context, node, helpers, config);
+  if (direct !== null) return direct;
+  const value = helpers.unwrap(node);
+  if (value?.type !== "Identifier") return null;
+  const variable = helpers.findVariable(context, value);
+  const definitions = variable?.defs.filter((definition) => definition.type === "Variable") ?? [];
+  if (definitions.length !== 1) return null;
+  const declaration = definitions[0]?.node;
+  if (
+    declaration?.type !== "VariableDeclarator" ||
+    declaration.parent?.type !== "VariableDeclaration" ||
+    declaration.parent.kind !== "const" ||
+    variable?.references.some((reference) => {
+      const identifier = reference.identifier;
+      return (
+        identifier !== declaration.id &&
+        !isTypeQuery(identifier) &&
+        !isCursorQueryArgument(context, identifier, helpers, config) &&
+        !isDiscardedSqlStatementAppend(identifier, helpers, transparentParent)
+      );
+    })
+  ) {
+    return null;
+  }
+  return directQueryHead(context, declaration.init, helpers, config);
+}
+
+module.exports = {
+  directCallParent,
+  firstQuasiText,
+  isTypeQuery,
+  queryHead,
+  transparentParent,
+};