@junoflow/eslint-plugin 0.1.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 +44 -0
  2. package/index.js +195 -0
  3. package/package.json +29 -0
package/README.md ADDED
@@ -0,0 +1,44 @@
1
+ # @junoflow/eslint-plugin
2
+
3
+ The lint rules [Juno](https://github.com/boivie/juno) applies to flows and
4
+ integrations. This package is the **single source**: the Juno server embeds this
5
+ exact file and runs these exact rules during verification, so a project that
6
+ lints clean locally does not fail with a 422 on deploy.
7
+
8
+ ```bash
9
+ npm install --save-dev @junoflow/eslint-plugin eslint
10
+ ```
11
+
12
+ Most integration authors do not install it directly —
13
+ [`@junoflow/cli`](https://www.npmjs.com/package/@junoflow/cli) ships an
14
+ `eslint.config.js` preset that enables the right rules for you.
15
+
16
+ ## Rules
17
+
18
+ | Rule | Applies to | Catches |
19
+ | ------------------------- | ---------- | -------------------------------------------------------------------------------------- |
20
+ | `juno/no-dynamic-step-id` | flows | `step.run(id)` where `id` is not a static string literal, or contains the reserved `#` |
21
+ | `juno/no-sleep-in-step` | flows | `sleep()` / `waitForEvent()` inside a `step.run()` callback |
22
+ | `juno/no-juno-sdk-import` | both | importing from `juno:sdk` — every type is an ambient global |
23
+ | `juno/require-in-step` | flows | `log()` / `now()` / `fetch()` outside a step. Defined, enabled nowhere |
24
+
25
+ ## One asymmetry, on purpose
26
+
27
+ The server lints the **bundled output**; your editor and `npm run lint` lint the
28
+ **source**. That is how `no-juno-sdk-import` works server-side: `juno:sdk` is an
29
+ esbuild external, so an import survives into the bundle as
30
+ `require('juno:sdk')`. Both ends catch it; they catch it differently.
31
+
32
+ ## Manual use
33
+
34
+ ```js
35
+ // eslint.config.js
36
+ import juno from '@junoflow/eslint-plugin';
37
+
38
+ export default [
39
+ {
40
+ plugins: { juno },
41
+ rules: { 'juno/no-juno-sdk-import': 'error' },
42
+ },
43
+ ];
44
+ ```
package/index.js ADDED
@@ -0,0 +1,195 @@
1
+ 'use strict';
2
+
3
+ // no-dynamic-step-id: step.run() first argument must be a static string literal.
4
+ const noDynamicStepId = {
5
+ meta: {
6
+ type: 'problem',
7
+ docs: { description: 'step.run() ID must be a static string literal' },
8
+ schema: [],
9
+ },
10
+ create(context) {
11
+ return {
12
+ CallExpression(node) {
13
+ const { callee } = node;
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
+ }
23
+ const id = node.arguments[0];
24
+ if (!id || id.type !== 'Literal' || typeof id.value !== 'string') {
25
+ context.report({
26
+ node: id || node,
27
+ message: 'step.run() ID must be a static string literal',
28
+ });
29
+ return;
30
+ }
31
+ // The runtime suffixes repeat occurrences of an ID with "#N" to give
32
+ // each loop iteration its own journal entry. Reserving "#" keeps an
33
+ // author-written ID from colliding with a generated one.
34
+ if (id.value.includes('#')) {
35
+ context.report({
36
+ node: id,
37
+ message: 'step.run() ID must not contain "#" (reserved separator)',
38
+ });
39
+ }
40
+ },
41
+ };
42
+ },
43
+ };
44
+
45
+ // no-sleep-in-step: sleep() and waitForEvent() must not be called inside step.run() callbacks.
46
+ const noSleepInStep = {
47
+ meta: {
48
+ type: 'problem',
49
+ docs: {
50
+ description:
51
+ 'sleep() and waitForEvent() must not appear inside step.run()',
52
+ },
53
+ schema: [],
54
+ },
55
+ create(context) {
56
+ // Counts nested step.run() CallExpression nodes we're currently inside.
57
+ let depth = 0;
58
+
59
+ function isStepRun(node) {
60
+ const { callee } = node;
61
+ return (
62
+ callee.type === 'MemberExpression' &&
63
+ callee.object.type === 'Identifier' &&
64
+ callee.object.name === 'step' &&
65
+ callee.property.type === 'Identifier' &&
66
+ callee.property.name === 'run'
67
+ );
68
+ }
69
+
70
+ return {
71
+ CallExpression(node) {
72
+ if (isStepRun(node)) {
73
+ depth++;
74
+ return;
75
+ }
76
+ if (depth > 0 && node.callee.type === 'Identifier') {
77
+ const name = node.callee.name;
78
+ if (name === 'sleep' || name === 'waitForEvent') {
79
+ context.report({
80
+ node,
81
+ message: `${name}() must not be called inside step.run()`,
82
+ });
83
+ }
84
+ }
85
+ },
86
+ 'CallExpression:exit'(node) {
87
+ if (isStepRun(node)) depth--;
88
+ },
89
+ };
90
+ },
91
+ };
92
+
93
+ // require-in-step: log(), now(), and fetch() must be called inside a step.run() callback.
94
+ const requireInStep = {
95
+ meta: {
96
+ type: 'problem',
97
+ docs: {
98
+ description: 'log(), now(), and fetch() must be called inside step.run()',
99
+ },
100
+ schema: [],
101
+ },
102
+ create(context) {
103
+ let depth = 0;
104
+
105
+ function isStepRun(node) {
106
+ const { callee } = node;
107
+ return (
108
+ callee.type === 'MemberExpression' &&
109
+ callee.object.type === 'Identifier' &&
110
+ callee.object.name === 'step' &&
111
+ callee.property.type === 'Identifier' &&
112
+ callee.property.name === 'run'
113
+ );
114
+ }
115
+
116
+ return {
117
+ CallExpression(node) {
118
+ if (isStepRun(node)) {
119
+ depth++;
120
+ return;
121
+ }
122
+ if (depth === 0 && node.callee.type === 'Identifier') {
123
+ const name = node.callee.name;
124
+ if (name === 'log' || name === 'now' || name === 'fetch') {
125
+ context.report({
126
+ node,
127
+ message: `${name}() must be called inside step.run()`,
128
+ });
129
+ }
130
+ }
131
+ },
132
+ 'CallExpression:exit'(node) {
133
+ if (isStepRun(node)) depth--;
134
+ },
135
+ };
136
+ },
137
+ };
138
+
139
+ // no-juno-sdk-import: flows and integrations must not import from juno:sdk.
140
+ //
141
+ // It has to catch two spellings, because it runs in two places. The server
142
+ // lints the *bundled* output, where esbuild has marked juno:sdk external and an
143
+ // import survives as require('juno:sdk'). An author's editor and `npm run lint`
144
+ // see the *source*, where it is still an import statement. Same rule, same
145
+ // message, both ends.
146
+ const MESSAGE =
147
+ 'Must not import from juno:sdk — all types are ambient globals declared in flow-api.d.ts / integration-api.d.ts';
148
+
149
+ const noJunoSdkImport = {
150
+ meta: {
151
+ type: 'problem',
152
+ docs: {
153
+ description:
154
+ 'Must not import from juno:sdk — all types are ambient globals',
155
+ },
156
+ schema: [],
157
+ },
158
+ create(context) {
159
+ function isSdk(node) {
160
+ return node && node.type === 'Literal' && node.value === 'juno:sdk';
161
+ }
162
+ return {
163
+ CallExpression(node) {
164
+ const isRequire =
165
+ node.callee.type === 'Identifier' && node.callee.name === 'require';
166
+ const isDynamicImport = node.callee.type === 'Import';
167
+ if (
168
+ (isRequire || isDynamicImport) &&
169
+ node.arguments.length === 1 &&
170
+ isSdk(node.arguments[0])
171
+ ) {
172
+ context.report({ node, message: MESSAGE });
173
+ }
174
+ },
175
+ ImportDeclaration(node) {
176
+ if (isSdk(node.source)) context.report({ node, message: MESSAGE });
177
+ },
178
+ ExportNamedDeclaration(node) {
179
+ if (isSdk(node.source)) context.report({ node, message: MESSAGE });
180
+ },
181
+ ExportAllDeclaration(node) {
182
+ if (isSdk(node.source)) context.report({ node, message: MESSAGE });
183
+ },
184
+ };
185
+ },
186
+ };
187
+
188
+ module.exports = {
189
+ rules: {
190
+ 'no-dynamic-step-id': noDynamicStepId,
191
+ 'no-sleep-in-step': noSleepInStep,
192
+ 'require-in-step': requireInStep,
193
+ 'no-juno-sdk-import': noJunoSdkImport,
194
+ },
195
+ };
package/package.json ADDED
@@ -0,0 +1,29 @@
1
+ {
2
+ "name": "@junoflow/eslint-plugin",
3
+ "version": "0.1.0",
4
+ "description": "ESLint rules for Juno flows and integrations — the same rules the server runs during verification.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/boivie/juno.git",
9
+ "directory": "tools/npm/eslint-plugin"
10
+ },
11
+ "type": "commonjs",
12
+ "main": "index.js",
13
+ "files": [
14
+ "index.js",
15
+ "README.md"
16
+ ],
17
+ "keywords": [
18
+ "eslint",
19
+ "eslintplugin",
20
+ "juno",
21
+ "junoflow"
22
+ ],
23
+ "peerDependencies": {
24
+ "eslint": ">=9"
25
+ },
26
+ "engines": {
27
+ "node": ">=20"
28
+ }
29
+ }