feat: Lint plugin POC (#2097)

Author: aleksanderkatan

packages/eslint-plugin/README.md

@@ -0,0 +1,8 @@
+<div align="center">
+
+# eslint-plugin-typegpu
+
+🚧 **Under Construction** 🚧 -
+[GitHub](https://github.com/software-mansion/TypeGPU/tree/main/packages/eslint-plugin)
+
+</div>

packages/eslint-plugin/deno.json

@@ -0,0 +1,7 @@
+{
+  "exclude": ["."],
+  "fmt": {
+    "exclude": ["!."],
+    "singleQuote": true
+  }
+}

packages/eslint-plugin/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "eslint-plugin-typegpu",
+  "version": "0.9.0",
+  "description": "An eslint plugin containing custom rules for TypeGPU.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test:types": "pnpm tsc --p ./tsconfig.json --noEmit",
+    "test": "vitest"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.1",
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.53.0"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/rule-tester": "^8.53.1",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}

packages/eslint-plugin/src/configs.ts

@@ -0,0 +1,19 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+import { integerDivision } from './rules/integerDivision.ts';
+
+export const rules = {
+  'integer-division': integerDivision,
+} as const;
+
+type Rules = Record<
+  `typegpu/${keyof typeof rules}`,
+  TSESLint.FlatConfig.RuleEntry
+>;
+
+export const recommendedRules: Rules = {
+  'typegpu/integer-division': 'warn',
+};
+
+export const allRules: Rules = {
+  'typegpu/integer-division': 'error',
+};

packages/eslint-plugin/src/index.ts

@@ -0,0 +1,33 @@
+import pkg from '../package.json';
+import type { TSESLint } from '@typescript-eslint/utils';
+import { allRules, recommendedRules, rules } from './configs.ts';
+
+const pluginBase: TSESLint.FlatConfig.Plugin = {
+  meta: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  rules,
+};
+
+const recommended: TSESLint.FlatConfig.Config = {
+  name: 'typegpu/recommended',
+  plugins: { typegpu: pluginBase },
+  rules: recommendedRules,
+};
+
+const all: TSESLint.FlatConfig.Config = {
+  name: 'typegpu/all',
+  plugins: { typegpu: pluginBase },
+  rules: allRules,
+};
+
+const plugin: TSESLint.FlatConfig.Plugin = {
+  ...pluginBase,
+  configs: {
+    recommended,
+    all,
+  },
+};
+
+export default plugin;

packages/eslint-plugin/src/ruleCreator.ts

@@ -0,0 +1,6 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+export const createRule = ESLintUtils.RuleCreator(
+  // TODO: docs for lint rules
+  () => `https://docs.swmansion.com/TypeGPU/getting-started/`,
+);

packages/eslint-plugin/src/rules/integerDivision.ts

@@ -0,0 +1,61 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { createRule } from '../ruleCreator.ts';
+
+// TODO: detect `std.div(d.u32(1), d.u32(2))`
+export const integerDivision = createRule({
+  name: 'integer-division',
+  meta: {
+    type: 'suggestion',
+    docs: { description: `Avoid dividing numbers wrapped in 'u32' and 'i32'.` },
+    messages: {
+      intDiv:
+        "'{{snippet}}' might result in floating point values. To perform integer division, wrap the result in 'd.u32' or 'd.i32' instead.",
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create(context) {
+    return {
+      BinaryExpression(node) {
+        if (node.operator !== '/') {
+          return;
+        }
+
+        if (node.parent?.type === 'CallExpression' && isIntCast(node.parent)) {
+          return;
+        }
+
+        if (isIntCast(node.left) || isIntCast(node.right)) {
+          context.report({
+            node,
+            messageId: 'intDiv',
+            data: { snippet: context.sourceCode.getText(node) },
+          });
+        }
+      },
+    };
+  },
+});
+
+/**
+ * Checks if a node is a call expression to an integer cast function (i32 or u32).
+ *
+ * @example
+ * // for simplicity, using code snippets instead of ASTs
+ * isIntCasts('d.u32()'); // true
+ * isIntCasts('i32()'); // true
+ * isIntCasts('f32()'); // false
+ */
+function isIntCast(node: TSESTree.Expression): boolean {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+
+  let callee: TSESTree.Node = node.callee;
+  while (callee.type === 'MemberExpression') {
+    callee = callee.property;
+  }
+
+  return callee.type === 'Identifier' && ['i32', 'u32'].includes(callee.name);
+}

packages/eslint-plugin/tests/integerDivision.test.ts

@@ -0,0 +1,60 @@
+import { describe } from 'vitest';
+import { integerDivision } from '../src/rules/integerDivision.ts';
+import { ruleTester } from './ruleTester.ts';
+
+describe('integerDivision', () => {
+  ruleTester.run('integerDivision', integerDivision, {
+    valid: [
+      '1 / 2',
+      'd.u32(d.u32(1) / d.u32(2))',
+    ],
+    invalid: [
+      {
+        code: 'd.u32(1) / 2',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: 'd.u32(1) / 2' } },
+        ],
+      },
+      {
+        code: '1 / d.u32(2)',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: '1 / d.u32(2)' } },
+        ],
+      },
+      {
+        code: 'd.u32(1) / d.u32(2)',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: 'd.u32(1) / d.u32(2)' } },
+        ],
+      },
+      {
+        code: 'd.i32(1) / d.i32(2)',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: 'd.i32(1) / d.i32(2)' } },
+        ],
+      },
+      {
+        code: 'd.u32(1) / d.i32(2)',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: 'd.u32(1) / d.i32(2)' } },
+        ],
+      },
+      {
+        code: 'u32(1) / u32(2)',
+        errors: [
+          { messageId: 'intDiv', data: { snippet: 'u32(1) / u32(2)' } },
+        ],
+      },
+      {
+        code: 'd.u32(1) / d.u32(2) / d.u32(3)',
+        errors: [
+          {
+            messageId: 'intDiv',
+            data: { snippet: 'd.u32(1) / d.u32(2) / d.u32(3)' },
+          },
+          { messageId: 'intDiv', data: { snippet: 'd.u32(1) / d.u32(2)' } },
+        ],
+      },
+    ],
+  });
+});

packages/eslint-plugin/tests/ruleTester.ts

@@ -0,0 +1,10 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+
+// RuleTester relies on global hooks for tests.
+// Vitest doesn't make the hooks available globally, so we need to bind them.
+RuleTester.describe = describe;
+RuleTester.it = it;
+RuleTester.afterAll = afterAll;
+
+export const ruleTester = new RuleTester();

packages/eslint-plugin/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}