chore: add exported-function-args-maximum Deno Style Guide linter plugin (#6561)

Author: timreichen

_tools/lint_plugin.ts

@@ -7,6 +7,8 @@
  */
 
 import { toCamelCase, toPascalCase } from "@std/text";
+import { toFileUrl } from "@std/path/to-file-url";
+import { resolve } from "@std/path/resolve";
 
 const PASCAL_CASE_REGEXP = /^_?(?:[A-Z][a-z0-9]*)*_?$/;
 const UPPER_CASE_ONLY = /^_?[A-Z]{2,}$/;
@@ -310,5 +312,69 @@ export default {
         };
       },
     },
+    // https://docs.deno.com/runtime/contributing/style_guide/#exported-functions%3A-max-2-args%2C-put-the-rest-into-an-options-object
+    "exported-function-args-maximum": {
+      create(context) {
+        const url = toFileUrl(resolve(context.filename));
+
+        // assertions and testing utils generally don't follow this rule
+        if (url.href.includes("/assert/")) return {};
+        if (url.href.includes("/testing/mock.ts")) return {};
+        if (url.href.includes("/testing/unstable_stub.ts")) return {};
+        if (url.href.includes("/testing/snapshot.ts")) return {};
+
+        // exports from private utils don't need to follow this rule
+        if (url.href.includes("/_")) return {};
+        // internal exports don't need to follow this rule
+        if (url.href.includes("/internal/")) return {};
+        // bytes API generally don't follow this rule
+        if (url.href.includes("/bytes/")) return {};
+
+        return {
+          ExportNamedDeclaration(node) {
+            if (node.declaration?.type !== "FunctionDeclaration") return;
+            const { params, id } = node.declaration;
+            if (params.length < 3) return;
+            if (params.length === 3) {
+              const param = params.at(-1)!;
+
+              switch (param.type) {
+                case "Identifier":
+                  if (param.name === "options") return;
+                  // Function as 3rd argument is valid (e.g. pooledMap)
+                  if (
+                    param.typeAnnotation?.typeAnnotation?.type ===
+                      "TSFunctionType"
+                  ) return;
+                  // attributes: Pick<T, "foo" | "bar"> as 3rd argument is valid
+                  if (
+                    param.typeAnnotation?.typeAnnotation?.typeName?.name ===
+                      "Pick"
+                  ) return;
+                  break;
+                case "AssignmentPattern": {
+                  if (param.right.type === "ObjectExpression") return;
+                  break;
+                }
+              }
+
+              return context.report({
+                node: id ?? declaration,
+                message:
+                  "Third argument of export function is not an options object or function.",
+                hint:
+                  "Export functions can have 0-2 required arguments, plus (if necessary) an options object (so max 3 total).",
+              });
+            }
+            context.report({
+              node: id ?? declaration,
+              message: "Exported function has more than three arguments.",
+              hint:
+                "Export functions can have 0-2 required arguments, plus (if necessary) an options object (so max 3 total).",
+            });
+          },
+        };
+      },
+    },
   },
 } satisfies Deno.lint.Plugin;

_tools/lint_plugin_test.ts

@@ -310,3 +310,67 @@ new CustomError("Can't parse input");
     ],
   );
 });
+
+Deno.test("deno-style-guide/exported-function-args-maximum", {
+  ignore: !Deno.version.deno.startsWith("2"),
+}, () => {
+  // Good
+  assertLintPluginDiagnostics(
+    `
+function foo() {
+}
+function foo(bar: unknown) {
+}
+function foo(bar: unknown, baz: unknown) {
+}
+function foo(bar: unknown, baz: unknown, options: Record<string, unknown>) {
+}
+function foo(bar: unknown, baz: unknown, bat: unknown, bay: unknown) {
+}
+export function foo() {
+}
+export function foo(bar: unknown) {
+}
+export function foo(bar: unknown, baz: unknown) {
+}
+export function foo(bar: unknown, baz: unknown, options: Record<string, unknown>) {
+}
+// function as last argument is allowed
+export function foo(bar: unknown, baz: unknown, bat: () => unknown) {
+}
+// Pick<T> is usually an object
+export function foo(bar: unknown, baz: unknown, bat: Pick<SomeType, "foo">) {
+}
+    `,
+    [],
+  );
+
+  // Bad
+  assertLintPluginDiagnostics(
+    `
+export function foo(bar: unknown, baz: unknown, bat: unknown) {
+}
+export function foo(bar: unknown, baz: unknown, bat: unknown, options: Record<string, unknown>) {
+}
+`,
+    [
+      {
+        fix: [],
+        hint:
+          "Export functions can have 0-2 required arguments, plus (if necessary) an options object (so max 3 total).",
+        id: "deno-style-guide/exported-function-args-maximum",
+        message:
+          "Third argument of export function is not an options object or function.",
+        range: [17, 20],
+      },
+      {
+        fix: [],
+        hint:
+          "Export functions can have 0-2 required arguments, plus (if necessary) an options object (so max 3 total).",
+        id: "deno-style-guide/exported-function-args-maximum",
+        message: "Exported function has more than three arguments.",
+        range: [83, 86],
+      },
+    ],
+  );
+});

collections/reduce_groups.ts

@@ -36,6 +36,7 @@ import { mapValues } from "./map_values.ts";
  * });
  * ```
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function reduceGroups<T, A>(
   record: Readonly<Record<string, ReadonlyArray<T>>>,
   reducer: (accumulator: A, current: T) => A,

collections/running_reduce.ts

@@ -26,6 +26,7 @@
  * assertEquals(sumSteps, [1, 3, 6, 10, 15]);
  * ```
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function runningReduce<T, O>(
   array: readonly T[],
   reducer: (accumulator: O, current: T, currentIndex: number) => O,

encoding/varint.ts

@@ -215,6 +215,7 @@ export function decodeVarint32(buf: Uint8Array, offset = 0): [number, number] {
  * assertEquals(encodeVarint(42n, buf), [new Uint8Array([42]), 1]);
  * ```
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function encodeVarint(
   num: bigint | number,
   buf: Uint8Array = new Uint8Array(MaxVarintLen64),

fs/unstable_chown.ts

@@ -24,6 +24,7 @@ import { mapError } from "./_map_error.ts";
  * @param uid The user id (UID) of the new owner, or `null` for no change.
  * @param gid The group id (GID) of the new owner, or `null` for no change.
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export async function chown(
   path: string | URL,
   uid: number | null,
@@ -61,6 +62,7 @@ export async function chown(
  * @param uid The user id (UID) of the new owner, or `null` for no change.
  * @param gid The group id (GID) of the new owner, or `null` for no change.
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function chownSync(
   path: string | URL,
   uid: number | null,

fs/unstable_utime.ts

@@ -32,6 +32,7 @@ import { mapError } from "./_map_error.ts";
  * @param atime The new access time
  * @param mtime The new modification time
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export async function utime(
   path: string | URL,
   atime: number | Date,
@@ -78,6 +79,7 @@ export async function utime(
  * @param atime The new access time
  * @param mtime The new modification time
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function utimeSync(
   path: string | URL,
   atime: number | Date,

streams/to_transform_stream.ts

@@ -60,6 +60,7 @@
  * );
  * ```
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function toTransformStream<I, O>(
   transformer: (src: ReadableStream<I>) => Iterable<O> | AsyncIterable<O>,
   writableStrategy?: QueuingStrategy<I>,

webgpu/create_capture.ts

@@ -70,6 +70,7 @@ export interface CreateCapture {
  * @param height The height of the capture texture.
  * @returns The texture to render to and buffer to read from.
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function createCapture(
   device: GPUDevice,
   width: number,

webgpu/row_padding.ts

@@ -70,6 +70,7 @@ export function getRowPadding(width: number): Padding {
  * @param height The height of the output buffer.
  * @returns The resliced buffer.
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function resliceBufferWithPadding(
   buffer: Uint8Array,
   width: number,

webgpu/texture_with_data.ts

@@ -120,6 +120,7 @@ function textureMipLevelSize(
  * @param data The data to write to the texture.
  * @returns The newly created texture.
  */
+// deno-lint-ignore deno-style-guide/exported-function-args-maximum
 export function createTextureWithData(
   device: GPUDevice,
   descriptor: GPUTextureDescriptor,