scripted-yaml 0.0.0-stage → 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.
@@ -0,0 +1,297 @@
1
+ ---
2
+ name: scripted-yaml
3
+ description: Write and check scripted-yaml files - YAML with marked formulas (`key!:` in FEEL), `{{ }}` in text, application markers (`run!sh:`) and `$` keywords ($vars, $value, $functions, $import, $if, $each, $when, $schema, $dsl, $extends, $tests). Use when creating, editing, reviewing or debugging such a file (pipelines, shop rules, routers, UI descriptions, Markdown front matter), or when `scripted-yaml validate` reports a problem.
4
+ ---
5
+
6
+ # scripted-yaml
7
+
8
+ A scripted-yaml file is a YAML file. Four markers say what is not plain data:
9
+
10
+ | You write | It means |
11
+ |---|---|
12
+ | `key: text` | data; in text, each `{{ formula }}` is computed |
13
+ | `key!: formula` | the value is one FEEL formula |
14
+ | `key!name: value` | the value goes, as written, to the application's function `name` (`sh`, `mdq`: the application chooses) |
15
+ | `$keyword:` | a word of the language, not data |
16
+
17
+ Every example below is a file in `examples/` beside this skill, checked by the project's tests.
18
+ After writing or changing a file, **always run `scripted-yaml validate`** (last section).
19
+
20
+ ```yaml
21
+ $vars:
22
+ STAGING_URL: { optional: true, about: Where the app under test runs. }
23
+ BRANCH: { default: main }
24
+ CI: { optional: true }
25
+
26
+ prerequisites:
27
+ staging:
28
+ $value!: vars.STAGING_URL != null
29
+ message: No staging URL. Set STAGING_URL.
30
+ browser:
31
+ $value!sh: ls ~/.cache/ms-playwright | grep -q chromium
32
+ message: No browser installed.
33
+
34
+ timeout!: if vars.CI != null then "30m" else "10m"
35
+
36
+ stages:
37
+ - id: plan
38
+ title: Plan for {{ vars.BRANCH }}
39
+ when!: prerequisites.staging
40
+ task: Write a test plan for {{ vars.STAGING_URL }} in plan.md.
41
+
42
+ - id: explore
43
+ title: Browser testing
44
+ when!: stages.plan.when and prerequisites.browser
45
+ run!sh: npx explorbot test plan.md
46
+ ```
47
+
48
+ - **Names are paths, spelled as in the file**: `prerequisites.staging`, `vars.BRANCH`. A list item is
49
+ named by its `id`: `stages.plan.when`. A bare name is looked up among sibling keys, then each
50
+ enclosing map, then the top of the file. Keys a formula reads must be identifiers: `test_command`.
51
+ - **`$vars`** declares the inputs; read them as `vars.NAME`. Required unless `optional: true` or a
52
+ `default`. Unset or empty is null. Values are not converted: text stays text.
53
+ - **`$value`** makes a map a value: `prerequisites.staging` is the boolean, `prerequisites.staging.message`
54
+ the text. One formula cannot read both of the same map.
55
+ - **Keys are definitions, not steps.** Order means nothing; a key is computed when first read, once.
56
+ - **A marked value** (`!sh`) is never looked into. A formula that reads one gets its `toString()`:
57
+ `"1"` is true, `"0"` is false. Do not put `{{ }}` in it: it is not filled in.
58
+
59
+ ## FEEL in ten lines
60
+
61
+ ```
62
+ vars.method = "GET" equals is ONE =; text is in double quotes
63
+ a and b a or b not(a) not is a function
64
+ vars.NAME != null "is set"; unset or empty variables are null
65
+ if a then b else c else is required; no ?: ternary
66
+ x in ["a", "b"] day between 1 and 5 one of; within
67
+ cart.items[price > 10] pick items; a bare name is the item's field
68
+ cart.items.price one field of every item
69
+ count(list) sum(list) min(list) lists count from 1: list[1], list[-1]
70
+ for item in list return item.price * 2 a loop gives one result per item
71
+ some item in list satisfies item.price > 5 yes or no over a list (also: every)
72
+ ```
73
+
74
+ Text functions: `starts with(a, b)`, `upper case(a)`, `string join(list, ", ")`, `string(number)`.
75
+
76
+ ## Mistakes
77
+
78
+ ```yaml
79
+ role: admin
80
+ ok: true
81
+ items: [a, b]
82
+ price: 5
83
+ test-command: npm test
84
+
85
+ same!: role == "admin"
86
+ allowed!: role in ["admin", "owner"] and ok
87
+ blocked!: not ok
88
+ first!: items[0]
89
+ label!: prise * 2
90
+ ready!: test-command != null
91
+ ci!: vars.CI != null
92
+ ```
93
+
94
+ `scripted-yaml validate mistakes.yml` prints:
95
+
96
+ ```
97
+ error mistakes.yml:9 blocked! unknown name "not ok"; for text, remove the "!"
98
+ error mistakes.yml:11 label! unknown name "prise"; did you mean "price"?
99
+ error mistakes.yml:12 ready! unknown name "test"; a key with a dash cannot be read by a formula: name it with an underscore
100
+ error mistakes.yml:12 ready! unknown name "command"; a key with a dash cannot be read by a formula: name it with an underscore
101
+ warning mistakes.yml:13 ci! the variable "CI" is not declared in $vars; it is null unless the application passes it
102
+ ```
103
+
104
+ Right: `role = "admin"`, `(role in ["admin", "owner"]) and ok`, `not(ok)`, `items[1]`, `test_command`,
105
+ and `CI: { optional: true }` under `$vars` (`examples/fixed.yml`).
106
+
107
+ Validation checks the syntax of a formula and that every name in it is defined; nothing more. It
108
+ does not report `same`, `allowed` and `first` above, nor these; they are wrong only when computed:
109
+
110
+ - **Equals is ONE `=`**; `x in list and y` is read as `x in (list and y)`: put brackets around the `in` test; lists count from 1, there is no `[0]`.
111
+ - **No truthiness.** `vars.NAME and ok` is null. Write `vars.NAME != null and ok`. `$if!` refuses null.
112
+ - **Text plus number is an error.** Write `"Total: " + string(n)`.
113
+ - **`sum` of an empty list is null.** Write `sum(append(list, 0))`.
114
+ - **A filter must be a comparison**: `[on_sale = false]`, not `[not(on_sale)]`.
115
+ - **A function parameter must not be named like a field of the items it filters.** A name a formula makes (a loop variable, a parameter, an entry of `{ }`) is its own in the whole formula: do not also read a key of that name there.
116
+ - In YAML, a formula that starts with `"`, `[` or `{`, or holds `: ` or ` #`, goes in single quotes:
117
+ `label!: '"Price: " + string(price)'`. Quote a text value that starts with `{{`.
118
+
119
+ ## Functions, structure, tests
120
+
121
+ ```yaml
122
+ $vars:
123
+ cart: {}
124
+ customer: {}
125
+ cities: { default: [] }
126
+
127
+ $functions:
128
+ inCart(wanted)!: vars.cart.items[category = wanted]
129
+ total(items)!: sum(append(items.price, 0))
130
+
131
+ is_vip!: count(vars.customer.orders) >= 10 or "vip" in vars.customer.tags
132
+
133
+ discount:
134
+ loyalty!: if is_vip then vars.cart.subtotal * 0.05 else 0
135
+ books!: if count(inCart("books")) >= 3 then total(inCart("books")) * 0.1 else 0
136
+ $value!: max(loyalty, books)
137
+ note: The bigger of the two discounts applies.
138
+
139
+ to_pay!: vars.cart.subtotal - discount
140
+
141
+ shipping:
142
+ - name: Standard
143
+ price!: if to_pay >= 50 then 0 else 4.90
144
+ - name: Express
145
+ price: 12.90
146
+ $if!: is_vip
147
+ - name: Economy
148
+ price: 2.50
149
+ $unless!: is_vip
150
+ - $each!: vars.cities
151
+ $as: city
152
+ name: Pickup in {{ city }}
153
+ price: 0
154
+ $if!: city != "Paris"
155
+
156
+ checkout:
157
+ payment_methods: [card, paypal]
158
+ $when:
159
+ - $if!: to_pay > 1000
160
+ payment_methods: [card, bank_transfer]
161
+ note: Orders over 1000 need a card or a bank transfer.
162
+ - $else:
163
+ note: ''
164
+
165
+ $tests:
166
+ - about: A regular customer with three books
167
+ vars:
168
+ customer: { orders: [], tags: [vip] }
169
+ cities: [Lyon, Paris]
170
+ cart: { subtotal: 60, items: [{ category: books, price: 10 }, { category: books, price: 20 }, { category: books, price: 30 }] }
171
+ expect:
172
+ discount: 6
173
+ discount.note: The bigger of the two discounts applies.
174
+ to_pay: 54
175
+ shipping.name: [Standard, Express, Pickup in Lyon]
176
+ checkout.payment_methods: [card, paypal]
177
+ ```
178
+
179
+ - **`$functions`**: `name(parameters)!: formula`. Not the name of a FEEL built-in or of a key.
180
+ - **`$if!` / `$unless!`** keep or drop the list item or map they sit in. They must give true or false.
181
+ - **`$each!`** repeats a list item per value, named by `$as`; `$if!` beside it is checked per value.
182
+ - **`$when`** changes keys of its map: every matching case applies, in order; `$else` when none did.
183
+ - **`$tests`**: `vars` in, `expect` out, as paths. The application runs them with `document.test()`.
184
+
185
+ ## `$import`: functions and data from other files
186
+
187
+ ```yaml
188
+ $import:
189
+ ./helpers.js: [slug] # names the module exports
190
+ ./settings.yml: settings # one name for the whole file
191
+ ./handbook.md: handbook # a function: selector in, Markdown out
192
+
193
+ title: Summer Sale
194
+ path!: '"/pages/" + slug(title)'
195
+ free_from: Free shipping from {{ settings.free_shipping_from }} {{ settings.currency }}
196
+ releases!: handbook("section(/^Releases/) paragraph")
197
+ ```
198
+
199
+ `scripted-yaml parse import.yml` gives `path` as `"/pages/summer-sale"`, `free_from` as
200
+ `"Free shipping from 50 EUR"` and `releases` as `"We release on Tuesdays.\n"`.
201
+
202
+ A formula calls only FEEL built-ins, `$functions` and imported names. Imported functions are
203
+ synchronous. Paths are relative to the file. In an `mdq` selector inside a formula, match text
204
+ with a regular expression (`section(/^Releases/)`): double quotes would end the FEEL text.
205
+
206
+ ## `$schema` and `$dsl`: which keys a file has
207
+
208
+ ```yaml
209
+ $schema:
210
+ required: [name, agents*:Agent]
211
+ optional: [target:Target, lead]
212
+ Agent:
213
+ key: name
214
+ required: [name, role:Role]
215
+ optional: [about, tools*]
216
+ Role: [reviewer, tester]
217
+ Target: [issue, pr]
218
+
219
+ name: qa-team
220
+ target: pr
221
+ agents:
222
+ - name: ann
223
+ role: reviewer
224
+ tools: [git, gh]
225
+ - name: raj
226
+ role: tester
227
+ about: Runs the browser tests.
228
+
229
+ lead!: agents.ann.role
230
+ ```
231
+
232
+ `field` is text, `field*` is many (a list, or a map keyed by name), `field:Type` has a named shape
233
+ or is one of a set of words. `key:` names the field that identifies an item (`id` when omitted).
234
+ A missing or wrong field is an error; a key that is not listed is a warning
235
+ (`examples/team-wrong.yml`):
236
+
237
+ ```
238
+ error team-wrong.yml:10 target "branch" is not one of: issue, pr
239
+ warning team-wrong.yml:11 colour "colour" is not a field of the schema
240
+ error team-wrong.yml:13 agents[1] missing required field "role"
241
+ error team-wrong.yml:15 agents[2].role "manager" is not one of: reviewer, tester
242
+ ```
243
+
244
+ When many files share a schema, it lives in its own file and each file starts with
245
+ `$dsl: ./pipeline.dsl.yml`. A DSL only checks: defaults belong in the file's own `$vars`.
246
+
247
+ ## `$extends`: a patch of another file
248
+
249
+ The base, `examples/base.yml`, has the stages `lint`, `test` (with `when!` and a `task`) and `report`. The patch:
250
+
251
+ ```yaml
252
+ $extends: ./base.yml
253
+
254
+ $vars:
255
+ RELEASE: { optional: true }
256
+
257
+ $replace:
258
+ name: release-checks
259
+
260
+ stages:
261
+ $before:
262
+ install:
263
+ title: Install
264
+ run!sh: npm ci
265
+
266
+ test:
267
+ $replace:
268
+ when!: base and vars.RELEASE != null
269
+ task:
270
+ $after: Fail on the first broken test.
271
+ $after:
272
+ coverage:
273
+ title: Coverage
274
+ run!sh: npm run coverage
275
+
276
+ $remove: [report]
277
+ ```
278
+
279
+ The result has the stages `install, lint, test, coverage`. Every change says what it does:
280
+ `$replace` overwrites fields that exist; `$before` / `$after` add items to a list, beside one item,
281
+ or text to a text field; `$add` adds entries to a map; `$remove` drops entries; `base` is the
282
+ inherited value. A plain field in a patch is an error, and so is a key the base does not have.
283
+
284
+ ## Checking a file
285
+
286
+ ```
287
+ scripted-yaml validate <file>... [--markers sh,mdq]
288
+ scripted-yaml parse <file> [--var NAME=value]... [--vars file.json] [--markers sh,mdq]
289
+ ```
290
+
291
+ 1. `validate` prints `ok`, or one line per problem: severity, `file:line`, key, message. The exit
292
+ code is 1 when there is an error. Name the markers the files use: `--markers sh`. A `.md` file
293
+ is checked by its front matter.
294
+ 2. Fix every error. Fix warnings too, unless the variable really comes from outside undeclared.
295
+ 3. `parse` prints the file as JSON with every formula computed, for the variables you pass. Use it
296
+ to see that conditions give true or false, not null. A marked value shows as
297
+ `{ "marker": "sh", "source": "…" }`; a formula that reads one sees its source text there.
@@ -0,0 +1,16 @@
1
+ name: checks
2
+ $vars:
3
+ FAST: { optional: true }
4
+
5
+ stages:
6
+ - id: lint
7
+ title: Lint
8
+ run!sh: npm run lint
9
+ - id: test
10
+ title: Tests
11
+ when!: vars.FAST = null
12
+ task: Run the whole suite.
13
+ run!sh: npm test
14
+ - id: report
15
+ title: Report
16
+ task: Summarise the results.
@@ -0,0 +1,16 @@
1
+ $vars:
2
+ CI: { optional: true }
3
+
4
+ role: admin
5
+ ok: true
6
+ items: [a, b]
7
+ price: 5
8
+ test_command: npm test
9
+
10
+ same!: role = "admin"
11
+ allowed!: (role in ["admin", "owner"]) and ok
12
+ blocked!: not(ok)
13
+ first!: items[1]
14
+ label!: '"Price: " + string(price * 2)'
15
+ ready!: test_command != null
16
+ ci!: vars.CI != null
@@ -0,0 +1,7 @@
1
+ # Handbook
2
+
3
+ How we work.
4
+
5
+ ## Releases
6
+
7
+ We release on Tuesdays.
@@ -0,0 +1,8 @@
1
+ /** Functions a file imports with $import. Synchronous: a formula cannot wait for a promise. */
2
+ export class Helpers {
3
+ static slug(text) {
4
+ return text.toLowerCase().replaceAll(' ', '-');
5
+ }
6
+ }
7
+
8
+ export const slug = Helpers.slug;
@@ -0,0 +1,9 @@
1
+ $import:
2
+ ./helpers.js: [slug] # names the module exports
3
+ ./settings.yml: settings # one name for the whole file
4
+ ./handbook.md: handbook # a function: selector in, Markdown out
5
+
6
+ title: Summer Sale
7
+ path!: '"/pages/" + slug(title)'
8
+ free_from: Free shipping from {{ settings.free_shipping_from }} {{ settings.currency }}
9
+ releases!: handbook("section(/^Releases/) paragraph")
@@ -0,0 +1,13 @@
1
+ role: admin
2
+ ok: true
3
+ items: [a, b]
4
+ price: 5
5
+ test-command: npm test
6
+
7
+ same!: role == "admin"
8
+ allowed!: role in ["admin", "owner"] and ok
9
+ blocked!: not ok
10
+ first!: items[0]
11
+ label!: prise * 2
12
+ ready!: test-command != null
13
+ ci!: vars.CI != null
@@ -0,0 +1,25 @@
1
+ $extends: ./base.yml
2
+
3
+ $vars:
4
+ RELEASE: { optional: true }
5
+
6
+ $replace:
7
+ name: release-checks
8
+
9
+ stages:
10
+ $before:
11
+ install:
12
+ title: Install
13
+ run!sh: npm ci
14
+
15
+ test:
16
+ $replace:
17
+ when!: base and vars.RELEASE != null
18
+ task:
19
+ $after: Fail on the first broken test.
20
+ $after:
21
+ coverage:
22
+ title: Coverage
23
+ run!sh: npm run coverage
24
+
25
+ $remove: [report]
@@ -0,0 +1,25 @@
1
+ $vars:
2
+ STAGING_URL: { optional: true, about: Where the app under test runs. }
3
+ BRANCH: { default: main }
4
+ CI: { optional: true }
5
+
6
+ prerequisites:
7
+ staging:
8
+ $value!: vars.STAGING_URL != null
9
+ message: No staging URL. Set STAGING_URL.
10
+ browser:
11
+ $value!sh: ls ~/.cache/ms-playwright | grep -q chromium
12
+ message: No browser installed.
13
+
14
+ timeout!: if vars.CI != null then "30m" else "10m"
15
+
16
+ stages:
17
+ - id: plan
18
+ title: Plan for {{ vars.BRANCH }}
19
+ when!: prerequisites.staging
20
+ task: Write a test plan for {{ vars.STAGING_URL }} in plan.md.
21
+
22
+ - id: explore
23
+ title: Browser testing
24
+ when!: stages.plan.when and prerequisites.browser
25
+ run!sh: npx explorbot test plan.md
@@ -0,0 +1,2 @@
1
+ currency: EUR
2
+ free_shipping_from: 50
@@ -0,0 +1,55 @@
1
+ $vars:
2
+ cart: {}
3
+ customer: {}
4
+ cities: { default: [] }
5
+
6
+ $functions:
7
+ inCart(wanted)!: vars.cart.items[category = wanted]
8
+ total(items)!: sum(append(items.price, 0))
9
+
10
+ is_vip!: count(vars.customer.orders) >= 10 or "vip" in vars.customer.tags
11
+
12
+ discount:
13
+ loyalty!: if is_vip then vars.cart.subtotal * 0.05 else 0
14
+ books!: if count(inCart("books")) >= 3 then total(inCart("books")) * 0.1 else 0
15
+ $value!: max(loyalty, books)
16
+ note: The bigger of the two discounts applies.
17
+
18
+ to_pay!: vars.cart.subtotal - discount
19
+
20
+ shipping:
21
+ - name: Standard
22
+ price!: if to_pay >= 50 then 0 else 4.90
23
+ - name: Express
24
+ price: 12.90
25
+ $if!: is_vip
26
+ - name: Economy
27
+ price: 2.50
28
+ $unless!: is_vip
29
+ - $each!: vars.cities
30
+ $as: city
31
+ name: Pickup in {{ city }}
32
+ price: 0
33
+ $if!: city != "Paris"
34
+
35
+ checkout:
36
+ payment_methods: [card, paypal]
37
+ $when:
38
+ - $if!: to_pay > 1000
39
+ payment_methods: [card, bank_transfer]
40
+ note: Orders over 1000 need a card or a bank transfer.
41
+ - $else:
42
+ note: ''
43
+
44
+ $tests:
45
+ - about: A regular customer with three books
46
+ vars:
47
+ customer: { orders: [], tags: [vip] }
48
+ cities: [Lyon, Paris]
49
+ cart: { subtotal: 60, items: [{ category: books, price: 10 }, { category: books, price: 20 }, { category: books, price: 30 }] }
50
+ expect:
51
+ discount: 6
52
+ discount.note: The bigger of the two discounts applies.
53
+ to_pay: 54
54
+ shipping.name: [Standard, Express, Pickup in Lyon]
55
+ checkout.payment_methods: [card, paypal]
@@ -0,0 +1,15 @@
1
+ $schema:
2
+ required: [name, agents*:Agent]
3
+ optional: [target:Target]
4
+ Agent:
5
+ required: [name, role:Role]
6
+ Role: [reviewer, tester]
7
+ Target: [issue, pr]
8
+
9
+ name: qa-team
10
+ target: branch
11
+ colour: red
12
+ agents:
13
+ - name: ann
14
+ - name: raj
15
+ role: manager
@@ -0,0 +1,21 @@
1
+ $schema:
2
+ required: [name, agents*:Agent]
3
+ optional: [target:Target, lead]
4
+ Agent:
5
+ key: name
6
+ required: [name, role:Role]
7
+ optional: [about, tools*]
8
+ Role: [reviewer, tester]
9
+ Target: [issue, pr]
10
+
11
+ name: qa-team
12
+ target: pr
13
+ agents:
14
+ - name: ann
15
+ role: reviewer
16
+ tools: [git, gh]
17
+ - name: raj
18
+ role: tester
19
+ about: Runs the browser tests.
20
+
21
+ lead!: agents.ann.role