eslint-plugin-no-mistakes 0.91.3 → 0.92.0

package/README.md

@@ -34,3 +34,19 @@ test and Vitest config files selected by your flat-config globs. It defaults to
 5,000 ms for configured test and hook timeouts and 30,000 ms for per-test and
 hook overrides. See the [rule documentation](../../docs/eslint-rules/vitest-timeout-cap.md)
 for options and examples.
+
+`gh-api-argument-safety` is an opt-in rule for structured endpoint fields and explicit API methods.
+See [options and examples](../../docs/eslint-rules/gh-api-argument-safety.md).
+
+`no-argv-main-guard` is an opt-in rule for symlink-sensitive entrypoint comparisons.
+See [options and examples](../../docs/eslint-rules/no-argv-main-guard.md).
+
+`no-comment-phrases` is an opt-in rule for configured phrases in line and block comments.
+See [options and examples](../../docs/eslint-rules/no-comment-phrases.md).
+
+`forbidden-member-chains` is an opt-in rule for configured static member-access chains.
+See [options and examples](../../docs/eslint-rules/forbidden-member-chains.md).
+
+`require-options-on-imported-call` requires a static options object on configured
+imports, globals with no local binding, and terminal methods with a matching receiver shape.
+See [options and examples](../../docs/eslint-rules/require-options-on-imported-call.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-no-mistakes",
-  "version": "0.91.3",
+  "version": "0.92.0",
   "description": "ESLint and Oxlint rules that keep code static enough for no-mistakes analyzers and coding agents",
   "license": "MIT",
   "repository": {

package/src/index.js

@@ -1,6 +1,10 @@
 "use strict";
 
 const rules = {
+  "forbidden-member-chains": require("./rules/forbidden-member-chains"),
+  "gh-api-argument-safety": require("./rules/gh-api-argument-safety"),
+  "no-argv-main-guard": require("./rules/no-argv-main-guard"),
+  "no-comment-phrases": require("./rules/no-comment-phrases"),
   "async-call-disposition": require("./rules/async-call-disposition"),
   "async-try-catch-return-await": require("./rules/async-try-catch-return-await"),
   "await-array-methods": require("./rules/await-array-methods"),

package/src/rule-suppression.js

@@ -1,11 +1,13 @@
 "use strict";
 
 // Parse actual comments once; directive-looking string literals never suppress.
-function ruleSuppression(context, ruleId) {
+// requireReason is opt-in. Callers that omit it keep today's directive match.
+function ruleSuppression(context, ruleId, suppressionOptions) {
   const lines = new Set();
   let file = false;
   const source = context.sourceCode;
   const first = source.ast.tokens[0];
+  const requireReason = suppressionOptions?.requireReason === true;
   for (const comment of source.getAllComments()) {
     for (const [offset, text] of comment.value.split(/\r?\n/).entries()) {
       const match = /^\s*\*?\s*no-mistakes-disable-(file|line|next-line)\b(.*)$/.exec(text);
@@ -20,6 +22,7 @@ function ruleSuppression(context, ruleId) {
         !names.some((name) => name === ruleId || name === `no-mistakes/${ruleId}`)
       )
         continue;
+      if (requireReason && !directiveReason(match[2])) continue;
       if (match[1] === "file") {
         if (!first || comment.range[1] <= first.range[0]) file = true;
       } else {
@@ -29,4 +32,11 @@ function ruleSuppression(context, ruleId) {
   }
   return (node) => file || lines.has(node.loc.start.line);
 }
+
+function directiveReason(tail) {
+  const marker = tail.indexOf("--");
+  if (marker === -1) return "";
+  return tail.slice(marker + 2).trim();
+}
+
 module.exports = { ruleSuppression };

package/src/rules/argv-main-values.js

@@ -0,0 +1,114 @@
+"use strict";
+const { unwrapExpression } = require("./async-ast");
+const { resolveVariable, memberPropertyName, isLocalRequire } = require("./async-target-bindings");
+const { literalString } = require("./module-mock-helpers");
+
+function globalName(node, name, context) {
+  if (node?.type !== "Identifier" || node.name !== name) return false;
+  return !resolveVariable(node, context)?.defs.length;
+}
+function nodeProcess(node, context) {
+  if (globalName(node, "process", context)) return true;
+  if (node?.type !== "Identifier") return false;
+  const variable = resolveVariable(node, context);
+  const def = variable?.defs.length === 1 ? variable.defs[0] : null;
+  if (def?.type === "ImportBinding") {
+    return (
+      ["ImportDefaultSpecifier", "ImportNamespaceSpecifier"].includes(def.node.type) &&
+      ["process", "node:process"].includes(def.parent.source.value)
+    );
+  }
+  const init = unwrapExpression(def?.node.init);
+  return (
+    def?.parent?.kind === "const" &&
+    def.node.id.type === "Identifier" &&
+    init?.type === "CallExpression" &&
+    init.callee.type === "Identifier" &&
+    init.callee.name === "require" &&
+    !isLocalRequire(init.callee, context) &&
+    ["process", "node:process"].includes(literalString(init.arguments[0]))
+  );
+}
+const ARGV = 1;
+const MAIN = 2;
+const PROCESS = 3;
+const ARGUMENTS = 4;
+function createClassifier(context, wrappers) {
+  const stable = new WeakMap();
+  const aliases = new WeakMap();
+  function classify(input, depth = 0) {
+    const node = unwrapExpression(input);
+    if (!node || depth > 32) return 0;
+    if (node.type === "Identifier") {
+      const variable = resolveVariable(node, context);
+      if (!variable) {
+        if (nodeProcess(node, context)) return PROCESS;
+        return globalName(node, "__filename", context) ? MAIN : 0;
+      }
+      if (!stable.has(variable))
+        stable.set(variable, !variable.references.some((r) => r.isWrite() && !r.init));
+      if (!stable.get(variable)) return 0;
+      if (nodeProcess(node, context)) return PROCESS;
+      if (globalName(node, "__filename", context)) return MAIN;
+      const def = variable.defs.length === 1 ? variable.defs[0] : null;
+      if (
+        def?.type !== "Variable" ||
+        def.parent.kind !== "const" ||
+        def.node.id.type !== "Identifier" ||
+        def.node.range[1] > node.range[0]
+      )
+        return 0;
+      if (!aliases.has(variable)) {
+        aliases.set(variable, 0);
+        aliases.set(variable, classify(def.node.init, depth + 1));
+      }
+      return aliases.get(variable);
+    }
+    if (node.type === "MemberExpression") {
+      const name = memberPropertyName(node);
+      if (
+        node.object.type === "MetaProperty" &&
+        node.object.meta.name === "import" &&
+        node.object.property.name === "meta" &&
+        ["url", "filename"].includes(name)
+      )
+        return MAIN;
+      const object = classify(node.object, depth + 1);
+      if (object === PROCESS && name === "argv") return ARGUMENTS;
+      if (
+        object === ARGUMENTS &&
+        node.computed &&
+        node.property.type === "Literal" &&
+        node.property.value === 1
+      )
+        return ARGV;
+      // A URL conversion's href preserves the same module/argv identity.
+      if (
+        name === "href" &&
+        unwrapExpression(node.object).type === "CallExpression" &&
+        wrappers.resolveCallTarget(unwrapExpression(node.object))?.calleeName === "pathToFileURL"
+      )
+        return object;
+    }
+    if (node.type === "CallExpression") {
+      const callee = unwrapExpression(node.callee);
+      if (
+        callee?.type === "MemberExpression" &&
+        memberPropertyName(callee) === "at" &&
+        classify(callee.object, depth + 1) === ARGUMENTS &&
+        node.arguments.length === 1 &&
+        node.arguments[0].type === "Literal" &&
+        node.arguments[0].value === 1
+      )
+        return ARGV;
+      if (node.arguments.length !== 1 || node.arguments[0].type === "SpreadElement") return 0;
+      if (globalName(callee, "Boolean", context) || wrappers.resolveCallTarget(node)) {
+        const value = classify(node.arguments[0], depth + 1);
+        return value === ARGV || value === MAIN ? value : 0;
+      }
+    }
+    return 0;
+  }
+  return (node) => classify(node);
+}
+module.exports = { createClassifier, ARGV, MAIN };

package/src/rules/forbidden-member-chains-destructure.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const { matches, expressionInfo } = require("./forbidden-member-chains-match");
+
+const PARAM_PARENTS = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression",
+]);
+
+function patternKey(prop) {
+  const key = prop.key;
+  if (key.type === "Identifier") return key.name;
+  if (key.type === "Literal" && (typeof key.value === "string" || typeof key.value === "number")) {
+    return String(key.value);
+  }
+  return null;
+}
+
+function objectPattern(node) {
+  let current = node;
+  while (current?.type === "AssignmentPattern") current = current.left;
+  return current?.type === "ObjectPattern" ? current : null;
+}
+
+function destructureVisitors({ compiled, context, suppressed, info }) {
+  function report(node, chain) {
+    if (suppressed(node)) return;
+    context.report({ node, messageId: "forbiddenChain", data: { message: chain.message } });
+  }
+
+  // Computed keys are unproven, including string and numeric literals.
+  // A chain already matched by an outer property is not reported again.
+  function walk(pattern, chainInfo, blocked) {
+    for (const prop of pattern.properties) {
+      if (prop.type !== "Property" || prop.computed) continue;
+      const name = patternKey(prop);
+      if (name == null) continue;
+      const next = { segments: chainInfo.segments.concat(name), rooted: chainInfo.rooted };
+      const blockedHere = new Set(blocked);
+      for (const chain of compiled) {
+        if (blockedHere.has(chain) || !matches(next, chain)) continue;
+        report(prop, chain);
+        blockedHere.add(chain);
+      }
+      const nested = objectPattern(prop.value);
+      if (nested) walk(nested, next, blockedHere);
+    }
+  }
+
+  function check(pattern, receiver) {
+    const chainInfo = expressionInfo(receiver, info);
+    if (!chainInfo) return;
+    walk(pattern, chainInfo, new Set());
+  }
+
+  return {
+    VariableDeclarator(node) {
+      const pattern = objectPattern(node.id);
+      if (pattern && node.init) check(pattern, node.init);
+    },
+    AssignmentExpression(node) {
+      const pattern = objectPattern(node.left);
+      if (pattern) check(pattern, node.right);
+    },
+    AssignmentPattern(node) {
+      if (!PARAM_PARENTS.has(node.parent?.type)) return;
+      const pattern = objectPattern(node.left);
+      if (pattern) check(pattern, node.right);
+    },
+  };
+}
+
+module.exports = { destructureVisitors };

package/src/rules/forbidden-member-chains-match.js

@@ -0,0 +1,120 @@
+"use strict";
+
+const MAX_WALK = 32;
+const TRANSPARENT = new Set([
+  "ChainExpression",
+  "ParenthesizedExpression",
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSTypeAssertion",
+  "TSInstantiationExpression",
+  "TypeCastExpression",
+]);
+
+function unwrap(node) {
+  let current = node;
+  while (current && TRANSPARENT.has(current.type)) current = current.expression;
+  return current;
+}
+
+function literalKey(node) {
+  const value = unwrap(node);
+  if (
+    value?.type === "Literal" &&
+    (typeof value.value === "string" || typeof value.value === "number")
+  ) {
+    return String(value.value);
+  }
+  if (value?.type === "TemplateLiteral" && value.expressions.length === 0) {
+    return value.quasis.map((quasi) => quasi.value.cooked).join("");
+  }
+  return null;
+}
+
+function staticProperty(member) {
+  if (member.computed) return literalKey(member.property);
+  const property = member.property;
+  return property.type === "PrivateIdentifier" ? `#${property.name}` : property.name;
+}
+
+function rooted(segments, node) {
+  if (node?.type === "Identifier") segments.unshift(node.name);
+  else if (node?.type === "ThisExpression") segments.unshift("this");
+  else if (node?.type === "Super") segments.unshift("super");
+  else if (node?.type === "MetaProperty") segments.unshift(node.meta.name, node.property.name);
+  else return false;
+  return true;
+}
+
+function computeChain(member) {
+  const segments = [];
+  let current = member;
+  for (let steps = 0; current?.type === "MemberExpression"; steps += 1) {
+    if (steps >= MAX_WALK) return null;
+    const name = staticProperty(current);
+    if (name == null) return { segments, rooted: false };
+    segments.unshift(name);
+    current = unwrap(current.object);
+  }
+  return { segments, rooted: rooted(segments, current) };
+}
+
+function matches(info, chain) {
+  if (!info) return false;
+  const { segments, rooted: fromRoot } = info;
+  const { parts } = chain;
+  if (segments.length < parts.length) return false;
+  const start = segments.length - parts.length;
+  for (let index = 0; index < parts.length; index += 1) {
+    if (segments[start + index] !== parts[index]) return false;
+  }
+  // A wildcard needs a receiver. An opaque receiver is not one of the segments.
+  if (!chain.wildcard) return fromRoot && start === 0;
+  return start > 0 || !fromRoot;
+}
+
+function surface(node) {
+  let current = node;
+  while (
+    current.parent &&
+    TRANSPARENT.has(current.parent.type) &&
+    unwrap(current.parent) === node
+  ) {
+    current = current.parent;
+  }
+  return current;
+}
+
+function hasMatchingAncestor(node, chain, info) {
+  let current = node;
+  for (;;) {
+    const parent = surface(current).parent;
+    if (!parent || parent.type !== "MemberExpression" || unwrap(parent.object) !== current) {
+      return false;
+    }
+    if (matches(info(parent), chain)) return true;
+    current = parent;
+  }
+}
+
+function invocationOf(member) {
+  const parent = surface(member).parent;
+  if (parent.type !== "CallExpression" && parent.type !== "NewExpression") return null;
+  return unwrap(parent.callee) === member ? parent : null;
+}
+
+function expressionInfo(node, memberInfo) {
+  const value = unwrap(node);
+  if (value.type === "MemberExpression") return memberInfo(value);
+  const segments = [];
+  return { segments, rooted: rooted(segments, value) };
+}
+
+module.exports = {
+  matches,
+  computeChain,
+  hasMatchingAncestor,
+  invocationOf,
+  expressionInfo,
+};

package/src/rules/forbidden-member-chains-schema.js

@@ -0,0 +1,104 @@
+"use strict";
+
+const MAX_SEGMENTS = 16;
+// A segment is non-empty and is not exactly "*". The star is only a leading receiver.
+const SEGMENT = "(?!\\*(?:\\.|$))[^.]+";
+const OPEN_PATH = `^(?:\\*(?:\\.${SEGMENT}){1,15}|${SEGMENT}(?:\\.${SEGMENT}){0,15})$`;
+// A named receiver replaces a leading "*" and still counts toward 16 segments.
+const NAMED_PATH = `^(?:\\*|\\*(?:\\.${SEGMENT}){1,15}|${SEGMENT}(?:\\.${SEGMENT}){0,14})$`;
+
+function text(maxLength, pattern) {
+  return pattern
+    ? { type: "string", minLength: 1, maxLength, pattern }
+    : { type: "string", minLength: 1, maxLength };
+}
+
+function nonStar() {
+  return text(128, "^(?!\\*$)[\\s\\S]+$");
+}
+
+function pathString(pattern) {
+  return text(256, pattern);
+}
+
+function segments(maxItems) {
+  return { type: "array", minItems: 1, maxItems, items: nonStar() };
+}
+
+function starThen(minItems, maxItems) {
+  return {
+    type: "array",
+    minItems,
+    maxItems,
+    items: [{ enum: ["*"] }],
+    additionalItems: nonStar(),
+  };
+}
+
+function pathSchema(pattern, starMin, plainMax, starMax) {
+  return {
+    anyOf: [pathString(pattern), segments(plainMax), starThen(starMin, starMax)],
+  };
+}
+
+function chain(properties, required) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required,
+    properties: { message: text(512), ...properties },
+  };
+}
+
+const schema = [
+  {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      chains: {
+        type: "array",
+        maxItems: 64,
+        items: {
+          anyOf: [
+            chain({ path: pathSchema(OPEN_PATH, 2, MAX_SEGMENTS, MAX_SEGMENTS) }, [
+              "path",
+              "message",
+            ]),
+            chain(
+              {
+                path: pathSchema(OPEN_PATH, 2, MAX_SEGMENTS, MAX_SEGMENTS),
+                receiver: { type: "string", enum: ["*"] },
+              },
+              ["path", "message", "receiver"],
+            ),
+            chain(
+              {
+                path: pathSchema(NAMED_PATH, 1, MAX_SEGMENTS - 1, MAX_SEGMENTS),
+                receiver: nonStar(),
+              },
+              ["path", "message", "receiver"],
+            ),
+          ],
+        },
+      },
+    },
+  },
+];
+
+function compile(entry) {
+  const parts = Array.isArray(entry.path) ? entry.path.slice() : entry.path.split(".");
+  let wildcard = false;
+  let body = parts;
+  if (body[0] === "*") {
+    wildcard = true;
+    body = body.slice(1);
+  }
+  if (entry.receiver === "*") wildcard = true;
+  else if (typeof entry.receiver === "string") {
+    body = [entry.receiver, ...body];
+    wildcard = false;
+  }
+  return { wildcard, parts: body, message: entry.message };
+}
+
+module.exports = { schema, compile };

package/src/rules/forbidden-member-chains.js

@@ -0,0 +1,49 @@
+"use strict";
+
+const { ruleSuppression } = require("../rule-suppression");
+const { schema, compile } = require("./forbidden-member-chains-schema");
+const {
+  matches,
+  computeChain,
+  hasMatchingAncestor,
+  invocationOf,
+} = require("./forbidden-member-chains-match");
+const { destructureVisitors } = require("./forbidden-member-chains-destructure");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: { description: "ban configured static member-access chains", recommended: false },
+    schema,
+    messages: { forbiddenChain: "{{message}}" },
+  },
+  create(context) {
+    const compiled = [];
+    const entries = context.options[0]?.chains;
+    if (Array.isArray(entries)) {
+      for (const entry of entries) compiled.push(compile(entry));
+    }
+    if (compiled.length === 0) return {};
+    const suppressed = ruleSuppression(context, "forbidden-member-chains");
+    const cache = new WeakMap();
+    const info = (member) => {
+      if (cache.has(member)) return cache.get(member);
+      const value = computeChain(member);
+      cache.set(member, value);
+      return value;
+    };
+    const report = (node, chain) => {
+      if (suppressed(node)) return;
+      context.report({ node, messageId: "forbiddenChain", data: { message: chain.message } });
+    };
+    return {
+      MemberExpression(node) {
+        for (const chain of compiled) {
+          if (!matches(info(node), chain) || hasMatchingAncestor(node, chain, info)) continue;
+          report(invocationOf(node) || node, chain);
+        }
+      },
+      ...destructureVisitors({ compiled, context, suppressed, info }),
+    };
+  },
+};

package/src/rules/gh-api-argument-safety.js

@@ -0,0 +1,125 @@
+"use strict";
+const { createTargetMatcher } = require("./async-targets");
+const { unwrapExpression } = require("./async-ast");
+const { resolveVariable, memberPropertyName } = require("./async-target-bindings");
+const { ruleSuppression } = require("../rule-suppression");
+const { inspectArgv, token } = require("./gh-api-argv");
+
+function wrapperName(node, context, stable) {
+  node = unwrapExpression(node);
+  const names = [];
+  while (node?.type === "MemberExpression") {
+    const name = memberPropertyName(node);
+    if (!name) return null;
+    names.unshift(name);
+    node = unwrapExpression(node.object);
+  }
+  if (node?.type !== "Identifier") return null;
+  const variable = resolveVariable(node, context);
+  // A configured module wrapper never means a same-spelled nested parameter.
+  if (variable && !["module", "global"].includes(variable.scope.type)) return null;
+  if (variable) {
+    if (!stable.has(variable))
+      stable.set(
+        variable,
+        !variable.references.some((reference) => reference.isWrite() && !reference.init),
+      );
+    if (!stable.get(variable)) return null;
+  }
+  return [node.name, ...names].join(".");
+}
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "require structured endpoint fields and explicit gh api methods",
+      recommended: false,
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          wrappers: {
+            type: "array",
+            maxItems: 64,
+            items: {
+              type: "object",
+              properties: {
+                callee: { type: "string", minLength: 1 },
+                argumentPosition: { type: "integer", minimum: 1, maximum: 32 },
+                includesApi: { type: "boolean" },
+              },
+              required: ["callee", "argumentPosition"],
+              additionalProperties: false,
+            },
+          },
+          endpointMessage: { type: "string", minLength: 1 },
+          methodMessage: { type: "string", minLength: 1 },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      endpointQuery: "{{message}}",
+      missingMethod: "{{message}}",
+    },
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const stable = new WeakMap();
+    const matcherContext = Object.create(context);
+    Object.defineProperty(matcherContext, "options", {
+      value: [
+        {
+          targets: [
+            {
+              sourceSpecifierPatterns: ["node:child_process", "child_process"],
+              calleeNamePatterns: ["execFile", "execFileSync", "spawn", "spawnSync"],
+            },
+          ],
+        },
+      ],
+    });
+    const matcher = createTargetMatcher(matcherContext);
+    const suppressed = ruleSuppression(context, "gh-api-argument-safety");
+    return {
+      ...matcher.visitors,
+      CallExpression(node) {
+        let array;
+        let includesApi = true;
+        if (matcher.resolveCallTarget(node) && token(node.arguments[0]) === "gh") {
+          array = unwrapExpression(node.arguments[1]);
+        } else {
+          const name = wrapperName(node.callee, context, stable);
+          const wrapper = (options.wrappers || []).find((entry) => entry.callee === name);
+          if (!wrapper) return;
+          array = unwrapExpression(node.arguments[wrapper.argumentPosition - 1]);
+          includesApi = wrapper.includesApi !== false;
+        }
+        if (suppressed(node)) return;
+        const result = inspectArgv(array, includesApi);
+        if (!result) return;
+        if (result.endpoint && !suppressed(result.endpoint))
+          context.report({
+            node: result.endpoint,
+            messageId: "endpointQuery",
+            data: {
+              message:
+                options.endpointMessage ||
+                "Use structured -f/-F fields instead of an endpoint query string.",
+            },
+          });
+        if (result.missingMethod)
+          context.report({
+            node,
+            messageId: "missingMethod",
+            data: {
+              message:
+                options.methodMessage ||
+                "Set an explicit -X/--method when gh api uses field flags (for example -X GET).",
+            },
+          });
+      },
+    };
+  },
+};