@junoflow/eslint-plugin 0.1.3 → 0.1.5

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
@@ -195,14 +195,14 @@ function isFindingsCall(p) {
195
195
  return obj === 'findings' && FINDING_METHODS.includes(method) ? method : null;
196
196
  }
197
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';
198
+ /** `targets.<name>.<action>()`, with or without a `ctx.` prefix. */
199
+ function isTargetCall(p) {
200
+ return !!p && p.length >= 3 && p[p.length - 3] === 'targets';
201
201
  }
202
202
 
203
- /** A flow binding's invoke()/invokeAll(): a binding call that suspends. */
203
+ /** A flow target's invoke()/invokeAll(): a target call that suspends. */
204
204
  function isFlowInvoke(p) {
205
- if (!isBindingCall(p)) return null;
205
+ if (!isTargetCall(p)) return null;
206
206
  const last = p[p.length - 1];
207
207
  return last === 'invoke' || last === 'invokeAll' ? last : null;
208
208
  }
@@ -240,7 +240,7 @@ function isCapabilityCall(p) {
240
240
  !!isStepCall(p) ||
241
241
  !!isStateCall(p) ||
242
242
  !!isFindingsCall(p) ||
243
- isBindingCall(p) ||
243
+ isTargetCall(p) ||
244
244
  isSleep(p) ||
245
245
  isWaitForEvent(p) ||
246
246
  isSolar(p)
@@ -251,14 +251,14 @@ function isCapabilityCall(p) {
251
251
  * A side effect that really happens again on every replay and every retry —
252
252
  * the right-hand column of the durability table, minus the reads.
253
253
  *
254
- * `state.get`, `now()`, `solar()` and a binding's `getState()` are reads and
254
+ * `state.get`, `now()`, `solar()` and a target's `getState()` are reads and
255
255
  * are deliberately absent: wrapping a read in a step *pins* it across a
256
256
  * suspension, which is usually the opposite of what the author wants. When one
257
257
  * of them must be stable, `prefer-step-for-clock` says so at warning level
258
258
  * rather than this rule saying it at error level.
259
259
  */
260
260
  function isRepeatedEffect(p) {
261
- if (isBindingCall(p)) {
261
+ if (isTargetCall(p)) {
262
262
  const last = p[p.length - 1];
263
263
  return last !== 'getState' && !isFlowInvoke(p);
264
264
  }
@@ -488,28 +488,44 @@ const validDuration = {
488
488
 
489
489
  const PROMISE_COMBINATORS = new Set(['all', 'allSettled', 'race', 'any']);
490
490
 
491
+ /**
492
+ * A call that ends the sandbox process: it fires a terminal message and exits,
493
+ * so the run resumes later from the journal. Two of them in one Promise
494
+ * combinator is not slow, it is wrong — the first to fire exits, and the others
495
+ * never happen at all.
496
+ *
497
+ * Ordinary capability calls are deliberately not here. The socket still carries
498
+ * one request at a time, but SocketClient queues them (sdk/src/socket.ts), so a
499
+ * concurrent fan-out is correct and merely serialized — a performance nuance,
500
+ * not a failed deploy.
501
+ */
502
+ function isSuspendingCall(p) {
503
+ return !!isFlowInvoke(p) || isSleep(p) || isWaitForEvent(p);
504
+ }
505
+
491
506
  const noConcurrentCapabilities = {
492
507
  meta: {
493
508
  type: 'problem',
494
509
  docs: {
495
- description: 'capability calls must not be issued concurrently',
510
+ description: 'suspending calls must not be issued concurrently',
496
511
  },
497
512
  schema: [],
498
513
  },
499
514
  create(context) {
500
- /** True when this element resolves to a capability call. */
501
- function isCapabilityElement(el) {
515
+ /** True when this element resolves to a suspending call. */
516
+ function isSuspendingElement(el) {
502
517
  if (!el) return false;
503
518
  const inner = el.type === 'AwaitExpression' ? el.argument : el;
504
519
  if (inner.type === 'CallExpression') {
505
- if (isCapabilityCall(calleePath(inner))) return true;
506
- // Promise.all(items.map(x => bindings.x.y(…))) — the fan-out spelling.
520
+ if (isSuspendingCall(calleePath(inner))) return true;
521
+ // Promise.all(items.map(x => targets.x.invoke(…))) — the fan-out
522
+ // spelling, one element syntactically and N suspensions at runtime.
507
523
  if (
508
524
  tailIs(calleePath(inner), 'map') &&
509
525
  inner.arguments.some(
510
526
  (a) =>
511
527
  isFunction(a) &&
512
- subtreeHasCall(a.body, (p) => isCapabilityCall(p))
528
+ subtreeHasCall(a.body, (p) => isSuspendingCall(p))
513
529
  )
514
530
  ) {
515
531
  return true;
@@ -528,8 +544,8 @@ const noConcurrentCapabilities = {
528
544
  const arg = node.arguments[0];
529
545
  let concurrent = 0;
530
546
  if (arg && arg.type === 'ArrayExpression') {
531
- concurrent = arg.elements.filter(isCapabilityElement).length;
532
- } else if (isCapabilityElement(arg)) {
547
+ concurrent = arg.elements.filter(isSuspendingElement).length;
548
+ } else if (isSuspendingElement(arg)) {
533
549
  // Promise.all(items.map(…)) — one element syntactically, N at runtime.
534
550
  concurrent = 2;
535
551
  }
@@ -538,7 +554,7 @@ const noConcurrentCapabilities = {
538
554
  context.report({
539
555
  node,
540
556
  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",
557
+ "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
558
  });
543
559
  },
544
560
  };
@@ -873,6 +889,67 @@ const noModuleState = {
873
889
  },
874
890
  };
875
891
 
892
+ // ─── no-event-cast ───────────────────────────────────────────────────────────
893
+
894
+ /**
895
+ * Unwraps the TypeScript expression wrappers a cast can be buried under, so
896
+ * `event as unknown as { key?: string }` and `(event as any)!` both reduce to
897
+ * the `event` identifier. Returns the innermost expression.
898
+ */
899
+ function unwrapTS(node) {
900
+ while (
901
+ node &&
902
+ (node.type === 'TSAsExpression' ||
903
+ node.type === 'TSTypeAssertion' ||
904
+ node.type === 'TSSatisfiesExpression' ||
905
+ node.type === 'TSNonNullExpression')
906
+ ) {
907
+ node = node.expression;
908
+ }
909
+ return node;
910
+ }
911
+
912
+ const noEventCast = {
913
+ meta: {
914
+ type: 'problem',
915
+ docs: {
916
+ description:
917
+ 'do not cast the trigger event to reach a member the generated types do not declare',
918
+ },
919
+ schema: [],
920
+ },
921
+ create(context) {
922
+ return {
923
+ MemberExpression(node) {
924
+ const obj = node.object;
925
+ if (
926
+ obj.type !== 'TSAsExpression' &&
927
+ obj.type !== 'TSTypeAssertion' &&
928
+ obj.type !== 'TSNonNullExpression'
929
+ ) {
930
+ return;
931
+ }
932
+ const base = unwrapTS(obj);
933
+ if (!base || base.type !== 'Identifier' || base.name !== 'event') {
934
+ return;
935
+ }
936
+ const member = node.computed
937
+ ? null
938
+ : node.property && node.property.name;
939
+ context.report({
940
+ node,
941
+ message:
942
+ `casting \`event\`${member ? ` to read \`${member}\`` : ''} defeats the generated types — ` +
943
+ "flow-env.d.ts declares exactly what this trigger's event carries, " +
944
+ 'so a cast makes an absent member compile and be undefined at run ' +
945
+ "time. A keyed modifier's instance arrives as `event.key`; anything " +
946
+ 'else has to come from the payload',
947
+ });
948
+ },
949
+ };
950
+ },
951
+ };
952
+
876
953
  // ─── no-juno-sdk-import ──────────────────────────────────────────────────────
877
954
  //
878
955
  // It has to catch two spellings, because it runs in two places. The server
@@ -991,6 +1068,61 @@ const requireSignalInListener = {
991
1068
  },
992
1069
  };
993
1070
 
1071
+ // ─── prefer-claim-over-set ───────────────────────────────────────────────────
1072
+ //
1073
+ // state.set writes a state's base — the value it holds when no layer of its
1074
+ // stack is active. On a state with no layers that is the whole story and this
1075
+ // rule says nothing. On a state that has declared a claim slot, a claim can
1076
+ // outrank the base, and a flow that meant "make it this now" has written
1077
+ // somewhere nobody is currently reading.
1078
+ //
1079
+ // The state ids are an option rather than something the rule works out for
1080
+ // itself, because whether a state has slots is a fact about the registry and
1081
+ // not about the source. Juno's verify step renders the option from the same
1082
+ // catalog typegen reads; an author linting locally without it gets a rule that
1083
+ // reports nothing, which is the right way for a missing catalog to fail.
1084
+ //
1085
+ // A warning, not an error, on the severity rule in rulesets.json: this reasons
1086
+ // about intent. Writing the base of a state that has slots is a legitimate
1087
+ // thing to do — it changes what happens when the claims let go — and a deploy
1088
+ // must not fail for it.
1089
+ const preferClaimOverSet = {
1090
+ meta: {
1091
+ type: 'suggestion',
1092
+ docs: {
1093
+ description:
1094
+ 'prefer state.claim over state.set on a state that declares claim slots',
1095
+ },
1096
+ schema: [
1097
+ {
1098
+ type: 'object',
1099
+ properties: {
1100
+ states: { type: 'array', items: { type: 'string' } },
1101
+ },
1102
+ additionalProperties: false,
1103
+ },
1104
+ ],
1105
+ },
1106
+ create(context) {
1107
+ const ids = new Set((context.options[0] || {}).states || []);
1108
+ if (ids.size === 0) return {};
1109
+ return {
1110
+ CallExpression(node) {
1111
+ if (isStateCall(calleePath(node)) !== 'set') return;
1112
+ const id = node.arguments[0];
1113
+ if (!id || id.type !== 'Literal' || typeof id.value !== 'string') {
1114
+ return;
1115
+ }
1116
+ if (!ids.has(id.value)) return;
1117
+ context.report({
1118
+ node: id,
1119
+ message: `${id.value} has claim slots, so state.set writes its base and a claim can outrank it — the value may not move. Use state.claim(id, value, { slot, 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`,
1120
+ });
1121
+ },
1122
+ };
1123
+ },
1124
+ };
1125
+
994
1126
  module.exports = {
995
1127
  rules: {
996
1128
  'no-dynamic-step-id': noDynamicStepId,
@@ -1006,6 +1138,8 @@ module.exports = {
1006
1138
  'no-duplicate-step-id': noDuplicateStepId,
1007
1139
  'prefer-step-for-clock': preferStepForClock,
1008
1140
  'no-module-state': noModuleState,
1141
+ 'prefer-claim-over-set': preferClaimOverSet,
1142
+ 'no-event-cast': noEventCast,
1009
1143
  'no-juno-sdk-import': noJunoSdkImport,
1010
1144
  'no-process-exit': noProcessExit,
1011
1145
  '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.3",
3
+ "version": "0.1.5",
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",