@dudousxd/nestjs-durable-eslint-plugin 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# @dudousxd/nestjs-durable-eslint-plugin
+
+Lint for non-deterministic sources inside a durable `@Workflow` — `Date.now()`, `Math.random()`,
+`new Date()`, `crypto.randomUUID()`, `performance.now()`. These differ on every replay and silently
+corrupt a durable run; use the checkpointed `ctx.now()` / `ctx.random()` / `ctx.uuid()` instead.
+
+Ships the rule for **both** ecosystems.
+
+## ESLint (flat config) — recommended
+
+AST-aware: only flags the banned calls inside the `run` method of a `@Workflow`-decorated class.
+
+```js
+// eslint.config.js
+import durable from '@dudousxd/nestjs-durable-eslint-plugin';
+
+export default [
+  {
+    files: ['**/*.ts'],
+    plugins: { '@dudousxd/nestjs-durable': durable },
+    rules: { '@dudousxd/nestjs-durable/no-nondeterminism': 'error' },
+  },
+];
+// or: export default [durable.configs.recommended]
+```
+
+## Biome (>= 2.0) — GritQL plugin
+
+Biome plugins can't yet scope by decorator/method, so target the plugin at your workflow files via
+`overrides`:
+
+```jsonc
+// biome.json
+{
+  "overrides": [
+    {
+      "include": ["**/*.workflow.ts"],
+      "plugins": ["./node_modules/@dudousxd/nestjs-durable-eslint-plugin/grit/no-nondeterminism.grit"]
+    }
+  ]
+}
+```
+
+> The deterministic escape hatches `ctx.now()` / `ctx.random()` / `ctx.uuid()` already exist in
+> `@dudousxd/nestjs-durable-core`; this rule pushes you to them at author time instead of finding the
+> drift at replay (`NonDeterminismError`).

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export declare const rules: {
+    'no-nondeterminism': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"useNow" | "useRandom" | "useUuid" | "useNowDate", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
+        name: string;
+    };
+};
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'no-nondeterminism': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"useNow" | "useRandom" | "useUuid" | "useNowDate", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
+            name: string;
+        };
+    };
+    configs: Record<string, unknown>;
+};
+export declare const configs: Record<string, unknown>;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,KAAK;;;;CAEjB,CAAC;AAEF,QAAA,MAAM,MAAM;;;;;;;;;;aAGK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CACvC,CAAC;AASF,eAAO,MAAM,OAAO,yBAAiB,CAAC;AACtC,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.rules = void 0;
+const no_nondeterminism_1 = require("./no-nondeterminism");
+exports.rules = {
+    'no-nondeterminism': no_nondeterminism_1.noNondeterminism,
+};
+const plugin = {
+    meta: { name: '@dudousxd/nestjs-durable-eslint-plugin', version: '0.1.0' },
+    rules: exports.rules,
+    configs: {},
+};
+// Flat-config preset: `extends` it (or spread) to turn the rule on. Defined after `plugin` so it can
+// reference the plugin object itself (the flat-config way to register a plugin + its rules).
+plugin.configs.recommended = {
+    plugins: { '@dudousxd/nestjs-durable': plugin },
+    rules: { '@dudousxd/nestjs-durable/no-nondeterminism': 'error' },
+};
+exports.configs = plugin.configs;
+exports.default = plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAuD;AAE1C,QAAA,KAAK,GAAG;IACnB,mBAAmB,EAAE,oCAAgB;CACtC,CAAC;AAEF,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,EAAE,IAAI,EAAE,wCAAwC,EAAE,OAAO,EAAE,OAAO,EAAE;IAC1E,KAAK,EAAL,aAAK;IACL,OAAO,EAAE,EAA6B;CACvC,CAAC;AAEF,qGAAqG;AACrG,6FAA6F;AAC7F,MAAM,CAAC,OAAO,CAAC,WAAW,GAAG;IAC3B,OAAO,EAAE,EAAE,0BAA0B,EAAE,MAAM,EAAE;IAC/C,KAAK,EAAE,EAAE,4CAA4C,EAAE,OAAO,EAAE;CACjE,CAAC;AAEW,QAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;AACtC,kBAAe,MAAM,CAAC"}

package/dist/no-nondeterminism.d.ts

@@ -0,0 +1,7 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+type MessageId = 'useNow' | 'useRandom' | 'useUuid' | 'useNowDate';
+export declare const noNondeterminism: ESLintUtils.RuleModule<MessageId, [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export {};
+//# sourceMappingURL=no-nondeterminism.d.ts.map

package/dist/no-nondeterminism.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-nondeterminism.d.ts","sourceRoot":"","sources":["../src/no-nondeterminism.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAMtE,KAAK,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AA4CnE,eAAO,MAAM,gBAAgB;;CA+C3B,CAAC"}

package/dist/no-nondeterminism.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noNondeterminism = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/DavideCarvalho/nestjs-durable#${name}`);
+/** True when `node` sits lexically inside the `run` method of a class decorated with `@Workflow`. */
+function isInWorkflowRun(node) {
+    let cur = node;
+    let runMethod;
+    while (cur) {
+        if (cur.type === 'MethodDefinition' &&
+            cur.key.type === 'Identifier' &&
+            cur.key.name === 'run') {
+            runMethod = cur;
+            break;
+        }
+        cur = cur.parent;
+    }
+    if (!runMethod)
+        return false;
+    const classNode = runMethod.parent?.parent; // MethodDefinition → ClassBody → Class
+    if (!classNode ||
+        (classNode.type !== 'ClassDeclaration' && classNode.type !== 'ClassExpression')) {
+        return false;
+    }
+    return (classNode.decorators ?? []).some((d) => {
+        const e = d.expression;
+        if (e.type === 'Identifier')
+            return e.name === 'Workflow';
+        if (e.type === 'CallExpression' && e.callee.type === 'Identifier') {
+            return e.callee.name === 'Workflow';
+        }
+        return false;
+    });
+}
+/** The receiver name of a member call: `crypto` for `crypto.x()` and `globalThis.crypto.x()`. */
+function receiverName(object) {
+    if (object.type === 'Identifier')
+        return object.name;
+    if (object.type === 'MemberExpression' && object.property.type === 'Identifier') {
+        return object.property.name;
+    }
+    return undefined;
+}
+exports.noNondeterminism = createRule({
+    name: 'no-nondeterminism',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow non-deterministic sources (Date.now, Math.random, new Date, crypto.randomUUID) inside a @Workflow run — they differ across replays and silently corrupt a durable run. Use ctx.now()/ctx.random()/ctx.uuid().',
+        },
+        messages: {
+            useNow: 'Non-deterministic `{{call}}` inside a @Workflow run — use `ctx.now()` (recorded once, then replayed).',
+            useRandom: 'Non-deterministic `Math.random()` inside a @Workflow run — use `ctx.random()`.',
+            useUuid: 'Non-deterministic `crypto.randomUUID()` inside a @Workflow run — use `ctx.uuid()`.',
+            useNowDate: 'Non-deterministic `new Date()` inside a @Workflow run — use `new Date(await ctx.now())`.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier')
+                    return;
+                const prop = callee.property.name;
+                const obj = receiverName(callee.object);
+                const isBanned = ((obj === 'Date' || obj === 'performance') && prop === 'now') ||
+                    (obj === 'Math' && prop === 'random') ||
+                    (obj === 'crypto' && prop === 'randomUUID');
+                if (!isBanned || !isInWorkflowRun(node))
+                    return;
+                if (prop === 'random')
+                    context.report({ node, messageId: 'useRandom' });
+                else if (prop === 'randomUUID')
+                    context.report({ node, messageId: 'useUuid' });
+                else
+                    context.report({ node, messageId: 'useNow', data: { call: `${obj}.now()` } });
+            },
+            NewExpression(node) {
+                if (node.callee.type === 'Identifier' &&
+                    node.callee.name === 'Date' &&
+                    node.arguments.length === 0 &&
+                    isInWorkflowRun(node)) {
+                    context.report({ node, messageId: 'useNowDate' });
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=no-nondeterminism.js.map

package/dist/no-nondeterminism.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-nondeterminism.js","sourceRoot":"","sources":["../src/no-nondeterminism.ts"],"names":[],"mappings":"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"}

package/grit/no-nondeterminism.grit

@@ -0,0 +1,18 @@
+// Biome (>= 2.0) GritQL plugin: flag non-deterministic sources that corrupt a durable replay.
+// Biome plugins can't yet scope by decorator/method, so target it at your workflow files via
+// biome.json `overrides` (e.g. include "**/*.workflow.ts") and use ctx.now()/ctx.random()/ctx.uuid().
+language js
+
+or {
+  `Date.now()`,
+  `performance.now()`,
+  `Math.random()`,
+  `crypto.randomUUID()`,
+  `globalThis.crypto.randomUUID()`,
+  `new Date()`
+} as $bad where {
+  register_diagnostic(
+    span = $bad,
+    message = "Non-deterministic source inside a durable workflow — it differs across replays and corrupts the run. Use ctx.now() / ctx.random() / ctx.uuid()."
+  )
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@dudousxd/nestjs-durable-eslint-plugin",
+  "version": "0.2.0",
+  "description": "ESLint rule: flag non-deterministic calls (Date.now, Math.random, …) inside a @Workflow run",
+  "license": "MIT",
+  "author": "Davide Carvalho",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavideCarvalho/nestjs-durable.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "grit"
+  ],
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.0.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/utils": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}