@heyramzi/lint 0.0.0-stage → 1.32.4

package/rules/convex-no-filter.js

@@ -0,0 +1,41 @@
+/**
+ * `.filter()` on a Convex query builder reads the whole range and drops rows in JS.
+ */
+import { propertyName, stepDown } from "#lint/rules/convex-ast.js";
+
+const TERMINALS = new Set(["collect", "take", "first", "unique", "paginate"]);
+
+function isDbQuery(call) {
+  return propertyName(call.callee) === "query" && propertyName(call.callee.object) === "db";
+}
+
+/** True when the chain under `.filter` is a query builder that nothing has run yet. */
+function buildsQuery(start) {
+  for (let node = start; node; node = stepDown(node)) {
+    if (node.type !== "CallExpression") continue;
+    const method = propertyName(node.callee);
+    if (method && TERMINALS.has(method)) return false;
+    if (isDbQuery(node)) return true;
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow `.filter()` chained on `ctx.db.query()`. Use `withIndex`." },
+    messages: {
+      noFilter:
+        "`.filter()` reads the whole table and throws rows away in JS, and the read is billed. Add the index to `schema.ts` and use `.withIndex(name, (q) => q.eq(field, value))`.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (propertyName(node.callee) !== "filter") return;
+        if (buildsQuery(node.callee.object)) context.report({ node, messageId: "noFilter" });
+      },
+    };
+  },
+};

package/rules/convex-no-get-metadata.js

@@ -0,0 +1,26 @@
+/**
+ * `ctx.storage.getMetadata` is deprecated.
+ */
+import { propertyName } from "#lint/rules/convex-ast.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow the deprecated `storage.getMetadata`." },
+    messages: {
+      noGetMetadata:
+        '`storage.getMetadata` is deprecated. Use `ctx.db.system.get("_storage", storageId)`.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (propertyName(node.callee) !== "getMetadata") return;
+        if (propertyName(node.callee.object) === "storage") {
+          context.report({ node, messageId: "noGetMetadata" });
+        }
+      },
+    };
+  },
+};

package/rules/convex-no-v-any.js

@@ -0,0 +1,24 @@
+/**
+ * `v.any()` turns a validator off.
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow `v.any()`. Name the shape." },
+    messages: {
+      noAny:
+        "`v.any()` switches validation off. Use `v.object({...})`, `v.record(v.string(), ...)` or `v.union(...)`.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type !== "MemberExpression" || callee.computed) return;
+        if (callee.object.type !== "Identifier" || callee.object.name !== "v") return;
+        if (callee.property.name === "any") context.report({ node, messageId: "noAny" });
+      },
+    };
+  },
+};

package/rules/convex-react-client-module-scope.js

@@ -0,0 +1,37 @@
+/**
+ * `new ConvexReactClient` belongs at module scope.
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow creating `ConvexReactClient` inside a function or component." },
+    messages: {
+      moduleScope:
+        "`new ConvexReactClient` inside a function builds a new client on every call. Create it once at module scope and import it.",
+    },
+    schema: [],
+  },
+  create(context) {
+    let depth = 0;
+    const enter = () => {
+      depth++;
+    };
+    const exit = () => {
+      depth--;
+    };
+    return {
+      FunctionDeclaration: enter,
+      "FunctionDeclaration:exit": exit,
+      FunctionExpression: enter,
+      "FunctionExpression:exit": exit,
+      ArrowFunctionExpression: enter,
+      "ArrowFunctionExpression:exit": exit,
+      NewExpression(node) {
+        if (depth === 0) return;
+        if (node.callee.type === "Identifier" && node.callee.name === "ConvexReactClient") {
+          context.report({ node, messageId: "moduleScope" });
+        }
+      },
+    };
+  },
+};

package/rules/convex-require-args.js

@@ -0,0 +1,39 @@
+/**
+ * A registered Convex function takes an object and declares `args`.
+ */
+import { findProperty, registerName } from "#lint/rules/convex-ast.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require the object syntax and an `args` validator on every Convex function.",
+    },
+    messages: {
+      oldSyntax:
+        "`{{ name }}(async (ctx) => ...)` is the old function syntax. Pass an object: `{{ name }}({ args: {...}, returns: v.null(), handler: async (ctx, args) => ... })`.",
+      missingArgs:
+        "`{{ name }}` has no `args`. Without a validator it's an unvalidated public endpoint. Add `args: {}` for none.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const name = registerName(node);
+        if (!name || node.arguments.length !== 1) return;
+        const [config] = node.arguments;
+        if (config.type === "ArrowFunctionExpression" || config.type === "FunctionExpression") {
+          context.report({ node, messageId: "oldSyntax", data: { name } });
+          return;
+        }
+        if (config.type !== "ObjectExpression") return;
+        if (config.properties.some((property) => property.type === "SpreadElement")) return;
+        if (!findProperty(config, "handler")) return;
+        if (!findProperty(config, "args")) {
+          context.report({ node, messageId: "missingArgs", data: { name } });
+        }
+      },
+    };
+  },
+};

package/rules/convex-require-returns.js

@@ -0,0 +1,31 @@
+/**
+ * A registered Convex function declares a `returns` validator.
+ */
+import { findProperty, registerName } from "#lint/rules/convex-ast.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Require a `returns` validator on every Convex function." },
+    messages: {
+      missingReturns:
+        "`{{ name }}` has no `returns`. Add a validator for what the handler returns, `v.null()` for nothing.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const name = registerName(node);
+        if (!name || node.arguments.length !== 1) return;
+        const [config] = node.arguments;
+        if (config.type !== "ObjectExpression") return;
+        if (config.properties.some((property) => property.type === "SpreadElement")) return;
+        if (!findProperty(config, "handler")) return;
+        if (!findProperty(config, "returns")) {
+          context.report({ node, messageId: "missingReturns", data: { name } });
+        }
+      },
+    };
+  },
+};

package/rules/convex-runtime-imports.js

@@ -0,0 +1,48 @@
+/**
+ * Node built-ins need `"use node"`, and a `"use node"` file holds actions only.
+ */
+import { builtinModules } from "node:module";
+import { hasUseNode, registerName } from "#lint/rules/convex-ast.js";
+
+const NODE_ONLY = new Set(["query", "mutation", "internalQuery", "internalMutation"]);
+
+function isBuiltin(source) {
+  if (source.startsWith("node:")) return true;
+  return builtinModules.includes(source.split("/")[0]);
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: 'Keep Node built-ins in `"use node"` files and keep queries out of them.',
+    },
+    messages: {
+      needsUseNode:
+        'Importing "{{ source }}" needs `"use node"` as the first line, and that file can then hold actions only. Move the Node work into an `internalAction` in its own file.',
+      actionsOnly:
+        'A `"use node"` file can only define actions, and `{{ name }}` isn\'t one. Move it to a file without the directive.',
+    },
+    schema: [],
+  },
+  create(context) {
+    let useNode = false;
+    return {
+      Program(node) {
+        useNode = hasUseNode(node);
+      },
+      ImportDeclaration(node) {
+        if (useNode || node.importKind === "type") return;
+        const source = node.source.value;
+        if (typeof source === "string" && isBuiltin(source)) {
+          context.report({ node, messageId: "needsUseNode", data: { source } });
+        }
+      },
+      CallExpression(node) {
+        if (!useNode) return;
+        const name = registerName(node);
+        if (name && NODE_ONLY.has(name)) context.report({ node, messageId: "actionsOnly", data: { name } });
+      },
+    };
+  },
+};

package/rules/max-function-lines.js

@@ -0,0 +1,105 @@
+/**
+ * Cap function body length (excluding blank lines and comments).
+ *
+ * Encourages small, focused functions. Default max: 30 lines.
+ * Counts only meaningful lines inside the function body.
+ */
+function getFunctionName(node) {
+  // Named function declaration
+  if (node.id) return node.id.name;
+
+  // Variable declarator: const foo = () => {}
+  if (node.parent && node.parent.type === "VariableDeclarator" && node.parent.id) {
+    return node.parent.id.name;
+  }
+
+  // Object method: { foo() {} }
+  if (node.parent && node.parent.type === "Property" && node.parent.key) {
+    return node.parent.key.name || node.parent.key.value || "anonymous";
+  }
+
+  // Class method
+  if (node.parent && node.parent.type === "MethodDefinition" && node.parent.key) {
+    return node.parent.key.name || node.parent.key.value || "anonymous";
+  }
+
+  return "anonymous";
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Enforce a maximum number of meaningful lines per function body.",
+    },
+    messages: {
+      tooLong:
+        "Function '{{ name }}' has {{ count }} lines (max {{ max }}). Break it into smaller functions.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          max: { type: "integer", minimum: 1 },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const max = (context.options[0] && context.options[0].max) || 30;
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    function countMeaningfulLines(node) {
+      const body = node.body;
+      if (!body || body.type !== "BlockStatement") return 0;
+
+      const startLine = body.loc.start.line + 1; // Skip opening brace
+      const endLine = body.loc.end.line; // Skip closing brace
+
+      if (startLine >= endLine) return 0;
+
+      let count = 0;
+      for (let line = startLine; line < endLine; line++) {
+        const lineText = sourceCode.lines[line - 1];
+        if (!lineText) continue;
+
+        const trimmed = lineText.trim();
+
+        // Skip blank lines
+        if (trimmed === "") continue;
+
+        // Skip single-line comments
+        if (trimmed.startsWith("//")) continue;
+
+        // Skip comment-only lines (block comments)
+        if (trimmed.startsWith("/*") || trimmed.startsWith("*")) continue;
+
+        count++;
+      }
+
+      return count;
+    }
+
+    function check(node) {
+      const count = countMeaningfulLines(node);
+      if (count > max) {
+        context.report({
+          node,
+          messageId: "tooLong",
+          data: {
+            name: getFunctionName(node),
+            count: String(count),
+            max: String(max),
+          },
+        });
+      }
+    }
+
+    return {
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+      ArrowFunctionExpression: check,
+    };
+  },
+};

package/rules/max-object-methods.js

@@ -0,0 +1,86 @@
+/**
+ * Cap the number of methods on an exported const object.
+ */
+
+/*
+ * When a const wrapper grows too large, split it into smaller objects by sub-domain. Default max: 10 methods.
+ */
+
+/*
+ * Only counts callable properties (methods, arrow functions, function expressions). Plain values and spreads are ignored. Only applies to exported const declarations.
+ */
+function isCallable(property) {
+  if (property.type !== "Property") return false;
+
+  // Method shorthand: { foo() {} }
+  if (property.method) return true;
+
+  const value = property.value;
+  if (!value) return false;
+
+  // Arrow function: { foo: () => {} }
+  if (value.type === "ArrowFunctionExpression") return true;
+
+  // Function expression: { foo: function() {} }
+  if (value.type === "FunctionExpression") return true;
+
+  return false;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Enforce a maximum number of methods on exported const objects.",
+    },
+    messages: {
+      tooMany:
+        "Object '{{ name }}' has {{ count }} methods (max {{ max }}). Split into smaller objects by sub-domain.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          max: { type: "integer", minimum: 1 },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const max = (context.options[0] && context.options[0].max) || 10;
+
+    return {
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+        if (!decl || decl.type !== "VariableDeclaration") return;
+        if (decl.kind !== "const") return;
+
+        for (const declarator of decl.declarations) {
+          if (!declarator.init) continue;
+
+          const init = declarator.init;
+
+          // Handle `{ ... } as const` via TSAsExpression
+          const obj = init.type === "TSAsExpression" ? init.expression : init;
+
+          if (obj.type !== "ObjectExpression") continue;
+
+          const methodCount = obj.properties.filter(isCallable).length;
+
+          if (methodCount > max) {
+            context.report({
+              node: declarator,
+              messageId: "tooMany",
+              data: {
+                name: declarator.id.name || "anonymous",
+                count: String(methodCount),
+                max: String(max),
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-ai-words.js

@@ -0,0 +1,78 @@
+/**
+ * Ban AI-generated slop words and phrases in string literals.
+ * Word list sourced from hardikpandya/stop-slop + local additions.
+ */
+
+import { words as BANNED_WORDS, phrases as BANNED_PHRASES } from "#lint/data/slop-words.js";
+
+const wordRegex = new RegExp(`\\b(${BANNED_WORDS.join("|")})\\b`, "gi");
+const phraseRegexes = BANNED_PHRASES.map((p) => ({
+  phrase: p,
+  regex: new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i"),
+}));
+
+function isUserFacingString(node) {
+  if (node.parent?.type === "ImportDeclaration") return false;
+  if (node.parent?.type === "ImportExpression") return false;
+  if (node.parent?.type === "CallExpression" && node.parent.callee?.name === "require")
+    return false;
+  if (node.parent?.type === "Property" && node.parent.key === node) return false;
+  if (node.parent?.type === "MemberExpression" && node.parent.property === node) return false;
+  return true;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow AI-generated slop words and phrases in string literals.",
+      url: "https://github.com/hardikpandya/stop-slop",
+    },
+    messages: {
+      bannedWord: 'AI slop: "{{ word }}". Reword to sound human.',
+      bannedPhrase: 'AI slop: "{{ phrase }}". Reword to sound human.',
+    },
+    schema: [],
+  },
+  create(context) {
+    function checkValue(value, node) {
+      if (typeof value !== "string") return;
+      if (value.length < 10) return;
+
+      for (const match of value.matchAll(wordRegex)) {
+        context.report({
+          node,
+          messageId: "bannedWord",
+          data: { word: match[1] },
+        });
+      }
+
+      for (const { phrase, regex } of phraseRegexes) {
+        if (regex.test(value)) {
+          context.report({
+            node,
+            messageId: "bannedPhrase",
+            data: { phrase },
+          });
+        }
+      }
+    }
+
+    return {
+      Literal(node) {
+        if (!isUserFacingString(node)) return;
+        checkValue(node.value, node);
+      },
+      TemplateLiteral(node) {
+        if (!isUserFacingString(node)) return;
+        for (const quasi of node.quasis) {
+          checkValue(quasi.value.cooked, node);
+        }
+      },
+      // JSON support
+      JSONLiteral(node) {
+        checkValue(node.value, node);
+      },
+    };
+  },
+};

package/rules/no-app-stores.js

@@ -0,0 +1,25 @@
+/**
+ * Ban `$app/stores`. Read `page`, `navigating` and `updated` from `$app/state`.
+ */
+const message =
+  "`$app/stores` is the Svelte 4 API. Use `import { page } from '$app/state'` and read `page.url`, not `$page.url`.";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow importing from $app/stores." },
+    messages: { appStores: message },
+    schema: [],
+  },
+  create(context) {
+    const check = (node) => {
+      if (node.source?.value === "$app/stores") context.report({ node, messageId: "appStores" });
+    };
+    return {
+      ImportDeclaration: check,
+      ExportNamedDeclaration: check,
+      ExportAllDeclaration: check,
+      ImportExpression: check,
+    };
+  },
+};

package/rules/no-chained-type-assertions.js

@@ -0,0 +1,91 @@
+/**
+ * Disallow chained type assertions (`x as unknown as Foo`, `<Foo><unknown>x`).
+ */
+
+/*
+ * A chain launders a value through a top type so the second assertion always compiles. The result is a claim with no evidence behind it.
+ */
+
+/*
+ * Keep the precise type, or parse the value at its boundary before narrowing it.
+ */
+
+/*
+ * Chains built only of `as const` are allowed.
+ */
+
+/*
+ * Ported from dmmulroy/anti-slop (MIT).
+ */
+
+const ASSERTION_TYPES = new Set(["TSAsExpression", "TSTypeAssertion"]);
+
+function isAssertion(node) {
+  return node != null && ASSERTION_TYPES.has(node.type);
+}
+
+function unwrapParens(node) {
+  let current = node;
+  while (current?.type === "ParenthesizedExpression") current = current.expression;
+  return current;
+}
+
+function isConstAssertion(node) {
+  const annotation = node.typeAnnotation;
+  return (
+    annotation?.type === "TSTypeReference" &&
+    annotation.typeName?.type === "Identifier" &&
+    annotation.typeName.name === "const"
+  );
+}
+
+/** Only report the outermost assertion of a chain, so one chain yields one diagnostic. */
+function isOutermost(node) {
+  let current = node;
+  let parent = node.parent;
+  while (parent?.type === "ParenthesizedExpression" && parent.expression === current) {
+    current = parent;
+    parent = parent.parent;
+  }
+  return !isAssertion(parent) || parent.expression !== current;
+}
+
+function isForbiddenChain(node) {
+  let count = 0;
+  let hasNonConst = false;
+  let current = node;
+
+  while (isAssertion(current)) {
+    count += 1;
+    if (!isConstAssertion(current)) hasNonConst = true;
+    current = unwrapParens(current.expression);
+  }
+
+  return count > 1 && hasNonConst;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow chained type assertions. They fabricate evidence by routing a value through a top type.",
+    },
+    messages: {
+      chained:
+        "This assertion chain discards type evidence. Keep the original precise type, or parse untrusted input at its boundary before narrowing it.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const check = (node) => {
+      if (!isOutermost(node) || !isForbiddenChain(node)) return;
+      context.report({ node, messageId: "chained" });
+    };
+
+    return {
+      TSAsExpression: check,
+      TSTypeAssertion: check,
+    };
+  },
+};

package/rules/no-class.js

@@ -0,0 +1,47 @@
+/**
+ * Ban class declarations. Only Error subclasses are allowed.
+ *
+ * Use const wrapper objects or factory functions instead.
+ * Error subclasses (extends Error, extends *Error) are allowed
+ * because instanceof discrimination requires class syntax.
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow class declarations. Use const wrappers or factory functions. Only Error subclasses are allowed.",
+    },
+    messages: {
+      noClass:
+        "Use a const wrapper object or factory function instead of a class. Classes are only allowed for Error subclasses.",
+    },
+    schema: [],
+  },
+  create(context) {
+    /** Names that require class syntax (Error hierarchy) */
+    const ALLOWED_SUPERCLASSES = /Error$/;
+
+    function check(node) {
+      const superClass = node.superClass;
+
+      if (superClass) {
+        const superName =
+          superClass.type === "Identifier"
+            ? superClass.name
+            : superClass.type === "MemberExpression" && superClass.property.type === "Identifier"
+              ? superClass.property.name
+              : null;
+
+        if (superName && ALLOWED_SUPERCLASSES.test(superName)) return;
+      }
+
+      context.report({ node, messageId: "noClass" });
+    }
+
+    return {
+      ClassDeclaration: check,
+      ClassExpression: check,
+    };
+  },
+};