@junoflow/eslint-plugin 0.1.4 → 0.3.0

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 CHANGED
@@ -17,21 +17,21 @@ These are about the replay contract: a Juno run re-executes your handler from
17
17
  the top after every suspension and every retry, replaying completed steps from a
18
18
  journal instead of re-running them. Everything below follows from that.
19
19
 
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 |
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 suspending calls — `sleep`, `waitForEvent`, `invoke`/`invokeAll`. The first to fire exits; the rest never run |
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 |
35
35
 
36
36
  ## Integration rules
37
37
 
@@ -49,7 +49,7 @@ journal instead of re-running them. Everything below follows from that.
49
49
  ## Why `require-effects-in-step` is conditional
50
50
 
51
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
52
+ re-run only if it throws, as a whole, so wrapping its one target call in a step
53
53
  buys nothing — and demanding it would make the simplest flows the most
54
54
  annotated.
55
55
 
package/index.js CHANGED
@@ -123,7 +123,7 @@ function subtreeHasCall(root, pred) {
123
123
  * null.
124
124
  *
125
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
126
+ * the call site (`step.run('x', fn, await state.y.get())`) is inside the
127
127
  * CallExpression but runs outside the step, and the two have opposite replay
128
128
  * behaviour.
129
129
  */
@@ -172,22 +172,35 @@ function isStepCall(p) {
172
172
  return null;
173
173
  }
174
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. */
175
+ // The six verbs a binding handle carries. `scoped` is not among them: it is a
176
+ // method on `state` itself, not on a binding, and stays two segments long.
177
+ const STATE_METHODS = ['get', 'set', 'claim', 'release', 'signal', 'retract'];
178
+
179
+ /**
180
+ * The state verb, or null. A binding is a handle — `state.<binding>.<verb>()`,
181
+ * the shape `isTargetCall` already matches — so the state segment is third
182
+ * from the end. `state.scoped()` is the one exception and keeps its own arm.
183
+ */
185
184
  function isStateCall(p) {
186
- if (!p || p.length < 2) return null;
187
- const [obj, method] = [p[p.length - 2], p[p.length - 1]];
185
+ if (!p) return null;
186
+ if (tailIs(p, 'state', 'scoped')) return 'scoped';
187
+ if (p.length < 3) return null;
188
+ const [obj, method] = [p[p.length - 3], p[p.length - 1]];
188
189
  return obj === 'state' && STATE_METHODS.includes(method) ? method : null;
189
190
  }
190
191
 
192
+ /**
193
+ * The binding name in `state.<binding>.<verb>()`, or null for `state.scoped()`
194
+ * and anything that is not a state call. A property name is always static, so
195
+ * unlike the string-literal argument it replaces there is no computed form for
196
+ * a rule to fall blind on.
197
+ */
198
+ function stateBindingName(p) {
199
+ const verb = isStateCall(p);
200
+ if (!verb || verb === 'scoped') return null;
201
+ return p[p.length - 2];
202
+ }
203
+
191
204
  const FINDING_METHODS = ['open', 'clear', 'set'];
192
205
  function isFindingsCall(p) {
193
206
  if (!p || p.length < 2) return null;
@@ -195,14 +208,14 @@ function isFindingsCall(p) {
195
208
  return obj === 'findings' && FINDING_METHODS.includes(method) ? method : null;
196
209
  }
197
210
 
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';
211
+ /** `targets.<name>.<action>()`, with or without a `ctx.` prefix. */
212
+ function isTargetCall(p) {
213
+ return !!p && p.length >= 3 && p[p.length - 3] === 'targets';
201
214
  }
202
215
 
203
- /** A flow binding's invoke()/invokeAll(): a binding call that suspends. */
216
+ /** A flow target's invoke()/invokeAll(): a target call that suspends. */
204
217
  function isFlowInvoke(p) {
205
- if (!isBindingCall(p)) return null;
218
+ if (!isTargetCall(p)) return null;
206
219
  const last = p[p.length - 1];
207
220
  return last === 'invoke' || last === 'invokeAll' ? last : null;
208
221
  }
@@ -240,7 +253,7 @@ function isCapabilityCall(p) {
240
253
  !!isStepCall(p) ||
241
254
  !!isStateCall(p) ||
242
255
  !!isFindingsCall(p) ||
243
- isBindingCall(p) ||
256
+ isTargetCall(p) ||
244
257
  isSleep(p) ||
245
258
  isWaitForEvent(p) ||
246
259
  isSolar(p)
@@ -251,14 +264,14 @@ function isCapabilityCall(p) {
251
264
  * A side effect that really happens again on every replay and every retry —
252
265
  * the right-hand column of the durability table, minus the reads.
253
266
  *
254
- * `state.get`, `now()`, `solar()` and a binding's `getState()` are reads and
267
+ * `state.get`, `now()`, `solar()` and a target's `getState()` are reads and
255
268
  * are deliberately absent: wrapping a read in a step *pins* it across a
256
269
  * suspension, which is usually the opposite of what the author wants. When one
257
270
  * of them must be stable, `prefer-step-for-clock` says so at warning level
258
271
  * rather than this rule saying it at error level.
259
272
  */
260
273
  function isRepeatedEffect(p) {
261
- if (isBindingCall(p)) {
274
+ if (isTargetCall(p)) {
262
275
  const last = p[p.length - 1];
263
276
  return last !== 'getState' && !isFlowInvoke(p);
264
277
  }
@@ -475,9 +488,11 @@ const validDuration = {
475
488
  check(objectProp(node.arguments[1], 'timeout'));
476
489
  return;
477
490
  }
491
+ // The binding names the state, the slot and the signal, so a claim's
492
+ // options are its second argument and a signal's its first.
478
493
  const state = isStateCall(p);
479
- if (state === 'claim') check(objectProp(node.arguments[2], 'ttl'));
480
- if (state === 'signal') check(objectProp(node.arguments[2], 'ttl'));
494
+ if (state === 'claim') check(objectProp(node.arguments[1], 'ttl'));
495
+ if (state === 'signal') check(objectProp(node.arguments[0], 'ttl'));
481
496
  if (isFlowInvoke(p)) check(objectProp(node.arguments[1], 'timeout'));
482
497
  },
483
498
  };
@@ -488,28 +503,44 @@ const validDuration = {
488
503
 
489
504
  const PROMISE_COMBINATORS = new Set(['all', 'allSettled', 'race', 'any']);
490
505
 
506
+ /**
507
+ * A call that ends the sandbox process: it fires a terminal message and exits,
508
+ * so the run resumes later from the journal. Two of them in one Promise
509
+ * combinator is not slow, it is wrong — the first to fire exits, and the others
510
+ * never happen at all.
511
+ *
512
+ * Ordinary capability calls are deliberately not here. The socket still carries
513
+ * one request at a time, but SocketClient queues them (sdk/src/socket.ts), so a
514
+ * concurrent fan-out is correct and merely serialized — a performance nuance,
515
+ * not a failed deploy.
516
+ */
517
+ function isSuspendingCall(p) {
518
+ return !!isFlowInvoke(p) || isSleep(p) || isWaitForEvent(p);
519
+ }
520
+
491
521
  const noConcurrentCapabilities = {
492
522
  meta: {
493
523
  type: 'problem',
494
524
  docs: {
495
- description: 'capability calls must not be issued concurrently',
525
+ description: 'suspending calls must not be issued concurrently',
496
526
  },
497
527
  schema: [],
498
528
  },
499
529
  create(context) {
500
- /** True when this element resolves to a capability call. */
501
- function isCapabilityElement(el) {
530
+ /** True when this element resolves to a suspending call. */
531
+ function isSuspendingElement(el) {
502
532
  if (!el) return false;
503
533
  const inner = el.type === 'AwaitExpression' ? el.argument : el;
504
534
  if (inner.type === 'CallExpression') {
505
- if (isCapabilityCall(calleePath(inner))) return true;
506
- // Promise.all(items.map(x => bindings.x.y(…))) — the fan-out spelling.
535
+ if (isSuspendingCall(calleePath(inner))) return true;
536
+ // Promise.all(items.map(x => targets.x.invoke(…))) — the fan-out
537
+ // spelling, one element syntactically and N suspensions at runtime.
507
538
  if (
508
539
  tailIs(calleePath(inner), 'map') &&
509
540
  inner.arguments.some(
510
541
  (a) =>
511
542
  isFunction(a) &&
512
- subtreeHasCall(a.body, (p) => isCapabilityCall(p))
543
+ subtreeHasCall(a.body, (p) => isSuspendingCall(p))
513
544
  )
514
545
  ) {
515
546
  return true;
@@ -528,8 +559,8 @@ const noConcurrentCapabilities = {
528
559
  const arg = node.arguments[0];
529
560
  let concurrent = 0;
530
561
  if (arg && arg.type === 'ArrayExpression') {
531
- concurrent = arg.elements.filter(isCapabilityElement).length;
532
- } else if (isCapabilityElement(arg)) {
562
+ concurrent = arg.elements.filter(isSuspendingElement).length;
563
+ } else if (isSuspendingElement(arg)) {
533
564
  // Promise.all(items.map(…)) — one element syntactically, N at runtime.
534
565
  concurrent = 2;
535
566
  }
@@ -538,7 +569,7 @@ const noConcurrentCapabilities = {
538
569
  context.report({
539
570
  node,
540
571
  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",
572
+ "sleep(), waitForEvent() and a flow target's invoke() end the sandbox process — the first one to fire wins and the rest never run. Await them one at a time, or use invokeAll() to fan out",
542
573
  });
543
574
  },
544
575
  };
@@ -873,6 +904,67 @@ const noModuleState = {
873
904
  },
874
905
  };
875
906
 
907
+ // ─── no-event-cast ───────────────────────────────────────────────────────────
908
+
909
+ /**
910
+ * Unwraps the TypeScript expression wrappers a cast can be buried under, so
911
+ * `event as unknown as { key?: string }` and `(event as any)!` both reduce to
912
+ * the `event` identifier. Returns the innermost expression.
913
+ */
914
+ function unwrapTS(node) {
915
+ while (
916
+ node &&
917
+ (node.type === 'TSAsExpression' ||
918
+ node.type === 'TSTypeAssertion' ||
919
+ node.type === 'TSSatisfiesExpression' ||
920
+ node.type === 'TSNonNullExpression')
921
+ ) {
922
+ node = node.expression;
923
+ }
924
+ return node;
925
+ }
926
+
927
+ const noEventCast = {
928
+ meta: {
929
+ type: 'problem',
930
+ docs: {
931
+ description:
932
+ 'do not cast the trigger event to reach a member the generated types do not declare',
933
+ },
934
+ schema: [],
935
+ },
936
+ create(context) {
937
+ return {
938
+ MemberExpression(node) {
939
+ const obj = node.object;
940
+ if (
941
+ obj.type !== 'TSAsExpression' &&
942
+ obj.type !== 'TSTypeAssertion' &&
943
+ obj.type !== 'TSNonNullExpression'
944
+ ) {
945
+ return;
946
+ }
947
+ const base = unwrapTS(obj);
948
+ if (!base || base.type !== 'Identifier' || base.name !== 'event') {
949
+ return;
950
+ }
951
+ const member = node.computed
952
+ ? null
953
+ : node.property && node.property.name;
954
+ context.report({
955
+ node,
956
+ message:
957
+ `casting \`event\`${member ? ` to read \`${member}\`` : ''} defeats the generated types — ` +
958
+ "flow-env.d.ts declares exactly what this trigger's event carries, " +
959
+ 'so a cast makes an absent member compile and be undefined at run ' +
960
+ "time. A keyed modifier's instance arrives as `event.key`; anything " +
961
+ 'else has to come from the payload',
962
+ });
963
+ },
964
+ };
965
+ },
966
+ };
967
+
876
968
  // ─── no-juno-sdk-import ──────────────────────────────────────────────────────
877
969
  //
878
970
  // It has to catch two spellings, because it runs in two places. The server
@@ -991,6 +1083,61 @@ const requireSignalInListener = {
991
1083
  },
992
1084
  };
993
1085
 
1086
+ // ─── prefer-claim-over-set ───────────────────────────────────────────────────
1087
+ //
1088
+ // state.<binding>.set writes a state's base — the value it holds when no layer
1089
+ // of its stack is active. On a state with no layers that is the whole story and this
1090
+ // rule says nothing. On a state that has declared a claim slot, a claim can
1091
+ // outrank the base, and a flow that meant "make it this now" has written
1092
+ // somewhere nobody is currently reading.
1093
+ //
1094
+ // The option names *bindings*, not states, because the binding is all the
1095
+ // source says: `state.<binding>.set(...)` never spells the state id. Which
1096
+ // bindings resolve to a slotted state is a fact about the manifest and the
1097
+ // registry, not about the source, so the rule cannot work it out and is told.
1098
+ // Juno's verify step renders the option from the same catalog typegen reads;
1099
+ // an author linting locally without it gets a rule that reports nothing, which
1100
+ // is the right way for a missing catalog to fail.
1101
+ //
1102
+ // A warning, not an error, on the severity rule in rulesets.json: this reasons
1103
+ // about intent. Writing the base of a state that has slots is a legitimate
1104
+ // thing to do — it changes what happens when the claims let go — and a deploy
1105
+ // must not fail for it.
1106
+ const preferClaimOverSet = {
1107
+ meta: {
1108
+ type: 'suggestion',
1109
+ docs: {
1110
+ description:
1111
+ 'prefer a claim binding over set on a state that declares claim slots',
1112
+ },
1113
+ schema: [
1114
+ {
1115
+ type: 'object',
1116
+ properties: {
1117
+ states: { type: 'array', items: { type: 'string' } },
1118
+ },
1119
+ additionalProperties: false,
1120
+ },
1121
+ ],
1122
+ },
1123
+ create(context) {
1124
+ const ids = new Set((context.options[0] || {}).states || []);
1125
+ if (ids.size === 0) return {};
1126
+ return {
1127
+ CallExpression(node) {
1128
+ const p = calleePath(node);
1129
+ if (isStateCall(p) !== 'set') return;
1130
+ const binding = stateBindingName(p);
1131
+ if (!binding || !ids.has(binding)) return;
1132
+ context.report({
1133
+ node: node.callee,
1134
+ message: `${binding} names a state with claim slots, so state.${binding}.set writes its base and a claim can outrank it — the value may not move. Declare a claim binding on the slot and call its claim(value, { ttl }) if you meant this flow's write to take effect now, or keep set if you meant to change what the state falls back to`,
1135
+ });
1136
+ },
1137
+ };
1138
+ },
1139
+ };
1140
+
994
1141
  module.exports = {
995
1142
  rules: {
996
1143
  'no-dynamic-step-id': noDynamicStepId,
@@ -1006,6 +1153,8 @@ module.exports = {
1006
1153
  'no-duplicate-step-id': noDuplicateStepId,
1007
1154
  'prefer-step-for-clock': preferStepForClock,
1008
1155
  'no-module-state': noModuleState,
1156
+ 'prefer-claim-over-set': preferClaimOverSet,
1157
+ 'no-event-cast': noEventCast,
1009
1158
  'no-juno-sdk-import': noJunoSdkImport,
1010
1159
  'no-process-exit': noProcessExit,
1011
1160
  'require-signal-in-listener': requireSignalInListener,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@junoflow/eslint-plugin",
3
- "version": "0.1.4",
3
+ "version": "0.3.0",
4
4
  "description": "ESLint rules for Juno flows and integrations",
5
5
  "license": "MIT",
6
6
  "repository": {
package/rulesets.json CHANGED
@@ -10,11 +10,13 @@
10
10
  "juno/no-credential-leak": "error",
11
11
  "juno/valid-duration": "error",
12
12
  "juno/no-juno-sdk-import": "error",
13
+ "juno/no-event-cast": "error",
13
14
  "juno/require-effects-in-step": "warn",
14
15
  "juno/require-suspension-label": "warn",
15
16
  "juno/no-duplicate-step-id": "warn",
16
17
  "juno/prefer-step-for-clock": "warn",
17
- "juno/no-module-state": "warn"
18
+ "juno/no-module-state": "warn",
19
+ "juno/prefer-claim-over-set": "warn"
18
20
  },
19
21
  "integration": {
20
22
  "juno/no-juno-sdk-import": "error",