@junoflow/eslint-plugin 0.1.5 → 0.6.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.
Files changed (3) hide show
  1. package/README.md +4 -0
  2. package/index.js +63 -31
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -59,6 +59,10 @@ run again from the top. Anything effectful left outside a step happens again on
59
59
  that pass. That transition is the gate, and it is why the rule fires on a
60
60
  handler that suspends even when it takes no step at all.
61
61
 
62
+ A control's `press()` and `extend()` count as effects — each call is one more
63
+ press, one more extension — while `activate()` and `release()` do not: they name
64
+ the end state, so a replay lands where the first call did.
65
+
62
66
  It stays at warning level because it is the rule most likely to misjudge correct
63
67
  code, and Juno runs these rules on deploy: at warning level a misjudgement costs
64
68
  an author a message rather than a release.
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;
@@ -200,6 +213,17 @@ function isTargetCall(p) {
200
213
  return !!p && p.length >= 3 && p[p.length - 3] === 'targets';
201
214
  }
202
215
 
216
+ // The four verbs a control handle carries. Which of them a given handle has
217
+ // follows from the control's type, but the verb alone says what it does.
218
+ const CONTROL_METHODS = ['press', 'activate', 'extend', 'release'];
219
+
220
+ /** `controls.<binding>.<verb>()` — the verb, or null. */
221
+ function isControlCall(p) {
222
+ if (!p || p.length < 3) return null;
223
+ const [obj, method] = [p[p.length - 3], p[p.length - 1]];
224
+ return obj === 'controls' && CONTROL_METHODS.includes(method) ? method : null;
225
+ }
226
+
203
227
  /** A flow target's invoke()/invokeAll(): a target call that suspends. */
204
228
  function isFlowInvoke(p) {
205
229
  if (!isTargetCall(p)) return null;
@@ -256,6 +280,10 @@ function isCapabilityCall(p) {
256
280
  * suspension, which is usually the opposite of what the author wants. When one
257
281
  * of them must be stable, `prefer-step-for-clock` says so at warning level
258
282
  * rather than this rule saying it at error level.
283
+ *
284
+ * Of a control's verbs only `press` and `extend` are here: each call is one
285
+ * more press, one more extension. `activate` and `release` name the end state,
286
+ * so a replay lands where the first call did, and they are left alone.
259
287
  */
260
288
  function isRepeatedEffect(p) {
261
289
  if (isTargetCall(p)) {
@@ -264,6 +292,8 @@ function isRepeatedEffect(p) {
264
292
  }
265
293
  const state = isStateCall(p);
266
294
  if (state) return state !== 'get' && state !== 'scoped';
295
+ const control = isControlCall(p);
296
+ if (control) return control === 'press' || control === 'extend';
267
297
  return isFetch(p) || isLog(p);
268
298
  }
269
299
 
@@ -475,9 +505,11 @@ const validDuration = {
475
505
  check(objectProp(node.arguments[1], 'timeout'));
476
506
  return;
477
507
  }
508
+ // The binding names the state, the slot and the signal, so a claim's
509
+ // options are its second argument and a signal's its first.
478
510
  const state = isStateCall(p);
479
- if (state === 'claim') check(objectProp(node.arguments[2], 'ttl'));
480
- if (state === 'signal') check(objectProp(node.arguments[2], 'ttl'));
511
+ if (state === 'claim') check(objectProp(node.arguments[1], 'ttl'));
512
+ if (state === 'signal') check(objectProp(node.arguments[0], 'ttl'));
481
513
  if (isFlowInvoke(p)) check(objectProp(node.arguments[1], 'timeout'));
482
514
  },
483
515
  };
@@ -1070,17 +1102,19 @@ const requireSignalInListener = {
1070
1102
 
1071
1103
  // ─── prefer-claim-over-set ───────────────────────────────────────────────────
1072
1104
  //
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
1105
+ // state.<binding>.set writes a state's base — the value it holds when no layer
1106
+ // of its stack is active. On a state with no layers that is the whole story and this
1075
1107
  // rule says nothing. On a state that has declared a claim slot, a claim can
1076
1108
  // outrank the base, and a flow that meant "make it this now" has written
1077
1109
  // somewhere nobody is currently reading.
1078
1110
  //
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.
1111
+ // The option names *bindings*, not states, because the binding is all the
1112
+ // source says: `state.<binding>.set(...)` never spells the state id. Which
1113
+ // bindings resolve to a slotted state is a fact about the manifest and the
1114
+ // registry, not about the source, so the rule cannot work it out and is told.
1115
+ // Juno's verify step renders the option from the same catalog typegen reads;
1116
+ // an author linting locally without it gets a rule that reports nothing, which
1117
+ // is the right way for a missing catalog to fail.
1084
1118
  //
1085
1119
  // A warning, not an error, on the severity rule in rulesets.json: this reasons
1086
1120
  // about intent. Writing the base of a state that has slots is a legitimate
@@ -1091,7 +1125,7 @@ const preferClaimOverSet = {
1091
1125
  type: 'suggestion',
1092
1126
  docs: {
1093
1127
  description:
1094
- 'prefer state.claim over state.set on a state that declares claim slots',
1128
+ 'prefer a claim binding over set on a state that declares claim slots',
1095
1129
  },
1096
1130
  schema: [
1097
1131
  {
@@ -1108,15 +1142,13 @@ const preferClaimOverSet = {
1108
1142
  if (ids.size === 0) return {};
1109
1143
  return {
1110
1144
  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;
1145
+ const p = calleePath(node);
1146
+ if (isStateCall(p) !== 'set') return;
1147
+ const binding = stateBindingName(p);
1148
+ if (!binding || !ids.has(binding)) return;
1117
1149
  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`,
1150
+ node: node.callee,
1151
+ 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`,
1120
1152
  });
1121
1153
  },
1122
1154
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@junoflow/eslint-plugin",
3
- "version": "0.1.5",
3
+ "version": "0.6.0",
4
4
  "description": "ESLint rules for Juno flows and integrations",
5
5
  "license": "MIT",
6
6
  "repository": {