@junoflow/eslint-plugin 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -13
- package/index.js +894 -68
- package/package.json +9 -1
- package/rulesets.json +27 -0
package/README.md
CHANGED
|
@@ -11,32 +11,130 @@ Most integration authors do not install it directly —
|
|
|
11
11
|
[`@junoflow/cli`](https://www.npmjs.com/package/@junoflow/cli) ships an
|
|
12
12
|
`eslint.config.js` preset that enables the right rules for you.
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## Flow rules
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
| `juno/no-sleep-in-step` | flows | `sleep()` / `waitForEvent()` inside a `step.run()` callback |
|
|
20
|
-
| `juno/no-juno-sdk-import` | both | importing from `juno:sdk` — it is the runtime shim, not a types package |
|
|
21
|
-
| `juno/require-in-step` | flows | `log()` / `now()` / `fetch()` outside a step. Defined, enabled nowhere |
|
|
16
|
+
These are about the replay contract: a Juno run re-executes your handler from
|
|
17
|
+
the top after every suspension and every retry, replaying completed steps from a
|
|
18
|
+
journal instead of re-running them. Everything below follows from that.
|
|
22
19
|
|
|
23
|
-
|
|
20
|
+
| Rule | | Catches |
|
|
21
|
+
| --------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| `juno/no-dynamic-step-id` | ⛔ | `step.run(id)` / `step.llm(id)` where `id` is not a static string literal, or contains the reserved `#` |
|
|
23
|
+
| `juno/no-dynamic-scoped-name` | ⛔ | `state.scoped(name)` where `name` is not a static string literal |
|
|
24
|
+
| `juno/no-journaled-in-step` | ⛔ | anything journaled inside a `step.run` callback — `sleep`, `waitForEvent`, `invoke`/`invokeAll`, `findings.*`, `state.scoped`, a step |
|
|
25
|
+
| `juno/no-concurrent-capabilities` | ⛔ | `Promise.all([…])` over two capability calls. The socket allows one request in flight; a second **rejects at runtime** |
|
|
26
|
+
| `juno/no-nondeterminism` | ⛔ | `Date.now()`, `new Date()`, `Math.random()`, `crypto.randomUUID()` outside a step, and `process.env` anywhere |
|
|
27
|
+
| `juno/no-floating-capability` | ⛔ | a capability call used as a statement without `await` |
|
|
28
|
+
| `juno/no-credential-leak` | ⛔ | `ctx.credentials.*` passed to `log`/`console`, put in a finding, or returned directly from a step |
|
|
29
|
+
| `juno/valid-duration` | ⛔ | a duration string that `time.ParseDuration` rejects — `'1d'`, `'10 minutes'`. Checks `sleep`, `timeout` and `ttl` arguments |
|
|
30
|
+
| `juno/require-effects-in-step` | ⚠️ | a side effect outside a step, **in a handler that already takes a step or suspends**. Reads (`state.get`, `now`, `getState`) are exempt |
|
|
31
|
+
| `juno/require-suspension-label` | ⚠️ | `sleep` / `waitForEvent` with no operator-facing label |
|
|
32
|
+
| `juno/no-duplicate-step-id` | ⚠️ | the same literal step ID at two call sites in one handler |
|
|
33
|
+
| `juno/prefer-step-for-clock` | ⚠️ | `now()` / `solar()` outside a step in a handler that suspends |
|
|
34
|
+
| `juno/no-module-state` | ⚠️ | module-scope `let`/`var` written from a handler. It does not persist — the sandbox is a fresh process per dispatch |
|
|
24
35
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
36
|
+
## Integration rules
|
|
37
|
+
|
|
38
|
+
| Rule | | Catches |
|
|
39
|
+
| --------------------------------- | --- | --------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| `juno/no-process-exit` | ⛔ | `process.exit()` / `process.abort()` — the host owns the sandbox lifecycle and needs the terminal message |
|
|
41
|
+
| `juno/require-signal-in-listener` | ⚠️ | a `listener` that never reads `ctx.signal`, so SIGTERM cannot stop it |
|
|
42
|
+
|
|
43
|
+
## Both
|
|
44
|
+
|
|
45
|
+
| Rule | | Catches |
|
|
46
|
+
| ------------------------- | --- | ----------------------------------------------------------------------- |
|
|
47
|
+
| `juno/no-juno-sdk-import` | ⛔ | importing from `juno:sdk` — it is the runtime shim, not a types package |
|
|
48
|
+
|
|
49
|
+
## Why `require-effects-in-step` is conditional
|
|
50
|
+
|
|
51
|
+
A handler that neither takes a step nor suspends runs straight through. It is
|
|
52
|
+
re-run only if it throws, as a whole, so wrapping its one binding call in a step
|
|
53
|
+
buys nothing — and demanding it would make the simplest flows the most
|
|
54
|
+
annotated.
|
|
55
|
+
|
|
56
|
+
The moment a handler takes a step or calls `sleep`, `waitForEvent` or `invoke`,
|
|
57
|
+
replay stops being a possibility and becomes a certainty: the handler **will**
|
|
58
|
+
run again from the top. Anything effectful left outside a step happens again on
|
|
59
|
+
that pass. That transition is the gate, and it is why the rule fires on a
|
|
60
|
+
handler that suspends even when it takes no step at all.
|
|
61
|
+
|
|
62
|
+
It stays at warning level because it is the rule most likely to misjudge correct
|
|
63
|
+
code, and Juno runs these rules on deploy: at warning level a misjudgement costs
|
|
64
|
+
an author a message rather than a release.
|
|
65
|
+
|
|
66
|
+
## Rule sets
|
|
67
|
+
|
|
68
|
+
`rulesets.json` says which rules run against which target, and it is the single
|
|
69
|
+
source — the plugin exports it as `configs`, the `@junoflow/cli` preset spreads
|
|
70
|
+
it, and Juno's verify step reads the same file to build the config it runs
|
|
71
|
+
server-side. A rule enabled on one side and not the other would be "lints clean
|
|
72
|
+
locally, 422 on deploy", which is the failure this arrangement removes.
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
import juno from '@junoflow/eslint-plugin';
|
|
76
|
+
|
|
77
|
+
juno.configs.flow; // the flow rules, by severity
|
|
78
|
+
juno.configs.integration; // the integration rules
|
|
79
|
+
juno.configs.bundle; // what may run against esbuild output
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Two lint targets, on purpose
|
|
83
|
+
|
|
84
|
+
`configs.bundle` is one rule, and that is not an oversight. Juno lints twice:
|
|
85
|
+
|
|
86
|
+
- **your source**, parsed as TypeScript. Every rule above lives here. Nothing
|
|
87
|
+
but your own code is in it, so a rule may key on plain JavaScript —
|
|
88
|
+
`Date.now()`, a module-scope `let`, `Promise.all`.
|
|
89
|
+
- **the esbuild bundle**, which has every npm dependency you declared inlined
|
|
90
|
+
into it. `Date.now()` appears in half of npm, so a generic rule here would
|
|
91
|
+
bury your own diagnostics. Exactly one rule needs the bundle:
|
|
92
|
+
`no-juno-sdk-import`, because `juno:sdk` is an esbuild external and an import
|
|
93
|
+
survives into the output as `require('juno:sdk')`.
|
|
94
|
+
|
|
95
|
+
That is also why the rule knows both spellings, `import` and `require`.
|
|
29
96
|
|
|
30
97
|
## Manual use
|
|
31
98
|
|
|
32
99
|
```js
|
|
33
100
|
// eslint.config.js
|
|
101
|
+
import tsParser from '@typescript-eslint/parser';
|
|
34
102
|
import juno from '@junoflow/eslint-plugin';
|
|
35
103
|
|
|
36
104
|
export default [
|
|
37
105
|
{
|
|
106
|
+
files: ['**/*.ts'],
|
|
107
|
+
languageOptions: {
|
|
108
|
+
parser: tsParser,
|
|
109
|
+
ecmaVersion: 2022,
|
|
110
|
+
sourceType: 'module',
|
|
111
|
+
},
|
|
38
112
|
plugins: { juno },
|
|
39
|
-
rules: {
|
|
113
|
+
rules: { ...juno.configs.integration },
|
|
40
114
|
},
|
|
41
115
|
];
|
|
42
116
|
```
|
|
117
|
+
|
|
118
|
+
## Both spellings of the flow context
|
|
119
|
+
|
|
120
|
+
Every rule matches on the **tail** of a member chain, so these are the same:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
onTick: async ({ step }) => step.run('x', fn);
|
|
124
|
+
onTick: async (ctx) => ctx.step.run('x', fn);
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Before that, the second form passed every rule silently, which is worse than
|
|
128
|
+
having no rule at all.
|
|
129
|
+
|
|
130
|
+
## Tests
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npm test
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`test/rules.test.js` is the per-rule suite and includes a `valid` block for
|
|
137
|
+
every shape a rule must stay quiet about — a false positive here is a failed
|
|
138
|
+
deploy for a correct flow, so those are the cases to add to when a rule turns
|
|
139
|
+
out too eager. `test/typescript.test.js` re-runs the rules through
|
|
140
|
+
`@typescript-eslint/parser`, which is the parser production actually uses.
|
package/index.js
CHANGED
|
@@ -1,30 +1,304 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
//
|
|
3
|
+
// The lint rules Juno enforces on flows and integrations.
|
|
4
|
+
//
|
|
5
|
+
// Two lint targets, and the difference decides what a rule may key on:
|
|
6
|
+
//
|
|
7
|
+
// * the author's SOURCE — flow.ts, or an integration's src/**, parsed as
|
|
8
|
+
// TypeScript. Only the author's own code is here, so a rule may key on
|
|
9
|
+
// generic JavaScript (`Date.now()`, `Promise.all`, module-scope `let`).
|
|
10
|
+
// * the BUNDLE — esbuild output with every npm dependency inlined. A rule
|
|
11
|
+
// that keys on generic JavaScript would report on half of npm here, so the
|
|
12
|
+
// bundle set is deliberately one rule: `no-juno-sdk-import`, which needs
|
|
13
|
+
// the bundle, because `juno:sdk` is an esbuild external and an import only
|
|
14
|
+
// survives as `require('juno:sdk')`.
|
|
15
|
+
//
|
|
16
|
+
// `rulesets.json` says which rule runs against which target. It is the single
|
|
17
|
+
// source: the CLI preset spreads it, and Juno's verify step reads it to build
|
|
18
|
+
// the config it runs server-side.
|
|
19
|
+
|
|
20
|
+
const rulesets = require('./rulesets.json');
|
|
21
|
+
|
|
22
|
+
// ─── AST helpers ─────────────────────────────────────────────────────────────
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The dotted name of a static member chain, as an array.
|
|
26
|
+
*
|
|
27
|
+
* `ctx.step.run` -> ['ctx','step','run']; `step.run` -> ['step','run'].
|
|
28
|
+
* Returns null for anything computed or dynamic (`a[b].c`, `f().g`).
|
|
29
|
+
*
|
|
30
|
+
* Every rule below matches on the *tail* of this path, which is what makes it
|
|
31
|
+
* see both spellings of the flow context: authors destructure it
|
|
32
|
+
* (`async ({ step }) => step.run(…)`) or they don't (`async (ctx) =>
|
|
33
|
+
* ctx.step.run(…)`), and a rule that only knew the first spelling silently
|
|
34
|
+
* passed the second.
|
|
35
|
+
*/
|
|
36
|
+
function staticPath(node) {
|
|
37
|
+
const parts = [];
|
|
38
|
+
let cur = node;
|
|
39
|
+
while (cur && cur.type === 'MemberExpression') {
|
|
40
|
+
if (cur.computed || cur.property.type !== 'Identifier') return null;
|
|
41
|
+
parts.unshift(cur.property.name);
|
|
42
|
+
cur = cur.object;
|
|
43
|
+
}
|
|
44
|
+
if (!cur) return null;
|
|
45
|
+
if (cur.type === 'Identifier') {
|
|
46
|
+
parts.unshift(cur.name);
|
|
47
|
+
return parts;
|
|
48
|
+
}
|
|
49
|
+
if (cur.type === 'ThisExpression') {
|
|
50
|
+
parts.unshift('this');
|
|
51
|
+
return parts;
|
|
52
|
+
}
|
|
53
|
+
return null;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function calleePath(node) {
|
|
57
|
+
return node.type === 'CallExpression' ? staticPath(node.callee) : null;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** True when `path` ends with the given names. */
|
|
61
|
+
function tailIs(path, ...names) {
|
|
62
|
+
if (!path || path.length < names.length) return false;
|
|
63
|
+
const off = path.length - names.length;
|
|
64
|
+
return names.every((n, i) => path[off + i] === n);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function isFunction(node) {
|
|
68
|
+
return (
|
|
69
|
+
node.type === 'FunctionDeclaration' ||
|
|
70
|
+
node.type === 'FunctionExpression' ||
|
|
71
|
+
node.type === 'ArrowFunctionExpression'
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// Keys that are not child nodes. `parent` in particular would make walk() loop.
|
|
76
|
+
const NON_CHILD_KEYS = new Set([
|
|
77
|
+
'parent',
|
|
78
|
+
'loc',
|
|
79
|
+
'range',
|
|
80
|
+
'start',
|
|
81
|
+
'end',
|
|
82
|
+
'tokens',
|
|
83
|
+
'comments',
|
|
84
|
+
]);
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Depth-first walk. Returning false from `visit` prunes that subtree.
|
|
88
|
+
* Hand-rolled rather than taken from eslint's visitor keys so the plugin keeps
|
|
89
|
+
* its zero-dependency shape (it is embedded into the Juno binary as one file).
|
|
90
|
+
*/
|
|
91
|
+
function walk(node, visit) {
|
|
92
|
+
if (!node || typeof node.type !== 'string') return;
|
|
93
|
+
if (visit(node) === false) return;
|
|
94
|
+
for (const key of Object.keys(node)) {
|
|
95
|
+
if (NON_CHILD_KEYS.has(key)) continue;
|
|
96
|
+
const val = node[key];
|
|
97
|
+
if (Array.isArray(val)) {
|
|
98
|
+
for (const child of val) {
|
|
99
|
+
if (child && typeof child.type === 'string') walk(child, visit);
|
|
100
|
+
}
|
|
101
|
+
} else if (val && typeof val.type === 'string') {
|
|
102
|
+
walk(val, visit);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** True when the subtree holds a CallExpression whose callee path matches. */
|
|
108
|
+
function subtreeHasCall(root, pred) {
|
|
109
|
+
let found = false;
|
|
110
|
+
walk(root, (n) => {
|
|
111
|
+
if (found) return false;
|
|
112
|
+
if (n.type === 'CallExpression' && pred(calleePath(n), n)) {
|
|
113
|
+
found = true;
|
|
114
|
+
return false;
|
|
115
|
+
}
|
|
116
|
+
return undefined;
|
|
117
|
+
});
|
|
118
|
+
return found;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* The step.run/step.llm CallExpression whose *callback* encloses `node`, or
|
|
123
|
+
* null.
|
|
124
|
+
*
|
|
125
|
+
* Deliberately the callback and not the call: an argument evaluated eagerly at
|
|
126
|
+
* the call site (`step.run('x', fn, await state.get('y'))`) is inside the
|
|
127
|
+
* CallExpression but runs outside the step, and the two have opposite replay
|
|
128
|
+
* behaviour.
|
|
129
|
+
*/
|
|
130
|
+
function enclosingStepCallback(sourceCode, node) {
|
|
131
|
+
const ancestors = sourceCode.getAncestors(node);
|
|
132
|
+
for (let i = ancestors.length - 1; i >= 0; i--) {
|
|
133
|
+
const fn = ancestors[i];
|
|
134
|
+
if (!isFunction(fn)) continue;
|
|
135
|
+
const parent = i > 0 ? ancestors[i - 1] : null;
|
|
136
|
+
if (
|
|
137
|
+
parent &&
|
|
138
|
+
parent.type === 'CallExpression' &&
|
|
139
|
+
isStepCall(calleePath(parent)) &&
|
|
140
|
+
parent.arguments.includes(fn)
|
|
141
|
+
) {
|
|
142
|
+
return parent;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return null;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The outermost function enclosing `node` — the handler, for anything written
|
|
150
|
+
* inside one.
|
|
151
|
+
*
|
|
152
|
+
* The gated rules ask "does the handler I am in take a step or suspend?", and
|
|
153
|
+
* this is the scope that question is asked over. A helper declared at module
|
|
154
|
+
* scope answers for itself and so is never gated, which is a false negative on
|
|
155
|
+
* purpose: it is the shape where the linter cannot see the call site.
|
|
156
|
+
*/
|
|
157
|
+
function outermostFunction(sourceCode, node) {
|
|
158
|
+
for (const a of sourceCode.getAncestors(node)) {
|
|
159
|
+
if (isFunction(a)) return a;
|
|
160
|
+
}
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// ─── The capability vocabulary ───────────────────────────────────────────────
|
|
165
|
+
// One place that knows what a path means, so a rule never re-spells `state` or
|
|
166
|
+
// `findings`. Each takes a path from calleePath() and answers about the tail.
|
|
167
|
+
|
|
168
|
+
/** 'run' | 'llm' | null */
|
|
169
|
+
function isStepCall(p) {
|
|
170
|
+
if (tailIs(p, 'step', 'run')) return 'run';
|
|
171
|
+
if (tailIs(p, 'step', 'llm')) return 'llm';
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
const STATE_METHODS = [
|
|
176
|
+
'get',
|
|
177
|
+
'set',
|
|
178
|
+
'claim',
|
|
179
|
+
'release',
|
|
180
|
+
'signal',
|
|
181
|
+
'retract',
|
|
182
|
+
'scoped',
|
|
183
|
+
];
|
|
184
|
+
/** The state method name, or null. */
|
|
185
|
+
function isStateCall(p) {
|
|
186
|
+
if (!p || p.length < 2) return null;
|
|
187
|
+
const [obj, method] = [p[p.length - 2], p[p.length - 1]];
|
|
188
|
+
return obj === 'state' && STATE_METHODS.includes(method) ? method : null;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const FINDING_METHODS = ['open', 'clear', 'set'];
|
|
192
|
+
function isFindingsCall(p) {
|
|
193
|
+
if (!p || p.length < 2) return null;
|
|
194
|
+
const [obj, method] = [p[p.length - 2], p[p.length - 1]];
|
|
195
|
+
return obj === 'findings' && FINDING_METHODS.includes(method) ? method : null;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** `bindings.<as>.<action>()`, with or without a `ctx.` prefix. */
|
|
199
|
+
function isBindingCall(p) {
|
|
200
|
+
return !!p && p.length >= 3 && p[p.length - 3] === 'bindings';
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** A flow binding's invoke()/invokeAll(): a binding call that suspends. */
|
|
204
|
+
function isFlowInvoke(p) {
|
|
205
|
+
if (!isBindingCall(p)) return null;
|
|
206
|
+
const last = p[p.length - 1];
|
|
207
|
+
return last === 'invoke' || last === 'invokeAll' ? last : null;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
const isSleep = (p) => tailIs(p, 'sleep');
|
|
211
|
+
const isWaitForEvent = (p) => tailIs(p, 'waitForEvent');
|
|
212
|
+
const isSolar = (p) => tailIs(p, 'solar');
|
|
213
|
+
const isNow = (p) => tailIs(p, 'now') && !tailIs(p, 'Date', 'now');
|
|
214
|
+
const isFetch = (p) => tailIs(p, 'fetch');
|
|
215
|
+
const isLog = (p) =>
|
|
216
|
+
tailIs(p, 'log') || tailIs(p, 'log', 'warn') || tailIs(p, 'log', 'error');
|
|
217
|
+
|
|
218
|
+
/** Suspends the run: the sandbox exits and the handler re-enters on wake. */
|
|
219
|
+
function isSuspending(p) {
|
|
220
|
+
return isSleep(p) || isWaitForEvent(p) || !!isFlowInvoke(p);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** Recorded in the journal, so it must not be replayed from inside a step. */
|
|
224
|
+
function journaledKind(p) {
|
|
225
|
+
const step = isStepCall(p);
|
|
226
|
+
if (step) return `step.${step}()`;
|
|
227
|
+
if (isSleep(p)) return 'sleep()';
|
|
228
|
+
if (isWaitForEvent(p)) return 'waitForEvent()';
|
|
229
|
+
const invoke = isFlowInvoke(p);
|
|
230
|
+
if (invoke) return `${invoke}()`;
|
|
231
|
+
const finding = isFindingsCall(p);
|
|
232
|
+
if (finding) return `findings.${finding}()`;
|
|
233
|
+
if (isStateCall(p) === 'scoped') return 'state.scoped()';
|
|
234
|
+
return null;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** Anything that crosses the capability socket. */
|
|
238
|
+
function isCapabilityCall(p) {
|
|
239
|
+
return (
|
|
240
|
+
!!isStepCall(p) ||
|
|
241
|
+
!!isStateCall(p) ||
|
|
242
|
+
!!isFindingsCall(p) ||
|
|
243
|
+
isBindingCall(p) ||
|
|
244
|
+
isSleep(p) ||
|
|
245
|
+
isWaitForEvent(p) ||
|
|
246
|
+
isSolar(p)
|
|
247
|
+
);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* A side effect that really happens again on every replay and every retry —
|
|
252
|
+
* the right-hand column of the durability table, minus the reads.
|
|
253
|
+
*
|
|
254
|
+
* `state.get`, `now()`, `solar()` and a binding's `getState()` are reads and
|
|
255
|
+
* are deliberately absent: wrapping a read in a step *pins* it across a
|
|
256
|
+
* suspension, which is usually the opposite of what the author wants. When one
|
|
257
|
+
* of them must be stable, `prefer-step-for-clock` says so at warning level
|
|
258
|
+
* rather than this rule saying it at error level.
|
|
259
|
+
*/
|
|
260
|
+
function isRepeatedEffect(p) {
|
|
261
|
+
if (isBindingCall(p)) {
|
|
262
|
+
const last = p[p.length - 1];
|
|
263
|
+
return last !== 'getState' && !isFlowInvoke(p);
|
|
264
|
+
}
|
|
265
|
+
const state = isStateCall(p);
|
|
266
|
+
if (state) return state !== 'get' && state !== 'scoped';
|
|
267
|
+
return isFetch(p) || isLog(p);
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
// A memo keyed on the function node, so "does this handler take a step?" is
|
|
271
|
+
// answered once per handler rather than once per reported call.
|
|
272
|
+
function memoize(fn) {
|
|
273
|
+
const cache = new WeakMap();
|
|
274
|
+
return (node) => {
|
|
275
|
+
if (cache.has(node)) return cache.get(node);
|
|
276
|
+
const val = fn(node);
|
|
277
|
+
cache.set(node, val);
|
|
278
|
+
return val;
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// ─── no-dynamic-step-id ──────────────────────────────────────────────────────
|
|
283
|
+
|
|
4
284
|
const noDynamicStepId = {
|
|
5
285
|
meta: {
|
|
6
286
|
type: 'problem',
|
|
7
|
-
docs: {
|
|
287
|
+
docs: {
|
|
288
|
+
description: 'step.run()/step.llm() ID must be a static string literal',
|
|
289
|
+
},
|
|
8
290
|
schema: [],
|
|
9
291
|
},
|
|
10
292
|
create(context) {
|
|
11
293
|
return {
|
|
12
294
|
CallExpression(node) {
|
|
13
|
-
const
|
|
14
|
-
if (
|
|
15
|
-
callee.type !== 'MemberExpression' ||
|
|
16
|
-
callee.object.type !== 'Identifier' ||
|
|
17
|
-
callee.object.name !== 'step' ||
|
|
18
|
-
callee.property.type !== 'Identifier' ||
|
|
19
|
-
callee.property.name !== 'run'
|
|
20
|
-
) {
|
|
21
|
-
return;
|
|
22
|
-
}
|
|
295
|
+
const kind = isStepCall(calleePath(node));
|
|
296
|
+
if (!kind) return;
|
|
23
297
|
const id = node.arguments[0];
|
|
24
298
|
if (!id || id.type !== 'Literal' || typeof id.value !== 'string') {
|
|
25
299
|
context.report({
|
|
26
300
|
node: id || node,
|
|
27
|
-
message:
|
|
301
|
+
message: `step.${kind}() ID must be a static string literal — it is the journal key, and a computed ID cannot be matched on the next entry`,
|
|
28
302
|
});
|
|
29
303
|
return;
|
|
30
304
|
}
|
|
@@ -34,7 +308,7 @@ const noDynamicStepId = {
|
|
|
34
308
|
if (id.value.includes('#')) {
|
|
35
309
|
context.report({
|
|
36
310
|
node: id,
|
|
37
|
-
message:
|
|
311
|
+
message: `step.${kind}() ID must not contain "#" (reserved separator)`,
|
|
38
312
|
});
|
|
39
313
|
}
|
|
40
314
|
},
|
|
@@ -42,101 +316,564 @@ const noDynamicStepId = {
|
|
|
42
316
|
},
|
|
43
317
|
};
|
|
44
318
|
|
|
45
|
-
// no-
|
|
46
|
-
|
|
319
|
+
// ─── no-dynamic-scoped-name ──────────────────────────────────────────────────
|
|
320
|
+
|
|
321
|
+
const noDynamicScopedName = {
|
|
322
|
+
meta: {
|
|
323
|
+
type: 'problem',
|
|
324
|
+
docs: {
|
|
325
|
+
description: 'state.scoped() name must be a static string literal',
|
|
326
|
+
},
|
|
327
|
+
schema: [],
|
|
328
|
+
},
|
|
329
|
+
create(context) {
|
|
330
|
+
return {
|
|
331
|
+
CallExpression(node) {
|
|
332
|
+
if (isStateCall(calleePath(node)) !== 'scoped') return;
|
|
333
|
+
const name = node.arguments[0];
|
|
334
|
+
if (
|
|
335
|
+
!name ||
|
|
336
|
+
name.type !== 'Literal' ||
|
|
337
|
+
typeof name.value !== 'string'
|
|
338
|
+
) {
|
|
339
|
+
context.report({
|
|
340
|
+
node: name || node,
|
|
341
|
+
message:
|
|
342
|
+
'state.scoped() name must be a static string literal — the setter is journaled under it, and a computed name cannot be matched on replay',
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
},
|
|
346
|
+
};
|
|
347
|
+
},
|
|
348
|
+
};
|
|
349
|
+
|
|
350
|
+
// ─── no-journaled-in-step ────────────────────────────────────────────────────
|
|
351
|
+
|
|
352
|
+
const noJournaledInStep = {
|
|
47
353
|
meta: {
|
|
48
354
|
type: 'problem',
|
|
49
355
|
docs: {
|
|
50
356
|
description:
|
|
51
|
-
'
|
|
357
|
+
'journaled calls must not appear inside a step.run() callback',
|
|
52
358
|
},
|
|
53
359
|
schema: [],
|
|
54
360
|
},
|
|
55
361
|
create(context) {
|
|
56
|
-
|
|
57
|
-
|
|
362
|
+
const sourceCode = context.sourceCode;
|
|
363
|
+
return {
|
|
364
|
+
CallExpression(node) {
|
|
365
|
+
const kind = journaledKind(calleePath(node));
|
|
366
|
+
if (!kind) return;
|
|
367
|
+
if (!enclosingStepCallback(sourceCode, node)) return;
|
|
368
|
+
|
|
369
|
+
// Two distinct failures, and the author needs to be told which.
|
|
370
|
+
const suspends = isSuspending(calleePath(node));
|
|
371
|
+
const why = suspends
|
|
372
|
+
? 'it suspends the run, so the step never completes and its callback re-runs in full on wake — every side effect before this line fires twice'
|
|
373
|
+
: 'its journal ID comes from a counter that only advances when the call executes, so a replay that skips this step misaligns every later call on the same key';
|
|
374
|
+
context.report({
|
|
375
|
+
node,
|
|
376
|
+
message: `${kind} must not be called inside step.run() — ${why}`,
|
|
377
|
+
});
|
|
378
|
+
},
|
|
379
|
+
};
|
|
380
|
+
},
|
|
381
|
+
};
|
|
382
|
+
|
|
383
|
+
// ─── require-effects-in-step ─────────────────────────────────────────────────
|
|
58
384
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
385
|
+
const requireEffectsInStep = {
|
|
386
|
+
meta: {
|
|
387
|
+
type: 'problem',
|
|
388
|
+
docs: {
|
|
389
|
+
description:
|
|
390
|
+
'side effects must be wrapped in step.run() once a handler takes a step or suspends',
|
|
391
|
+
},
|
|
392
|
+
schema: [],
|
|
393
|
+
},
|
|
394
|
+
create(context) {
|
|
395
|
+
const sourceCode = context.sourceCode;
|
|
396
|
+
// The gate: a handler that neither steps nor suspends is a straight-line
|
|
397
|
+
// flow, re-run only on a retry, and forcing a step on it buys nothing. Once
|
|
398
|
+
// it does either, replay is a certainty rather than a possibility.
|
|
399
|
+
const isGated = memoize((fn) =>
|
|
400
|
+
subtreeHasCall(fn.body, (p) => !!isStepCall(p) || isSuspending(p))
|
|
401
|
+
);
|
|
402
|
+
|
|
403
|
+
return {
|
|
404
|
+
CallExpression(node) {
|
|
405
|
+
const p = calleePath(node);
|
|
406
|
+
if (!isRepeatedEffect(p)) return;
|
|
407
|
+
if (enclosingStepCallback(sourceCode, node)) return;
|
|
408
|
+
const handler = outermostFunction(sourceCode, node);
|
|
409
|
+
if (!handler || !isGated(handler)) return;
|
|
410
|
+
context.report({
|
|
411
|
+
node,
|
|
412
|
+
message: `${p[p.length - 1]}() is not journaled and this handler replays — wrap it in step.run() or it happens again on every wake and retry`,
|
|
413
|
+
});
|
|
414
|
+
},
|
|
415
|
+
};
|
|
416
|
+
},
|
|
417
|
+
};
|
|
418
|
+
|
|
419
|
+
// ─── valid-duration ──────────────────────────────────────────────────────────
|
|
420
|
+
|
|
421
|
+
// Go's time.ParseDuration: a sequence of decimal numbers each with a unit, and
|
|
422
|
+
// no spaces. Notably there is NO day unit, which is the mistake this catches
|
|
423
|
+
// most often.
|
|
424
|
+
const GO_DURATION =
|
|
425
|
+
/^[+-]?(\d+(\.\d*)?|\.\d+)(ns|us|µs|μs|ms|s|m|h)((\d+(\.\d*)?|\.\d+)(ns|us|µs|μs|ms|s|m|h))*$/;
|
|
426
|
+
|
|
427
|
+
function literalString(node) {
|
|
428
|
+
if (!node) return null;
|
|
429
|
+
if (node.type === 'Literal' && typeof node.value === 'string') {
|
|
430
|
+
return node.value;
|
|
431
|
+
}
|
|
432
|
+
if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
|
|
433
|
+
return node.quasis.map((q) => q.value.cooked).join('');
|
|
434
|
+
}
|
|
435
|
+
return null;
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
/** The value node of `key` on an object literal argument, or null. */
|
|
439
|
+
function objectProp(node, key) {
|
|
440
|
+
if (!node || node.type !== 'ObjectExpression') return null;
|
|
441
|
+
for (const prop of node.properties) {
|
|
442
|
+
if (prop.type !== 'Property' || prop.computed) continue;
|
|
443
|
+
const name =
|
|
444
|
+
prop.key.type === 'Identifier' ? prop.key.name : literalString(prop.key);
|
|
445
|
+
if (name === key) return prop.value;
|
|
446
|
+
}
|
|
447
|
+
return null;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
const validDuration = {
|
|
451
|
+
meta: {
|
|
452
|
+
type: 'problem',
|
|
453
|
+
docs: { description: 'duration strings must parse as Go durations' },
|
|
454
|
+
schema: [],
|
|
455
|
+
},
|
|
456
|
+
create(context) {
|
|
457
|
+
function check(node) {
|
|
458
|
+
const value = literalString(node);
|
|
459
|
+
if (value === null || value === '0') return;
|
|
460
|
+
if (GO_DURATION.test(value)) return;
|
|
461
|
+
context.report({
|
|
462
|
+
node,
|
|
463
|
+
message: `${JSON.stringify(value)} is not a Go duration — write "30s", "5m", "1h30m". There is no day unit ("1d" is invalid; use "24h") and no spaces or long unit names`,
|
|
464
|
+
});
|
|
68
465
|
}
|
|
69
466
|
|
|
70
467
|
return {
|
|
71
468
|
CallExpression(node) {
|
|
72
|
-
|
|
73
|
-
|
|
469
|
+
const p = calleePath(node);
|
|
470
|
+
if (isSleep(p)) {
|
|
471
|
+
check(node.arguments[0]);
|
|
74
472
|
return;
|
|
75
473
|
}
|
|
76
|
-
if (
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
context.report({
|
|
80
|
-
node,
|
|
81
|
-
message: `${name}() must not be called inside step.run()`,
|
|
82
|
-
});
|
|
83
|
-
}
|
|
474
|
+
if (isWaitForEvent(p)) {
|
|
475
|
+
check(objectProp(node.arguments[1], 'timeout'));
|
|
476
|
+
return;
|
|
84
477
|
}
|
|
478
|
+
const state = isStateCall(p);
|
|
479
|
+
if (state === 'claim') check(objectProp(node.arguments[2], 'ttl'));
|
|
480
|
+
if (state === 'signal') check(objectProp(node.arguments[2], 'ttl'));
|
|
481
|
+
if (isFlowInvoke(p)) check(objectProp(node.arguments[1], 'timeout'));
|
|
85
482
|
},
|
|
86
|
-
|
|
87
|
-
|
|
483
|
+
};
|
|
484
|
+
},
|
|
485
|
+
};
|
|
486
|
+
|
|
487
|
+
// ─── no-concurrent-capabilities ──────────────────────────────────────────────
|
|
488
|
+
|
|
489
|
+
const PROMISE_COMBINATORS = new Set(['all', 'allSettled', 'race', 'any']);
|
|
490
|
+
|
|
491
|
+
const noConcurrentCapabilities = {
|
|
492
|
+
meta: {
|
|
493
|
+
type: 'problem',
|
|
494
|
+
docs: {
|
|
495
|
+
description: 'capability calls must not be issued concurrently',
|
|
496
|
+
},
|
|
497
|
+
schema: [],
|
|
498
|
+
},
|
|
499
|
+
create(context) {
|
|
500
|
+
/** True when this element resolves to a capability call. */
|
|
501
|
+
function isCapabilityElement(el) {
|
|
502
|
+
if (!el) return false;
|
|
503
|
+
const inner = el.type === 'AwaitExpression' ? el.argument : el;
|
|
504
|
+
if (inner.type === 'CallExpression') {
|
|
505
|
+
if (isCapabilityCall(calleePath(inner))) return true;
|
|
506
|
+
// Promise.all(items.map(x => bindings.x.y(…))) — the fan-out spelling.
|
|
507
|
+
if (
|
|
508
|
+
tailIs(calleePath(inner), 'map') &&
|
|
509
|
+
inner.arguments.some(
|
|
510
|
+
(a) =>
|
|
511
|
+
isFunction(a) &&
|
|
512
|
+
subtreeHasCall(a.body, (p) => isCapabilityCall(p))
|
|
513
|
+
)
|
|
514
|
+
) {
|
|
515
|
+
return true;
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
return false;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
return {
|
|
522
|
+
CallExpression(node) {
|
|
523
|
+
const p = calleePath(node);
|
|
524
|
+
if (!p || p.length < 2) return;
|
|
525
|
+
if (p[p.length - 2] !== 'Promise') return;
|
|
526
|
+
if (!PROMISE_COMBINATORS.has(p[p.length - 1])) return;
|
|
527
|
+
|
|
528
|
+
const arg = node.arguments[0];
|
|
529
|
+
let concurrent = 0;
|
|
530
|
+
if (arg && arg.type === 'ArrayExpression') {
|
|
531
|
+
concurrent = arg.elements.filter(isCapabilityElement).length;
|
|
532
|
+
} else if (isCapabilityElement(arg)) {
|
|
533
|
+
// Promise.all(items.map(…)) — one element syntactically, N at runtime.
|
|
534
|
+
concurrent = 2;
|
|
535
|
+
}
|
|
536
|
+
if (concurrent < 2) return;
|
|
537
|
+
|
|
538
|
+
context.report({
|
|
539
|
+
node,
|
|
540
|
+
message:
|
|
541
|
+
"the capability socket allows at most one request in flight — a second concurrent call rejects at runtime. Await them one at a time, or use a flow binding's invokeAll() to fan out",
|
|
542
|
+
});
|
|
88
543
|
},
|
|
89
544
|
};
|
|
90
545
|
},
|
|
91
546
|
};
|
|
92
547
|
|
|
93
|
-
//
|
|
94
|
-
|
|
548
|
+
// ─── no-nondeterminism ───────────────────────────────────────────────────────
|
|
549
|
+
|
|
550
|
+
const noNondeterminism = {
|
|
95
551
|
meta: {
|
|
96
552
|
type: 'problem',
|
|
97
553
|
docs: {
|
|
98
|
-
description:
|
|
554
|
+
description:
|
|
555
|
+
'wall-clock and randomness outside a step break replay determinism',
|
|
99
556
|
},
|
|
100
557
|
schema: [],
|
|
101
558
|
},
|
|
102
559
|
create(context) {
|
|
103
|
-
|
|
560
|
+
const sourceCode = context.sourceCode;
|
|
104
561
|
|
|
105
|
-
function
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
callee.property.type === 'Identifier' &&
|
|
112
|
-
callee.property.name === 'run'
|
|
113
|
-
);
|
|
562
|
+
function report(node, what, advice) {
|
|
563
|
+
if (enclosingStepCallback(sourceCode, node)) return;
|
|
564
|
+
context.report({
|
|
565
|
+
node,
|
|
566
|
+
message: `${what} outside step.run() re-evaluates on every replay — ${advice}`,
|
|
567
|
+
});
|
|
114
568
|
}
|
|
115
569
|
|
|
116
570
|
return {
|
|
117
571
|
CallExpression(node) {
|
|
118
|
-
|
|
119
|
-
|
|
572
|
+
const p = calleePath(node);
|
|
573
|
+
if (tailIs(p, 'Date', 'now')) {
|
|
574
|
+
report(
|
|
575
|
+
node,
|
|
576
|
+
'Date.now()',
|
|
577
|
+
'use ctx.now(), which reports the site timezone, and wrap it in step.run() when the value must survive a sleep'
|
|
578
|
+
);
|
|
579
|
+
} else if (tailIs(p, 'Math', 'random')) {
|
|
580
|
+
report(
|
|
581
|
+
node,
|
|
582
|
+
'Math.random()',
|
|
583
|
+
'control flow must be identical on every re-entry or the journal misaligns. Draw it inside step.run() so the value is recorded'
|
|
584
|
+
);
|
|
585
|
+
} else if (
|
|
586
|
+
tailIs(p, 'crypto', 'randomUUID') ||
|
|
587
|
+
tailIs(p, 'crypto', 'getRandomValues')
|
|
588
|
+
) {
|
|
589
|
+
report(
|
|
590
|
+
node,
|
|
591
|
+
`${p.slice(-2).join('.')}()`,
|
|
592
|
+
'draw it inside step.run() so the value is recorded and replayed'
|
|
593
|
+
);
|
|
594
|
+
}
|
|
595
|
+
},
|
|
596
|
+
NewExpression(node) {
|
|
597
|
+
// `new Date(iso)` is a pure conversion; only the zero-arg clock read is
|
|
598
|
+
// nondeterministic.
|
|
599
|
+
if (node.arguments.length > 0) return;
|
|
600
|
+
if (node.callee.type !== 'Identifier' || node.callee.name !== 'Date') {
|
|
120
601
|
return;
|
|
121
602
|
}
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
603
|
+
report(
|
|
604
|
+
node,
|
|
605
|
+
'new Date()',
|
|
606
|
+
'use ctx.now(), which reports the site timezone, and wrap it in step.run() when the value must survive a sleep'
|
|
607
|
+
);
|
|
608
|
+
},
|
|
609
|
+
MemberExpression(node) {
|
|
610
|
+
if (node.computed) return;
|
|
611
|
+
if (!tailIs(staticPath(node), 'process', 'env')) return;
|
|
612
|
+
context.report({
|
|
613
|
+
node,
|
|
614
|
+
message:
|
|
615
|
+
"the sandbox has no environment variables — declare the secret in the manifest's credentials and read it from ctx.credentials",
|
|
616
|
+
});
|
|
617
|
+
},
|
|
618
|
+
};
|
|
619
|
+
},
|
|
620
|
+
};
|
|
621
|
+
|
|
622
|
+
// ─── no-floating-capability ──────────────────────────────────────────────────
|
|
623
|
+
|
|
624
|
+
const noFloatingCapability = {
|
|
625
|
+
meta: {
|
|
626
|
+
type: 'problem',
|
|
627
|
+
docs: { description: 'capability calls must be awaited' },
|
|
628
|
+
schema: [],
|
|
629
|
+
},
|
|
630
|
+
create(context) {
|
|
631
|
+
return {
|
|
632
|
+
ExpressionStatement(node) {
|
|
633
|
+
const expr = node.expression;
|
|
634
|
+
if (expr.type !== 'CallExpression') return;
|
|
635
|
+
const p = calleePath(expr);
|
|
636
|
+
if (!isCapabilityCall(p)) return;
|
|
637
|
+
context.report({
|
|
638
|
+
node: expr,
|
|
639
|
+
message: `${p[p.length - 1]}() returns a promise and is not awaited — the sandbox exits on the run's terminal message, so an un-awaited capability call may never reach the host, and a rejection becomes an unhandled one`,
|
|
640
|
+
});
|
|
641
|
+
},
|
|
642
|
+
};
|
|
643
|
+
},
|
|
644
|
+
};
|
|
645
|
+
|
|
646
|
+
// ─── no-credential-leak ──────────────────────────────────────────────────────
|
|
647
|
+
|
|
648
|
+
const noCredentialLeak = {
|
|
649
|
+
meta: {
|
|
650
|
+
type: 'problem',
|
|
651
|
+
docs: { description: 'credentials must not be logged or journaled' },
|
|
652
|
+
schema: [],
|
|
653
|
+
},
|
|
654
|
+
create(context) {
|
|
655
|
+
const sourceCode = context.sourceCode;
|
|
656
|
+
|
|
657
|
+
/** The `ctx.credentials.x` reads inside a subtree. */
|
|
658
|
+
function credentialsIn(root) {
|
|
659
|
+
const hits = [];
|
|
660
|
+
walk(root, (n) => {
|
|
661
|
+
if (n.type !== 'MemberExpression' || n.computed) return undefined;
|
|
662
|
+
if (tailIs(staticPath(n), 'credentials', n.property.name)) hits.push(n);
|
|
663
|
+
return undefined;
|
|
664
|
+
});
|
|
665
|
+
return hits;
|
|
666
|
+
}
|
|
667
|
+
|
|
668
|
+
function reportAll(nodes, where) {
|
|
669
|
+
for (const n of nodes) {
|
|
670
|
+
context.report({
|
|
671
|
+
node: n,
|
|
672
|
+
message: `a credential must never be ${where}`,
|
|
673
|
+
});
|
|
674
|
+
}
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
return {
|
|
678
|
+
CallExpression(node) {
|
|
679
|
+
const p = calleePath(node);
|
|
680
|
+
if (
|
|
681
|
+
isLog(p) ||
|
|
682
|
+
tailIs(p, 'console', 'log') ||
|
|
683
|
+
tailIs(p, 'console', 'error') ||
|
|
684
|
+
tailIs(p, 'console', 'warn')
|
|
685
|
+
) {
|
|
686
|
+
for (const arg of node.arguments) {
|
|
687
|
+
reportAll(
|
|
688
|
+
credentialsIn(arg),
|
|
689
|
+
'logged — run logs are persisted and shown to every operator'
|
|
690
|
+
);
|
|
691
|
+
}
|
|
692
|
+
return;
|
|
693
|
+
}
|
|
694
|
+
if (isFindingsCall(p)) {
|
|
695
|
+
for (const arg of node.arguments) {
|
|
696
|
+
reportAll(
|
|
697
|
+
credentialsIn(arg),
|
|
698
|
+
"put in a finding — a finding's text and data are stored and shown on the board"
|
|
699
|
+
);
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
},
|
|
703
|
+
ReturnStatement(node) {
|
|
704
|
+
if (!node.argument) return;
|
|
705
|
+
// Only the shapes where the credential is unambiguously part of the
|
|
706
|
+
// returned value: `return credentials.t` and `return { token:
|
|
707
|
+
// credentials.t }`. A credential passed *into* a call that is then
|
|
708
|
+
// returned (`return api.send({ token: credentials.t })`) is the normal
|
|
709
|
+
// way to use one, and flagging it would make the rule unusable.
|
|
710
|
+
const arg = node.argument;
|
|
711
|
+
const direct =
|
|
712
|
+
arg.type === 'MemberExpression' ||
|
|
713
|
+
arg.type === 'ObjectExpression' ||
|
|
714
|
+
arg.type === 'ArrayExpression';
|
|
715
|
+
if (!direct) return;
|
|
716
|
+
if (!enclosingStepCallback(sourceCode, node)) return;
|
|
717
|
+
reportAll(
|
|
718
|
+
credentialsIn(arg),
|
|
719
|
+
'returned from a step — step outputs are written to the journal and shown in the run view'
|
|
720
|
+
);
|
|
721
|
+
},
|
|
722
|
+
};
|
|
723
|
+
},
|
|
724
|
+
};
|
|
725
|
+
|
|
726
|
+
// ─── require-suspension-label ────────────────────────────────────────────────
|
|
727
|
+
|
|
728
|
+
const requireSuspensionLabel = {
|
|
729
|
+
meta: {
|
|
730
|
+
type: 'suggestion',
|
|
731
|
+
docs: { description: 'sleep() and waitForEvent() should carry a label' },
|
|
732
|
+
schema: [],
|
|
733
|
+
},
|
|
734
|
+
create(context) {
|
|
735
|
+
return {
|
|
736
|
+
CallExpression(node) {
|
|
737
|
+
const p = calleePath(node);
|
|
738
|
+
if (isSleep(p) && node.arguments.length < 2) {
|
|
739
|
+
context.report({
|
|
740
|
+
node,
|
|
741
|
+
message:
|
|
742
|
+
'sleep() without a label shows the operator a generic "Sleeping" — a flow that sleeps in three places is indistinguishable from itself in the run view',
|
|
743
|
+
});
|
|
744
|
+
} else if (isWaitForEvent(p) && node.arguments.length < 3) {
|
|
745
|
+
context.report({
|
|
746
|
+
node,
|
|
747
|
+
message:
|
|
748
|
+
'waitForEvent() without a label shows the operator a description derived from the pattern — pass a third argument saying what the run is waiting for',
|
|
749
|
+
});
|
|
750
|
+
}
|
|
751
|
+
},
|
|
752
|
+
};
|
|
753
|
+
},
|
|
754
|
+
};
|
|
755
|
+
|
|
756
|
+
// ─── no-duplicate-step-id ────────────────────────────────────────────────────
|
|
757
|
+
|
|
758
|
+
const noDuplicateStepId = {
|
|
759
|
+
meta: {
|
|
760
|
+
type: 'suggestion',
|
|
761
|
+
docs: { description: 'a step ID should appear at one call site' },
|
|
762
|
+
schema: [],
|
|
763
|
+
},
|
|
764
|
+
create(context) {
|
|
765
|
+
const sourceCode = context.sourceCode;
|
|
766
|
+
// fn -> id -> first call site
|
|
767
|
+
const seen = new WeakMap();
|
|
768
|
+
|
|
769
|
+
return {
|
|
770
|
+
CallExpression(node) {
|
|
771
|
+
if (!isStepCall(calleePath(node))) return;
|
|
772
|
+
const id = node.arguments[0];
|
|
773
|
+
if (!id || id.type !== 'Literal' || typeof id.value !== 'string')
|
|
774
|
+
return;
|
|
775
|
+
const scope = outermostFunction(sourceCode, node) || sourceCode.ast;
|
|
776
|
+
let ids = seen.get(scope);
|
|
777
|
+
if (!ids) {
|
|
778
|
+
ids = new Map();
|
|
779
|
+
seen.set(scope, ids);
|
|
780
|
+
}
|
|
781
|
+
if (!ids.has(id.value)) {
|
|
782
|
+
ids.set(id.value, node);
|
|
783
|
+
return;
|
|
784
|
+
}
|
|
785
|
+
context.report({
|
|
786
|
+
node: id,
|
|
787
|
+
message: `step ID ${JSON.stringify(id.value)} is already used at another call site in this handler. The repeat is journaled as ${JSON.stringify(id.value + '#1')}, which only lines up if both sites run in the same order on every replay — a branch that takes the other arm shifts them. Give this one its own ID. (A single call site inside a loop is the supported form and is not reported.)`,
|
|
788
|
+
});
|
|
789
|
+
},
|
|
790
|
+
};
|
|
791
|
+
},
|
|
792
|
+
};
|
|
793
|
+
|
|
794
|
+
// ─── prefer-step-for-clock ───────────────────────────────────────────────────
|
|
795
|
+
|
|
796
|
+
const preferStepForClock = {
|
|
797
|
+
meta: {
|
|
798
|
+
type: 'suggestion',
|
|
799
|
+
docs: {
|
|
800
|
+
description:
|
|
801
|
+
'clock and solar reads should be journaled in a handler that suspends',
|
|
802
|
+
},
|
|
803
|
+
schema: [],
|
|
804
|
+
},
|
|
805
|
+
create(context) {
|
|
806
|
+
const sourceCode = context.sourceCode;
|
|
807
|
+
const suspends = memoize((fn) => subtreeHasCall(fn.body, isSuspending));
|
|
808
|
+
|
|
809
|
+
return {
|
|
810
|
+
CallExpression(node) {
|
|
811
|
+
const p = calleePath(node);
|
|
812
|
+
if (!isNow(p) && !isSolar(p)) return;
|
|
813
|
+
if (enclosingStepCallback(sourceCode, node)) return;
|
|
814
|
+
const handler = outermostFunction(sourceCode, node);
|
|
815
|
+
if (!handler || !suspends(handler)) return;
|
|
816
|
+
context.report({
|
|
817
|
+
node,
|
|
818
|
+
message: `${p[p.length - 1]}() is not journaled and this handler suspends — after the wake it reports the new time, not the one the first execution saw. Wrap it in step.run() if the value must be stable`,
|
|
819
|
+
});
|
|
820
|
+
},
|
|
821
|
+
};
|
|
822
|
+
},
|
|
823
|
+
};
|
|
824
|
+
|
|
825
|
+
// ─── no-module-state ─────────────────────────────────────────────────────────
|
|
826
|
+
|
|
827
|
+
const noModuleState = {
|
|
828
|
+
meta: {
|
|
829
|
+
type: 'suggestion',
|
|
830
|
+
docs: { description: 'module-scope mutable state does not persist' },
|
|
831
|
+
schema: [],
|
|
832
|
+
},
|
|
833
|
+
create(context) {
|
|
834
|
+
const sourceCode = context.sourceCode;
|
|
835
|
+
|
|
836
|
+
function isNestedInFunction(scope, top) {
|
|
837
|
+
for (let s = scope; s; s = s.upper) {
|
|
838
|
+
if (s === top) return false;
|
|
839
|
+
if (s.type === 'function') return true;
|
|
840
|
+
}
|
|
841
|
+
return false;
|
|
842
|
+
}
|
|
843
|
+
|
|
844
|
+
return {
|
|
845
|
+
'Program:exit'(node) {
|
|
846
|
+
const top = sourceCode.getScope(node);
|
|
847
|
+
const scopes = [top];
|
|
848
|
+
// With sourceType: module the real bindings live one scope down.
|
|
849
|
+
for (const child of top.childScopes) {
|
|
850
|
+
if (child.type === 'module') scopes.push(child);
|
|
851
|
+
}
|
|
852
|
+
for (const scope of scopes) {
|
|
853
|
+
for (const variable of scope.variables) {
|
|
854
|
+
// esbuild's own helpers (__defProp, __toCommonJS, …) are module
|
|
855
|
+
// scope by construction and never written from a function.
|
|
856
|
+
if (variable.name.startsWith('__')) continue;
|
|
857
|
+
const def = variable.defs[0];
|
|
858
|
+
if (!def || def.type !== 'Variable') continue;
|
|
859
|
+
if (def.parent.kind === 'const') continue;
|
|
860
|
+
|
|
861
|
+
const written = variable.references.filter(
|
|
862
|
+
(ref) => ref.isWrite() && isNestedInFunction(ref.from, scope)
|
|
863
|
+
);
|
|
864
|
+
if (written.length === 0) continue;
|
|
125
865
|
context.report({
|
|
126
|
-
node,
|
|
127
|
-
message: `${name}
|
|
866
|
+
node: written[0].identifier,
|
|
867
|
+
message: `${variable.name} is module-scope state written from a handler. It does not persist: the sandbox is a fresh process for every dispatch, and it is re-loaded from the top on every replay. Use ctx.state for something that must outlive the run, or ctx.state.scoped for something private to it`,
|
|
128
868
|
});
|
|
129
869
|
}
|
|
130
870
|
}
|
|
131
871
|
},
|
|
132
|
-
'CallExpression:exit'(node) {
|
|
133
|
-
if (isStepRun(node)) depth--;
|
|
134
|
-
},
|
|
135
872
|
};
|
|
136
873
|
},
|
|
137
874
|
};
|
|
138
875
|
|
|
139
|
-
// no-juno-sdk-import
|
|
876
|
+
// ─── no-juno-sdk-import ──────────────────────────────────────────────────────
|
|
140
877
|
//
|
|
141
878
|
// It has to catch two spellings, because it runs in two places. The server
|
|
142
879
|
// lints the *bundled* output, where esbuild has marked juno:sdk external and an
|
|
@@ -163,15 +900,20 @@ const noJunoSdkImport = {
|
|
|
163
900
|
CallExpression(node) {
|
|
164
901
|
const isRequire =
|
|
165
902
|
node.callee.type === 'Identifier' && node.callee.name === 'require';
|
|
166
|
-
const isDynamicImport = node.callee.type === 'Import';
|
|
167
903
|
if (
|
|
168
|
-
|
|
904
|
+
isRequire &&
|
|
169
905
|
node.arguments.length === 1 &&
|
|
170
906
|
isSdk(node.arguments[0])
|
|
171
907
|
) {
|
|
172
908
|
context.report({ node, message: MESSAGE });
|
|
173
909
|
}
|
|
174
910
|
},
|
|
911
|
+
// `import('juno:sdk')` is an ImportExpression, not a CallExpression with
|
|
912
|
+
// an `Import` callee — the shape the rule looked for until a test asked
|
|
913
|
+
// for it and found nothing reported.
|
|
914
|
+
ImportExpression(node) {
|
|
915
|
+
if (isSdk(node.source)) context.report({ node, message: MESSAGE });
|
|
916
|
+
},
|
|
175
917
|
ImportDeclaration(node) {
|
|
176
918
|
if (isSdk(node.source)) context.report({ node, message: MESSAGE });
|
|
177
919
|
},
|
|
@@ -185,11 +927,95 @@ const noJunoSdkImport = {
|
|
|
185
927
|
},
|
|
186
928
|
};
|
|
187
929
|
|
|
930
|
+
// ─── no-process-exit ─────────────────────────────────────────────────────────
|
|
931
|
+
|
|
932
|
+
const noProcessExit = {
|
|
933
|
+
meta: {
|
|
934
|
+
type: 'problem',
|
|
935
|
+
docs: { description: 'integrations must not call process.exit()' },
|
|
936
|
+
schema: [],
|
|
937
|
+
},
|
|
938
|
+
create(context) {
|
|
939
|
+
return {
|
|
940
|
+
CallExpression(node) {
|
|
941
|
+
const p = calleePath(node);
|
|
942
|
+
if (!tailIs(p, 'process', 'exit') && !tailIs(p, 'process', 'abort')) {
|
|
943
|
+
return;
|
|
944
|
+
}
|
|
945
|
+
context.report({
|
|
946
|
+
node,
|
|
947
|
+
message:
|
|
948
|
+
'the host owns the sandbox lifecycle — return or throw and let the runtime send the terminal message. process.exit() skips it, and the invocation is recorded as failed',
|
|
949
|
+
});
|
|
950
|
+
},
|
|
951
|
+
};
|
|
952
|
+
},
|
|
953
|
+
};
|
|
954
|
+
|
|
955
|
+
// ─── require-signal-in-listener ──────────────────────────────────────────────
|
|
956
|
+
|
|
957
|
+
const requireSignalInListener = {
|
|
958
|
+
meta: {
|
|
959
|
+
type: 'suggestion',
|
|
960
|
+
docs: { description: 'a listener should observe ctx.signal' },
|
|
961
|
+
schema: [],
|
|
962
|
+
},
|
|
963
|
+
create(context) {
|
|
964
|
+
return {
|
|
965
|
+
Property(node) {
|
|
966
|
+
if (node.computed) return;
|
|
967
|
+
const key =
|
|
968
|
+
node.key.type === 'Identifier'
|
|
969
|
+
? node.key.name
|
|
970
|
+
: literalString(node.key);
|
|
971
|
+
if (key !== 'listener') return;
|
|
972
|
+
if (!isFunction(node.value)) return;
|
|
973
|
+
|
|
974
|
+
let usesSignal = false;
|
|
975
|
+
walk(node.value.body, (n) => {
|
|
976
|
+
if (usesSignal) return false;
|
|
977
|
+
if (n.type === 'Identifier' && n.name === 'signal') usesSignal = true;
|
|
978
|
+
return undefined;
|
|
979
|
+
});
|
|
980
|
+
// Destructuring `signal` out of the context is not enough on its own —
|
|
981
|
+
// only the body decides, so the parameter list is not consulted.
|
|
982
|
+
if (usesSignal) return;
|
|
983
|
+
|
|
984
|
+
context.report({
|
|
985
|
+
node: node.key,
|
|
986
|
+
message:
|
|
987
|
+
'this listener never reads ctx.signal, so it cannot shut down on SIGTERM — the supervisor will kill it on every restart. Check signal.aborted in the loop, or pass it to the client you are subscribing with',
|
|
988
|
+
});
|
|
989
|
+
},
|
|
990
|
+
};
|
|
991
|
+
},
|
|
992
|
+
};
|
|
993
|
+
|
|
188
994
|
module.exports = {
|
|
189
995
|
rules: {
|
|
190
996
|
'no-dynamic-step-id': noDynamicStepId,
|
|
191
|
-
'no-
|
|
192
|
-
'
|
|
997
|
+
'no-dynamic-scoped-name': noDynamicScopedName,
|
|
998
|
+
'no-journaled-in-step': noJournaledInStep,
|
|
999
|
+
'require-effects-in-step': requireEffectsInStep,
|
|
1000
|
+
'valid-duration': validDuration,
|
|
1001
|
+
'no-concurrent-capabilities': noConcurrentCapabilities,
|
|
1002
|
+
'no-nondeterminism': noNondeterminism,
|
|
1003
|
+
'no-floating-capability': noFloatingCapability,
|
|
1004
|
+
'no-credential-leak': noCredentialLeak,
|
|
1005
|
+
'require-suspension-label': requireSuspensionLabel,
|
|
1006
|
+
'no-duplicate-step-id': noDuplicateStepId,
|
|
1007
|
+
'prefer-step-for-clock': preferStepForClock,
|
|
1008
|
+
'no-module-state': noModuleState,
|
|
193
1009
|
'no-juno-sdk-import': noJunoSdkImport,
|
|
1010
|
+
'no-process-exit': noProcessExit,
|
|
1011
|
+
'require-signal-in-listener': requireSignalInListener,
|
|
1012
|
+
},
|
|
1013
|
+
// The rule sets by lint target, from rulesets.json. Juno's verify step reads
|
|
1014
|
+
// the same file, so the rules enforced on deploy and the rules an author
|
|
1015
|
+
// lints with cannot diverge.
|
|
1016
|
+
configs: {
|
|
1017
|
+
flow: rulesets.flow,
|
|
1018
|
+
integration: rulesets.integration,
|
|
1019
|
+
bundle: rulesets.bundle,
|
|
194
1020
|
},
|
|
195
1021
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@junoflow/eslint-plugin",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "ESLint rules for Juno flows and integrations",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -12,11 +12,19 @@
|
|
|
12
12
|
"main": "index.js",
|
|
13
13
|
"files": [
|
|
14
14
|
"index.js",
|
|
15
|
+
"rulesets.json",
|
|
15
16
|
"README.md"
|
|
16
17
|
],
|
|
18
|
+
"scripts": {
|
|
19
|
+
"test": "node --test \"test/**/*.test.js\""
|
|
20
|
+
},
|
|
17
21
|
"peerDependencies": {
|
|
18
22
|
"eslint": ">=9"
|
|
19
23
|
},
|
|
24
|
+
"devDependencies": {
|
|
25
|
+
"@typescript-eslint/parser": "^8.0.0",
|
|
26
|
+
"eslint": "^9.0.0"
|
|
27
|
+
},
|
|
20
28
|
"engines": {
|
|
21
29
|
"node": ">=20"
|
|
22
30
|
}
|
package/rulesets.json
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$comment": "The rule sets, by lint target. This file is the single source: index.js exports it as `configs`, the @junoflow/cli preset spreads `integration`, and Juno's verify step reads it to build the eslint config it runs server-side. A rule added to index.js but not listed here runs nowhere.",
|
|
3
|
+
"flow": {
|
|
4
|
+
"juno/no-dynamic-step-id": "error",
|
|
5
|
+
"juno/no-dynamic-scoped-name": "error",
|
|
6
|
+
"juno/no-journaled-in-step": "error",
|
|
7
|
+
"juno/no-concurrent-capabilities": "error",
|
|
8
|
+
"juno/no-nondeterminism": "error",
|
|
9
|
+
"juno/no-floating-capability": "error",
|
|
10
|
+
"juno/no-credential-leak": "error",
|
|
11
|
+
"juno/valid-duration": "error",
|
|
12
|
+
"juno/no-juno-sdk-import": "error",
|
|
13
|
+
"juno/require-effects-in-step": "warn",
|
|
14
|
+
"juno/require-suspension-label": "warn",
|
|
15
|
+
"juno/no-duplicate-step-id": "warn",
|
|
16
|
+
"juno/prefer-step-for-clock": "warn",
|
|
17
|
+
"juno/no-module-state": "warn"
|
|
18
|
+
},
|
|
19
|
+
"integration": {
|
|
20
|
+
"juno/no-juno-sdk-import": "error",
|
|
21
|
+
"juno/no-process-exit": "error",
|
|
22
|
+
"juno/require-signal-in-listener": "warn"
|
|
23
|
+
},
|
|
24
|
+
"bundle": {
|
|
25
|
+
"juno/no-juno-sdk-import": "error"
|
|
26
|
+
}
|
|
27
|
+
}
|