@junoflow/eslint-plugin 0.1.4 → 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 +16 -16
- package/index.js +151 -17
- package/package.json +1 -1
- package/rulesets.json +3 -1
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
|
|
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
|
|
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
|
-
/** `
|
|
199
|
-
function
|
|
200
|
-
return !!p && p.length >= 3 && p[p.length - 3] === '
|
|
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
|
|
203
|
+
/** A flow target's invoke()/invokeAll(): a target call that suspends. */
|
|
204
204
|
function isFlowInvoke(p) {
|
|
205
|
-
if (!
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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: '
|
|
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
|
|
501
|
-
function
|
|
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 (
|
|
506
|
-
// Promise.all(items.map(x =>
|
|
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) =>
|
|
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(
|
|
532
|
-
} else if (
|
|
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
|
-
"
|
|
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
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",
|