@danieljvdm/dev-kit 0.17.0 → 0.18.0

package/src/oxlint-plugin-anti-slop/rules/no-unknown-parameters.ts

@@ -0,0 +1,86 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+type Parameter = ESTree.ParamPattern;
+type ParameterOwner =
+  | ESTree.ArrowFunctionExpression
+  | ESTree.Function
+  | ESTree.TSCallSignatureDeclaration
+  | ESTree.TSConstructSignatureDeclaration
+  | ESTree.TSConstructorType
+  | ESTree.TSFunctionType
+  | ESTree.TSMethodSignature;
+
+function parameterAnnotation(parameter: Parameter): ESTree.TSTypeAnnotation | null | undefined {
+  if (parameter.type === "TSParameterProperty") {
+    return parameterAnnotation(parameter.parameter);
+  }
+  if (parameter.type === "RestElement") {
+    return parameter.typeAnnotation ?? parameterAnnotation(parameter.argument);
+  }
+  if (parameter.type === "AssignmentPattern") {
+    return parameter.typeAnnotation ?? parameter.left.typeAnnotation;
+  }
+
+  return parameter.typeAnnotation;
+}
+
+function parameterName(parameter: Parameter, sourceText: string): string {
+  if (parameter.type === "TSParameterProperty") {
+    return parameterName(parameter.parameter, sourceText);
+  }
+  if (parameter.type === "AssignmentPattern") {
+    return parameterName(parameter.left, sourceText);
+  }
+  if (parameter.type === "RestElement") {
+    return parameterName(parameter.argument, sourceText);
+  }
+
+  return parameter.type === "Identifier"
+    ? parameter.name
+    : sourceText.replace(/\s*:\s*unknown\s*$/u, "");
+}
+
+/** Disallow unknown inputs except explicitly named error-cause enrichment. */
+export const noUnknownParametersRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow explicitly unknown function parameters except `cause`; decode unknown input at its I/O boundary instead.",
+    },
+    messages: {
+      unknownParameter:
+        "Parameter `{{parameter}}` leaves input unparsed. Accept a named domain type; run the expected schema or parser at the I/O boundary before calling this function.",
+    },
+  },
+  create(context) {
+    const checkParameters = (node: ParameterOwner) => {
+      for (const parameter of node.params) {
+        const annotation = parameterAnnotation(parameter);
+
+        if (annotation?.typeAnnotation.type !== "TSUnknownKeyword") continue;
+        const name = parameterName(parameter, context.sourceCode.getText(parameter));
+
+        if (name === "cause") continue;
+        context.report({
+          node: annotation.typeAnnotation,
+          messageId: "unknownParameter",
+          data: { parameter: name },
+        });
+      }
+    };
+
+    return {
+      ArrowFunctionExpression: checkParameters,
+      FunctionDeclaration: checkParameters,
+      FunctionExpression: checkParameters,
+      TSCallSignatureDeclaration: checkParameters,
+      TSConstructSignatureDeclaration: checkParameters,
+      TSConstructorType: checkParameters,
+      TSDeclareFunction: checkParameters,
+      TSEmptyBodyFunctionExpression: checkParameters,
+      TSFunctionType: checkParameters,
+      TSMethodSignature: checkParameters,
+    };
+  },
+});

package/src/oxlint-plugin-anti-slop/rules/no-unknown-returns.ts

@@ -0,0 +1,125 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+type FunctionWithReturnType =
+  | ESTree.ArrowFunctionExpression
+  | ESTree.Function
+  | ESTree.TSCallSignatureDeclaration
+  | ESTree.TSConstructSignatureDeclaration
+  | ESTree.TSConstructorType
+  | ESTree.TSFunctionType
+  | ESTree.TSMethodSignature;
+
+function referencedAliasName(type: ESTree.TSType): string | null {
+  if (type.type === "TSParenthesizedType") return referencedAliasName(type.typeAnnotation);
+  if (type.type !== "TSTypeReference" || type.typeName.type !== "Identifier") return null;
+
+  return type.typeArguments === null ||
+    type.typeArguments === undefined ||
+    type.typeArguments.params.length === 0
+    ? type.typeName.name
+    : null;
+}
+
+function lexicalTypeParameterNames(node: ESTree.Node): ReadonlySet<string> {
+  const names = new Set<string>();
+  let current: ESTree.Node | null = node;
+
+  while (current !== null && current.type !== "Program") {
+    if ("typeParameters" in current) {
+      for (const parameter of current.typeParameters?.params ?? []) {
+        names.add(parameter.name.name);
+      }
+    }
+    current = current.parent;
+  }
+
+  return names;
+}
+
+/** Ban function contracts that return unknown instead of a parsed domain type. */
+export const noUnknownReturnsRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow functions whose explicit return contract is unknown or Promise<unknown>.",
+    },
+    messages: {
+      unknownReturn:
+        "This function exposes `unknown` to its caller. Parse the value at its boundary and return a named domain type.",
+    },
+  },
+  create(context) {
+    const aliases = new Map<string, ESTree.TSTypeAliasDeclaration>();
+
+    const resolvesToUnknown = (
+      type: ESTree.TSType,
+      shadowedAliases: ReadonlySet<string>,
+      visited = new Set<string>(),
+    ): boolean => {
+      if (type.type === "TSUnknownKeyword") return true;
+      if (type.type === "TSParenthesizedType") {
+        return resolvesToUnknown(type.typeAnnotation, shadowedAliases, visited);
+      }
+      if (type.type === "TSUnionType") {
+        return type.types.some((member) => resolvesToUnknown(member, shadowedAliases, visited));
+      }
+      if (
+        type.type === "TSTypeReference" &&
+        type.typeName.type === "Identifier" &&
+        (type.typeName.name === "Promise" || type.typeName.name === "PromiseLike")
+      ) {
+        const value = type.typeArguments?.params[0];
+
+        return value !== undefined && resolvesToUnknown(value, shadowedAliases, visited);
+      }
+      const name = referencedAliasName(type);
+
+      if (name === null || visited.has(name) || shadowedAliases.has(name)) return false;
+      const alias = aliases.get(name);
+
+      if (
+        alias === undefined ||
+        (alias.typeParameters !== null && alias.typeParameters !== undefined)
+      ) {
+        return false;
+      }
+      const nextVisited = new Set(visited);
+
+      nextVisited.add(name);
+
+      return resolvesToUnknown(alias.typeAnnotation, shadowedAliases, nextVisited);
+    };
+
+    const checkReturnType = (node: FunctionWithReturnType) => {
+      const annotation = node.returnType;
+
+      if (annotation === null || annotation === undefined) return;
+      if (!resolvesToUnknown(annotation.typeAnnotation, lexicalTypeParameterNames(node))) return;
+      context.report({ node: annotation.typeAnnotation, messageId: "unknownReturn" });
+    };
+
+    return {
+      Program(node) {
+        for (const statement of node.body) {
+          const declaration =
+            statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+
+          if (declaration?.type === "TSTypeAliasDeclaration") {
+            aliases.set(declaration.id.name, declaration);
+          }
+        }
+      },
+      ArrowFunctionExpression: checkReturnType,
+      FunctionDeclaration: checkReturnType,
+      FunctionExpression: checkReturnType,
+      TSCallSignatureDeclaration: checkReturnType,
+      TSConstructSignatureDeclaration: checkReturnType,
+      TSConstructorType: checkReturnType,
+      TSDeclareFunction: checkReturnType,
+      TSEmptyBodyFunctionExpression: checkReturnType,
+      TSFunctionType: checkReturnType,
+      TSMethodSignature: checkReturnType,
+    };
+  },
+});

package/src/oxlint-plugin-anti-slop/rules/no-unknown-type-aliases.ts

@@ -0,0 +1,73 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+function referencedAliasName(type: ESTree.TSType): string | null {
+  if (type.type === "TSParenthesizedType") return referencedAliasName(type.typeAnnotation);
+  if (type.type !== "TSTypeReference" || type.typeName.type !== "Identifier") return null;
+
+  return type.typeArguments === null ||
+    type.typeArguments === undefined ||
+    type.typeArguments.params.length === 0
+    ? type.typeName.name
+    : null;
+}
+
+/** Ban named aliases that merely conceal TypeScript's unknown top type. */
+export const noUnknownTypeAliasesRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow type aliases whose resolved type is unknown; unknown must remain visible at an allowed boundary.",
+    },
+    messages: {
+      unknownAlias:
+        "Type alias `{{alias}}` hides `unknown`. Keep `unknown` explicit at the parsing boundary or on an allowed `cause` field; otherwise use the parsed owner type.",
+    },
+  },
+  create(context) {
+    const aliases = new Map<string, ESTree.TSTypeAliasDeclaration>();
+
+    const resolvesToUnknown = (type: ESTree.TSType, visited = new Set<string>()): boolean => {
+      if (type.type === "TSUnknownKeyword") return true;
+      if (type.type === "TSParenthesizedType")
+        return resolvesToUnknown(type.typeAnnotation, visited);
+      const name = referencedAliasName(type);
+
+      if (name === null || visited.has(name)) return false;
+      const alias = aliases.get(name);
+
+      if (
+        alias === undefined ||
+        (alias.typeParameters !== null && alias.typeParameters !== undefined)
+      ) {
+        return false;
+      }
+      const nextVisited = new Set(visited);
+
+      nextVisited.add(name);
+
+      return resolvesToUnknown(alias.typeAnnotation, nextVisited);
+    };
+
+    return {
+      Program(node) {
+        for (const statement of node.body) {
+          const declaration =
+            statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+
+          if (declaration?.type === "TSTypeAliasDeclaration") {
+            aliases.set(declaration.id.name, declaration);
+          }
+        }
+        for (const alias of aliases.values()) {
+          if (!resolvesToUnknown(alias.typeAnnotation, new Set([alias.id.name]))) continue;
+          context.report({
+            node: alias.id,
+            messageId: "unknownAlias",
+            data: { alias: alias.id.name },
+          });
+        }
+      },
+    };
+  },
+});

package/src/oxlint-plugin-anti-slop/rules/no-unsafe-dictionary-type.ts

@@ -0,0 +1,139 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+import {
+  classifyUnsafeDictionary,
+  classifyUnsafeDictionaryValue,
+  createTypeEnvironment,
+  type TypeEnvironment,
+} from "../shared/dictionary-types.ts";
+
+const typeNodeKinds: ReadonlySet<string> = new Set([
+  "JSDocNonNullableType",
+  "JSDocNullableType",
+  "JSDocUnknownType",
+  "TSAnyKeyword",
+  "TSArrayType",
+  "TSBigIntKeyword",
+  "TSBooleanKeyword",
+  "TSConditionalType",
+  "TSConstructorType",
+  "TSFunctionType",
+  "TSImportType",
+  "TSIndexedAccessType",
+  "TSInferType",
+  "TSIntersectionType",
+  "TSIntrinsicKeyword",
+  "TSLiteralType",
+  "TSMappedType",
+  "TSNamedTupleMember",
+  "TSNeverKeyword",
+  "TSNullKeyword",
+  "TSNumberKeyword",
+  "TSObjectKeyword",
+  "TSParenthesizedType",
+  "TSStringKeyword",
+  "TSSymbolKeyword",
+  "TSTemplateLiteralType",
+  "TSThisType",
+  "TSTupleType",
+  "TSTypeLiteral",
+  "TSTypeOperator",
+  "TSTypePredicate",
+  "TSTypeQuery",
+  "TSTypeReference",
+  "TSUndefinedKeyword",
+  "TSUnionType",
+  "TSUnknownKeyword",
+  "TSVoidKeyword",
+]);
+
+function isTypeNode(node: ESTree.Node): node is ESTree.TSType {
+  return typeNodeKinds.has(node.type);
+}
+
+function typeReferenceName(type: ESTree.TSTypeReference): string | null {
+  return type.typeName.type === "Identifier" ? type.typeName.name : null;
+}
+
+function isInsideTypeAliasDeclaration(node: ESTree.Node): boolean {
+  let current: ESTree.Node | null = node.parent;
+
+  while (current !== null && current.type !== "Program") {
+    if (current.type === "TSTypeAliasDeclaration") return true;
+    current = current.parent;
+  }
+
+  return false;
+}
+
+function isPlainAliasConsumerUse(node: ESTree.TSType, environment: TypeEnvironment): boolean {
+  if (node.type !== "TSTypeReference" || node.typeArguments?.params.length) return false;
+  const name = typeReferenceName(node);
+
+  return name !== null && environment.aliases.has(name) && !isInsideTypeAliasDeclaration(node);
+}
+
+function shouldReportType(node: ESTree.TSType, environment: TypeEnvironment): boolean {
+  if (isPlainAliasConsumerUse(node, environment)) return false;
+  if (classifyUnsafeDictionary(node, environment) === null) return false;
+  let current: ESTree.Node | null = node.parent;
+
+  while (current !== null && current.type !== "Program") {
+    if (isTypeNode(current) && classifyUnsafeDictionary(current, environment) !== null)
+      return false;
+    current = current.parent;
+  }
+
+  return true;
+}
+
+/** Disallow object-dictionary contracts whose direct value type is an unsafe escape hatch. */
+export const noUnsafeDictionaryTypeRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow object-dictionary contracts whose direct value type is unknown, any, object, {}, or a union/alias containing one of those escape hatches.",
+    },
+    messages: {
+      unsafeDictionary:
+        "This dictionary's {{value}} value type gives callers no concrete value contract. Use an owner/schema-derived value type; parse external payloads before insertion.",
+    },
+  },
+  createOnce(context) {
+    let environment: TypeEnvironment | null = null;
+    const report = (node: ESTree.Node, value: string) => {
+      context.report({ node, messageId: "unsafeDictionary", data: { value } });
+    };
+    const reportIfUnsafe = (node: ESTree.TSType) => {
+      if (environment === null || !shouldReportType(node, environment)) return;
+      const unsafe = classifyUnsafeDictionary(node, environment);
+
+      if (unsafe === null) return;
+      report(node, unsafe.unsafeValue);
+    };
+
+    return {
+      Program(node) {
+        environment = createTypeEnvironment(node);
+      },
+      TSTypeReference: reportIfUnsafe,
+      TSTypeLiteral: reportIfUnsafe,
+      TSMappedType: reportIfUnsafe,
+      TSIndexSignature(node) {
+        if (
+          environment === null ||
+          node.typeAnnotation === null ||
+          node.parent.type === "TSTypeLiteral"
+        )
+          return;
+        const unsafe = classifyUnsafeDictionaryValue(
+          node.typeAnnotation.typeAnnotation,
+          environment,
+        );
+
+        if (unsafe !== null) report(node, unsafe.unsafeValue);
+      },
+    };
+  },
+});