@heyramzi/lint 0.0.0-stage → 1.32.4

package/rules/no-known-value-widening.js

@@ -0,0 +1,289 @@
+/**
+ * Disallow widening a syntactically known value to a broad type.
+ */
+
+/*
+ * When the initializer is a literal, an object, an array or a function, the compiler already knows the type.
+ */
+
+/*
+ * Annotating the binding `unknown`, `any`, `object` or `Record<string, unknown>` throws that away, and the next reader has to assert it back. Keep inference, or use `satisfies`, or name a contract.
+ */
+
+/*
+ * Empty objects and empty arrays are exempt: they are accumulators, not evidence.
+ */
+
+/*
+ * So are bindings that are mutated later in the file (`x.y = ...`, `Object.assign(x, ...)`): there the wide annotation is what makes the later writes legal, not laziness.
+ */
+
+/*
+ * Simplified from dmmulroy/anti-slop (MIT). The original resolves aliases across a whole type environment; this checks the annotation and the initializer only, which is where the pattern actually shows up.
+ */
+
+const BROAD_KEYWORDS = new Set(["TSUnknownKeyword", "TSAnyKeyword", "TSObjectKeyword"]);
+
+const BROAD_RECORD_KEYS = new Set(["TSStringKeyword", "TSNumberKeyword", "TSSymbolKeyword"]);
+
+/** Initializers whose type the compiler can read straight off the syntax. */
+const KNOWN_VALUE_TYPES = new Set([
+  "ArrayExpression",
+  "ArrowFunctionExpression",
+  "ClassExpression",
+  "FunctionExpression",
+  "Literal",
+  "NewExpression",
+  "ObjectExpression",
+  "TemplateLiteral",
+]);
+
+function unwrapType(type) {
+  let current = type;
+  while (current?.type === "TSParenthesizedType") current = current.typeAnnotation;
+  return current;
+}
+
+function unwrapExpression(node) {
+  let current = node;
+  while (current?.type === "ParenthesizedExpression") current = current.expression;
+  return current;
+}
+
+function typeReferenceName(type) {
+  return type.typeName?.type === "Identifier" ? type.typeName.name : null;
+}
+
+function isTopType(type) {
+  const unwrapped = unwrapType(type);
+  return unwrapped?.type === "TSUnknownKeyword" || unwrapped?.type === "TSAnyKeyword";
+}
+
+function isBroadRecordKey(type) {
+  const unwrapped = unwrapType(type);
+  if (!unwrapped) return false;
+  if (BROAD_RECORD_KEYS.has(unwrapped.type)) return true;
+  if (unwrapped.type === "TSUnionType") return unwrapped.types.every(isBroadRecordKey);
+  return unwrapped.type === "TSTypeReference" && typeReferenceName(unwrapped) === "PropertyKey";
+}
+
+/** `Record<string, unknown>` and the index-signature spelling of the same thing. */
+function isBroadRecord(type) {
+  const unwrapped = unwrapType(type);
+  if (!unwrapped) return false;
+
+  if (unwrapped.type === "TSTypeReference") {
+    if (typeReferenceName(unwrapped) !== "Record") return false;
+    const params = unwrapped.typeArguments?.params ?? [];
+    return params.length === 2 && isBroadRecordKey(params[0]) && isTopType(params[1]);
+  }
+
+  if (unwrapped.type !== "TSTypeLiteral" || unwrapped.members.length !== 1) return false;
+  const [member] = unwrapped.members;
+  if (member?.type !== "TSIndexSignature" || member.parameters.length !== 1) return false;
+  const [parameter] = member.parameters;
+  return (
+    isBroadRecordKey(parameter?.typeAnnotation?.typeAnnotation) &&
+    isTopType(member.typeAnnotation?.typeAnnotation)
+  );
+}
+
+function broadTypeName(type) {
+  const unwrapped = unwrapType(type);
+  if (!unwrapped) return null;
+  if (BROAD_KEYWORDS.has(unwrapped.type)) {
+    return unwrapped.type === "TSObjectKeyword"
+      ? "object"
+      : unwrapped.type === "TSAnyKeyword"
+        ? "any"
+        : "unknown";
+  }
+  return isBroadRecord(unwrapped) ? "open dictionary" : null;
+}
+
+/** Accumulators start empty and get filled; that is not discarded evidence. */
+function isEmptyContainer(node) {
+  const unwrapped = unwrapExpression(node);
+  if (unwrapped?.type === "ObjectExpression") return unwrapped.properties.length === 0;
+  if (unwrapped?.type === "ArrayExpression") return unwrapped.elements.length === 0;
+  return false;
+}
+
+/** `null` and `undefined` are placeholders awaiting a real value, not evidence. */
+function isPlaceholder(node) {
+  const unwrapped = unwrapExpression(node);
+  if (unwrapped?.type === "Identifier") return unwrapped.name === "undefined";
+  return unwrapped?.type === "Literal" && unwrapped.value === null;
+}
+
+function isKnownValue(node) {
+  const unwrapped = unwrapExpression(node);
+  if (!unwrapped) return false;
+  if (isPlaceholder(unwrapped)) return false;
+  // `x as const` keeps its evidence; anything else asserted is already covered
+  // by no-chained-type-assertions and require-safety-comment-for-type-assertion.
+  if (unwrapped.type === "TSAsExpression") {
+    const annotation = unwrapped.typeAnnotation;
+    return (
+      annotation?.type === "TSTypeReference" &&
+      annotation.typeName?.type === "Identifier" &&
+      annotation.typeName.name === "const"
+    );
+  }
+  return KNOWN_VALUE_TYPES.has(unwrapped.type) && !isEmptyContainer(unwrapped);
+}
+
+/** `x.y = ...` and `Object.assign(x, ...)`: both need `x` to stay wide. */
+function isMutationOf(node, names, reassigned) {
+  if (node.type === "AssignmentExpression") {
+    const { left } = node;
+    if (left?.type === "MemberExpression" && left.object?.type === "Identifier") {
+      names.add(left.object.name);
+    } else if (left?.type === "Identifier") {
+      reassigned.add(left.name);
+    }
+    return;
+  }
+  if (node.type !== "CallExpression") return;
+  const callee = node.callee;
+  if (
+    callee?.type === "MemberExpression" &&
+    callee.object?.type === "Identifier" &&
+    callee.object.name === "Object" &&
+    callee.property?.name === "assign"
+  ) {
+    const [target] = node.arguments;
+    if (target?.type === "Identifier") names.add(target.name);
+  }
+}
+
+function collectMutatedNames(root, names, reassigned) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    isMutationOf(node, names, reassigned);
+    for (const key of Object.keys(node)) {
+      if (key === "parent") continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child != null && typeof child.type === "string") stack.push(child);
+        }
+      } else if (value != null && typeof value.type === "string") {
+        stack.push(value);
+      }
+    }
+  }
+}
+
+function referencesName(root, name) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current.type === "Identifier" && current.name === name) return true;
+    for (const key of Object.keys(current)) {
+      if (key === "parent") continue;
+      const value = current[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child != null && typeof child.type === "string") stack.push(child);
+        }
+      } else if (value != null && typeof value.type === "string") {
+        stack.push(value);
+      }
+    }
+  }
+  return false;
+}
+
+function functionOwnName(node) {
+  if (node.id?.name) return node.id.name;
+  const parent = node.parent;
+  if (parent?.type === "VariableDeclarator" && parent.id?.type === "Identifier") {
+    return parent.id.name;
+  }
+  return null;
+}
+
+/**
+ * A function that calls itself has no inferable return type, so the annotation
+ * is load-bearing rather than lazy. Removing it would only produce TS7023.
+ */
+function isRecursive(node) {
+  const name = functionOwnName(node);
+  if (name === null || node.body == null) return false;
+  return referencesName(node.body, name);
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow annotating a known value with a broad type that discards its evidence.",
+    },
+    messages: {
+      widening:
+        "The explicit `{{target}}` type on {{subject}} discards known type evidence. Keep inference, validate with `satisfies`, or name a contract.",
+    },
+    schema: [],
+  },
+  create(context) {
+    // WHY: name-based rather than scope-resolved. A shadowed name in the same
+    // file only ever costs a missed report, never a wrong one.
+    const mutatedNames = new Set();
+    const reassignedNames = new Set();
+
+    const report = (valueNode, annotation, subject) => {
+      const target = annotation ? broadTypeName(annotation.typeAnnotation) : null;
+      if (target === null || !isKnownValue(valueNode)) return;
+      context.report({ node: valueNode, messageId: "widening", data: { subject, target } });
+    };
+
+    return {
+      // WHY: a mutation sits below its declaration, so visitor order would reach
+      // the declarator first. Collect every mutated name up front instead.
+      Program(node) {
+        mutatedNames.clear();
+        reassignedNames.clear();
+        collectMutatedNames(node, mutatedNames, reassignedNames);
+      },
+      VariableDeclarator(node) {
+        if (node.init == null || node.id.type !== "Identifier") return;
+        if (mutatedNames.has(node.id.name)) return;
+        // A `let` that is reassigned later declares the type of its whole lifetime,
+        // not of its first value. `const` gets no such exemption.
+        if (node.parent?.kind !== "const" && reassignedNames.has(node.id.name)) return;
+        // A binding read inside its own initializer (a Proxy handler, a stub whose
+        // methods return it) has no inferable type; dropping the annotation gives TS7022.
+        if (referencesName(node.init, node.id.name)) return;
+        report(node.init, node.id.typeAnnotation, `binding \`${node.id.name}\``);
+      },
+      PropertyDefinition(node) {
+        if (node.value == null) return;
+        report(node.value, node.typeAnnotation, "this property");
+      },
+      ReturnStatement(node) {
+        if (node.argument == null) return;
+        let owner = node.parent;
+        while (owner && owner.type !== "Program") {
+          if (
+            owner.type === "ArrowFunctionExpression" ||
+            owner.type === "FunctionDeclaration" ||
+            owner.type === "FunctionExpression"
+          ) {
+            break;
+          }
+          owner = owner.parent;
+        }
+        if (!owner || owner.type === "Program") return;
+        if (isRecursive(owner)) return;
+        report(node.argument, owner.returnType, "this return value");
+      },
+      ArrowFunctionExpression(node) {
+        if (node.body.type === "BlockStatement" || isRecursive(node)) return;
+        report(node.body, node.returnType, "this return value");
+      },
+    };
+  },
+};

package/rules/no-legacy-compat.js

@@ -0,0 +1,35 @@
+/**
+ * A re-export renamed to a leading `_` keeps a dead name alive. Compat words in comments are
+ * the comment gate's job: `comment-length.js`.
+ */
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow re-exports renamed to a leading `_`. Delete the unused name instead.",
+    },
+    messages: {
+      unusedRename:
+        'Suspicious rename to "_{{ name }}". If the original is unused, delete it instead of renaming with a leading "_" prefix.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      ExportNamedDeclaration(node) {
+        if (!node.source) return;
+        for (const specifier of node.specifiers) {
+          const exported = specifier.exported.name ?? specifier.exported.value;
+          const local = specifier.local.name ?? specifier.local.value;
+          if (exported !== local && exported.startsWith("_")) {
+            context.report({
+              node: specifier,
+              messageId: "unusedRename",
+              data: { name: exported },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-overkill-fallback.js

@@ -0,0 +1,77 @@
+// Warns about overkill nullish coalescing patterns: 1. Triple ?? chains: `a ?? b ?? c` (defensive over-engineering) 2. Trailing `?? null`: `x?.foo ?? null` (no-op, undefined is already nullish)
+
+// 3. Trailing `?? ""`: `x ?? ""` (empty string fallbacks rarely needed) 4. `(x?.length ?? 0) > 0` (verbose, `x?.length` is truthy when > 0)
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow overkill nullish coalescing patterns (triple chains, ?? null, ?? '').",
+    },
+    messages: {
+      tripleChain: "Triple ?? chain is overkill. Simplify to at most two levels.",
+      trailingNull:
+        "'?? null' is redundant. The expression already evaluates to undefined/null without it.",
+      trailingEmptyString:
+        "'?? \"\"' is likely redundant. Template strings and most contexts handle undefined gracefully.",
+      verboseLengthCheck:
+        "'(x?.length ?? 0) > 0' is verbose. Use 'x?.length' as a truthy check or 'x.length > 0' if non-nullable.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      LogicalExpression(node) {
+        if (node.operator !== "??") return;
+
+        // Rule 1: Triple ?? chain, a ?? b ?? c
+        // The outermost ?? has left side that is also a ??
+        if (node.left.type === "LogicalExpression" && node.left.operator === "??") {
+          context.report({ node, messageId: "tripleChain" });
+          return;
+        }
+
+        // Rule 2: Trailing ?? null
+        if (node.right.type === "Literal" && node.right.value === null) {
+          context.report({ node, messageId: "trailingNull" });
+          return;
+        }
+
+        // Rule 3: Trailing ?? ""
+        if (
+          node.right.type === "Literal" &&
+          node.right.value === "" &&
+          typeof node.right.value === "string"
+        ) {
+          context.report({ node, messageId: "trailingEmptyString" });
+          return;
+        }
+      },
+
+      // Rule 4: (x?.length ?? 0) > 0
+      BinaryExpression(node) {
+        if (node.operator !== ">" && node.operator !== ">=") return;
+        if (node.right.type !== "Literal" || node.right.value !== 0) return;
+
+        // Check if left is (x?.length ?? 0) wrapped in parens or not
+        const left = node.left;
+        if (
+          left.type === "LogicalExpression" &&
+          left.operator === "??" &&
+          left.right.type === "Literal" &&
+          left.right.value === 0
+        ) {
+          // Check that left.left ends with .length
+          const inner = left.left;
+          if (
+            inner.type === "MemberExpression" &&
+            inner.property.type === "Identifier" &&
+            inner.property.name === "length"
+          ) {
+            context.report({ node, messageId: "verboseLengthCheck" });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-raw-try-catch.js

@@ -0,0 +1,26 @@
+/**
+ * Disallow raw try/catch blocks in favor of tryCatch() / tryCatchAsync().
+ * These helpers from @heyramzi/utils return a Result<T, E> for typed error handling.
+ */
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow raw try/catch blocks. Use tryCatch() or tryCatchAsync() from @heyramzi/utils instead.",
+    },
+    messages: {
+      noRawTryCatch:
+        "Avoid raw try/catch. Use tryCatch() for sync or tryCatchAsync() for async contexts from @heyramzi/utils.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TryStatement(node) {
+        context.report({ node, messageId: "noRawTryCatch" });
+      },
+    };
+  },
+};

package/rules/no-redundant-prop-fallback.js

@@ -0,0 +1,153 @@
+/**
+ * Ban a `||` or `??` fallback that repeats the default the prop already has in its destructuring.
+ */
+
+/*
+ * Bad: `let { font = 'sans' } = $props()` then `font || 'sans'`. A different fallback passes, since `null` and `""` slip past a default. Covers parameters, `$props()` and markup.
+ */
+import { readTemplate } from "#lint/svelte-template.js";
+
+/** A literal's identity as a string: `s:sans`, `n:3`, `b:true`, `null`. */
+function literalKey(node) {
+  if (node?.type !== "Literal" || node.regex || typeof node.value === "bigint") return null;
+  if (node.value === null) return "null";
+  const kind = { string: "s", number: "n", boolean: "b" }[typeof node.value];
+  return kind ? `${kind}:${node.value}` : null;
+}
+
+/** `= "x"` and `= $bindable("x")` both default to "x". `$bindable()` defaults to nothing. */
+function defaultKey(assignment) {
+  const right = assignment.right;
+  if (right.type === "CallExpression" && right.callee?.name === "$bindable") {
+    return literalKey(right.arguments[0]);
+  }
+  return literalKey(right);
+}
+
+function collectDefaults(pattern, into) {
+  if (pattern?.type !== "ObjectPattern") return;
+  for (const prop of pattern.properties) {
+    if (prop.type !== "Property" || prop.value?.type !== "AssignmentPattern") continue;
+    const name = prop.value.left?.name || prop.key?.name;
+    const key = defaultKey(prop.value);
+    if (name && key !== null) into.set(name, key);
+  }
+}
+
+function paramNames(pattern, into) {
+  if (!pattern) return;
+  if (pattern.type === "Identifier") into.add(pattern.name);
+  else if (pattern.type === "AssignmentPattern") paramNames(pattern.left, into);
+  else if (pattern.type === "RestElement") paramNames(pattern.argument, into);
+  else if (pattern.type === "ArrayPattern") pattern.elements.forEach((e) => paramNames(e, into));
+  else if (pattern.type === "ObjectPattern") {
+    for (const prop of pattern.properties) {
+      paramNames(prop.type === "RestElement" ? prop.argument : prop.value, into);
+    }
+  }
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The key of a literal as written in markup: `'sans'`, `3`, `true`. */
+function markupKey(token) {
+  if (/^["']/.test(token)) return `s:${token.slice(1, -1)}`;
+  if (/^-?\d/.test(token)) return `n:${Number(token)}`;
+  return token === "null" ? "null" : `b:${token}`;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow a || / ?? fallback that repeats the default a prop already has in its destructuring.",
+    },
+    messages: {
+      redundantFallback:
+        "'{{ name }}' already defaults to the same value in destructuring. Remove the '{{ op }}' fallback.",
+      redundantMarkupFallback:
+        "'{{ name }}' already defaults to the same value in `$props()`, but line {{ line }} falls back again with '{{ op }}'. Use '{{ name }}' alone.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const scopeStack = [];
+    const propDefaults = new Map();
+
+    function enterFunction(node) {
+      const defaults = new Map();
+      const params = new Set();
+      for (const param of node.params || []) {
+        collectDefaults(param, defaults);
+        paramNames(param, params);
+      }
+      scopeStack.push({ defaults, params });
+    }
+
+    function exitFunction() {
+      scopeStack.pop();
+    }
+
+    function checkLogical(node) {
+      if (node.operator !== "||" && node.operator !== "??") return;
+      const { left, right } = node;
+      if (left.type !== "Identifier") return;
+      const rightKey = literalKey(right);
+      if (rightKey === null) return;
+
+      const current = scopeStack[scopeStack.length - 1];
+      const shadowed = scopeStack.some((scope) => scope.params.has(left.name));
+      const known =
+        current?.defaults.get(left.name) ?? (shadowed ? undefined : propDefaults.get(left.name));
+      if (known === rightKey) {
+        context.report({
+          node,
+          messageId: "redundantFallback",
+          data: { name: left.name, op: node.operator },
+        });
+      }
+    }
+
+    function checkMarkup() {
+      if (!context.filename.endsWith(".svelte") || propDefaults.size === 0) return;
+      const template = readTemplate(context.filename);
+      if (!template) return;
+      const blockText = template.blocks.map((block) => block.code).join("\n");
+      for (const [name, key] of propDefaults) {
+        // A loop variable or snippet parameter of the same name isn't the prop.
+        if (new RegExp(`(?<![\\w$.])${escapeRegExp(name)}(?![\\w$])`).test(blockText)) continue;
+        const fallback = new RegExp(
+          `(?<![\\w$.])${escapeRegExp(name)}\\s*(\\?\\?|\\|\\|)\\s*("[^"\\\\]*"|'[^'\\\\]*'|-?\\d[\\w.]*|true|false|null)(?![\\w$.(\\[])`,
+        );
+        for (const expression of template.expressions) {
+          const match = fallback.exec(expression.code);
+          if (!match || markupKey(match[2]) !== key) continue;
+          context.report({
+            loc: { line: 1, column: 0 },
+            messageId: "redundantMarkupFallback",
+            data: { name, op: match[1], line: String(expression.line) },
+          });
+        }
+      }
+    }
+
+    return {
+      FunctionDeclaration: enterFunction,
+      FunctionExpression: enterFunction,
+      ArrowFunctionExpression: enterFunction,
+      "FunctionDeclaration:exit": exitFunction,
+      "FunctionExpression:exit": exitFunction,
+      "ArrowFunctionExpression:exit": exitFunction,
+      VariableDeclarator(node) {
+        if (node.init?.type === "CallExpression" && node.init.callee?.name === "$props") {
+          collectDefaults(node.id, propDefaults);
+        }
+      },
+      LogicalExpression: checkLogical,
+      "Program:exit": checkMarkup,
+    };
+  },
+};