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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Testomat.io (JESUSMARIA.DESIGN sp. z o.o.)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,311 @@
1
- # Temporary Holding Version
1
+ # scripted-yaml
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ YAML files that carry small pieces of logic, and a TypeScript library that validates and loads them.
4
+
5
+ Use it where rules belong to the people who own them, not to the code: shop discounts, which parts
6
+ of a screen a user sees, how a game character's stats add up. The file stays readable YAML; the
7
+ logic is short formulas in a standard language (FEEL), marked so nobody mistakes them for text.
8
+
9
+ ```
10
+ npm install scripted-yaml
11
+ ```
12
+
13
+ Runs on Node 22 or newer and on Bun. A file that imports a `.ts` module with `$import` needs a
14
+ runtime that loads TypeScript itself: Bun, or Node 22.18 and newer.
15
+
16
+ **Load only files you trust.** `load` and `loadText` import the modules a file names with `$import`,
17
+ which runs their code. `validate` never does: it imports nothing and computes nothing.
18
+
19
+ ## What a file looks like
20
+
21
+ | You write | It means |
22
+ |---|---|
23
+ | `key:` | text or data; `{{ }}` inside text is a formula |
24
+ | `key!:` | the value is a formula, written in FEEL |
25
+ | `key!name:` | the value is handed to the application's function `name` |
26
+ | `$keyword:` | a word of the language: `$vars`, `$value`, `$if!`, `$unless!`, `$each!`, `$when`, `$functions`, `$import`, `$schema`, `$dsl`, `$extends`, `$tests` |
27
+
28
+ Formulas are FEEL, run by `feelin`. Text templates are read by `feelers`. YAML is read by `yaml`.
29
+ scripted-yaml has no parser of its own. [`docs/examples/`](https://github.com/DavertMik/scripted-yaml/tree/main/docs/examples) holds tested FEEL examples, including the common mistakes.
30
+
31
+ ## Examples
32
+
33
+ Each file below is in [`examples/`](https://github.com/DavertMik/scripted-yaml/tree/main/examples), and a test resolves it and checks the result shown.
34
+
35
+ ### Shop: discounts and shipping
36
+
37
+ ```yaml
38
+ $vars:
39
+ cart: { about: The order. Its subtotal is used here. }
40
+ customer: { about: The buyer. Past orders and tags. }
41
+
42
+ is_vip!: count(vars.customer.orders) >= 10 or "vip" in vars.customer.tags
43
+
44
+ discount:
45
+ loyalty!: if is_vip then vars.cart.subtotal * 0.05 else 0
46
+ volume!: if vars.cart.subtotal >= 200 then 15 else 0
47
+ $value!: max(loyalty, volume)
48
+ note: The bigger of the two discounts applies.
49
+
50
+ to_pay!: vars.cart.subtotal - discount
51
+
52
+ shipping:
53
+ - name: Standard
54
+ price!: if to_pay >= 50 then 0 else 4.90
55
+ - name: Express
56
+ price: 12.90
57
+ $if!: is_vip
58
+
59
+ message: You pay {{ to_pay }} and save {{ discount }}.
60
+ ```
61
+
62
+ With `cart: { subtotal: 240 }` and a customer tagged `vip`:
63
+
64
+ ```js
65
+ {
66
+ is_vip: true,
67
+ discount: { loyalty: 12, volume: 15, $value: 15, note: 'The bigger of the two discounts applies.' },
68
+ to_pay: 225,
69
+ shipping: [{ name: 'Standard', price: 0 }, { name: 'Express', price: 12.9 }],
70
+ message: 'You pay 225 and save 15.',
71
+ }
72
+ ```
73
+
74
+ `discount` is a map with a `$value`: a formula that reads `discount` gets 15, and the keys beside it
75
+ explain how. For a new customer with a cart of 30, `to_pay` is 30 and only Standard shipping is left, at 4.9.
76
+
77
+ ### UI: parts that show, hide and change
78
+
79
+ ```yaml
80
+ $vars:
81
+ user: { optional: true, about: The signed-in user. Null when signed out. }
82
+ plan: { default: free }
83
+ flags: { default: [] }
84
+
85
+ signed_in!: vars.user != null
86
+ is_admin!: if signed_in then vars.user.role = "admin" else false
87
+ paid!: vars.plan != "free"
88
+
89
+ header:
90
+ title: Dashboard
91
+ greeting!: if signed_in then "Welcome back, " + vars.user.name else "Welcome"
92
+
93
+ sidebar:
94
+ - label: Home
95
+ icon: home
96
+ - label: Reports
97
+ icon: chart
98
+ $if!: paid
99
+ - label: Upgrade
100
+ icon: star
101
+ action!js: openCheckout()
102
+ $unless!: paid
103
+ - label: Admin
104
+ icon: shield
105
+ $if!: is_admin
106
+ - $each!: vars.flags
107
+ $as: flag
108
+ label: Beta {{ flag }}
109
+ icon: flask
110
+
111
+ theme:
112
+ accent: blue
113
+ $when:
114
+ - $if!: paid
115
+ accent: gold
116
+ ```
117
+
118
+ Signed out, on the free plan, the result is:
119
+
120
+ ```js
121
+ {
122
+ signed_in: false, is_admin: false, paid: false,
123
+ header: { title: 'Dashboard', greeting: 'Welcome' },
124
+ sidebar: [
125
+ { label: 'Home', icon: 'home' },
126
+ { label: 'Upgrade', icon: 'star', action: Script { js: 'openCheckout()' } },
127
+ ],
128
+ theme: { accent: 'blue' },
129
+ }
130
+ ```
131
+
132
+ For an admin called Ada on the `team` plan with the flag `charts`, the sidebar is Home, Reports,
133
+ Admin and "Beta charts", the greeting is "Welcome back, Ada", and the accent is gold.
134
+
135
+ `action!js:` is a marker. The library does not know JavaScript: it hands `openCheckout()` to the
136
+ function the application registered for `js`, and puts whatever that returns in its place.
137
+
138
+ ### Game: an RPG character sheet
139
+
140
+ ```yaml
141
+ $vars:
142
+ hero: { about: "Name, class, level and the seven base attributes." }
143
+ gear: { default: [], about: "Items worn. Each adds an amount to one stat." }
144
+
145
+ classes:
146
+ knight: { hp_per_level: 12, sp_per_level: 0, magic: none }
147
+ archer: { hp_per_level: 8, sp_per_level: 2, magic: intellect }
148
+ cleric: { hp_per_level: 7, sp_per_level: 5, magic: personality }
149
+ sorcerer: { hp_per_level: 5, sp_per_level: 6, magic: intellect }
150
+
151
+ # The row of `classes` for this hero: `get value` looks a key up by a name held in a variable.
152
+ hero_class!: get value(classes, vars.hero.class)
153
+
154
+ $functions:
155
+ from_gear(wanted)!: sum(append(vars.gear[stat = wanted].amount, 0))
156
+ bonus(score)!: floor((score - 10) / 3)
157
+
158
+ # Base value plus what the gear adds.
159
+ attributes:
160
+ might!: vars.hero.might + from_gear("might")
161
+ intellect!: vars.hero.intellect + from_gear("intellect")
162
+ personality!: vars.hero.personality + from_gear("personality")
163
+ endurance!: vars.hero.endurance + from_gear("endurance")
164
+ accuracy!: vars.hero.accuracy + from_gear("accuracy")
165
+ speed!: vars.hero.speed + from_gear("speed")
166
+ luck!: vars.hero.luck + from_gear("luck")
167
+
168
+ casting!: if hero_class.magic = "personality" then attributes.personality else attributes.intellect
169
+
170
+ stats:
171
+ hit_points!: (hero_class.hp_per_level + bonus(attributes.endurance)) * vars.hero.level
172
+ spell_points!: if hero_class.magic = "none" then 0 else (hero_class.sp_per_level + bonus(casting)) * vars.hero.level
173
+ armor_class!: from_gear("armor") + bonus(attributes.speed)
174
+ to_hit!: vars.hero.level + bonus(attributes.accuracy)
175
+ damage!: max(1, from_gear("damage") + bonus(attributes.might))
176
+
177
+ resistances:
178
+ fire!: from_gear("fire") + bonus(attributes.luck)
179
+ water!: from_gear("water") + bonus(attributes.luck)
180
+ mind!: from_gear("mind") + bonus(attributes.personality)
181
+
182
+ rank!: if vars.hero.level >= 10 then "Veteran" else "Novice"
183
+ summary: "{{ vars.hero.name }}, {{ rank }} {{ vars.hero.class }} of level {{ vars.hero.level }}"
184
+
185
+ skills:
186
+ - name: Strike
187
+ damage!: stats.damage
188
+ - name: Shield Wall
189
+ $if!: vars.hero.class = "knight" and vars.hero.level >= 5
190
+ - name: Aimed Shot
191
+ to_hit!: stats.to_hit + 4
192
+ $if!: vars.hero.class = "archer"
193
+ - name: Heal
194
+ restores!: 5 + bonus(attributes.personality) * 2
195
+ cost: 3
196
+ $if!: vars.hero.class = "cleric"
197
+ - name: Fireball
198
+ damage!: bonus(attributes.intellect) * vars.hero.level
199
+ cost: 8
200
+ $if!: vars.hero.class = "sorcerer" and stats.spell_points >= 8
201
+ - name: Lucky Dodge
202
+ $if!: attributes.luck >= 16
203
+ ```
204
+
205
+ Seven attributes in the style of classic party role-playing games, each raised by gear; hit points,
206
+ spell points, armor class and resistances worked out from them; skills that unlock by class and level.
207
+
208
+ For Brom, a level 7 knight (might 18, endurance 16, luck 9) with an iron sword (+4 damage), chain
209
+ mail (+6 armor) and a ring of might (+3):
210
+
211
+ ```js
212
+ {
213
+ hero_class: { hp_per_level: 12, sp_per_level: 0, magic: 'none' },
214
+ attributes: { might: 21, intellect: 8, personality: 10, endurance: 16, accuracy: 13, speed: 11, luck: 9 },
215
+ casting: 8,
216
+ stats: { hit_points: 98, spell_points: 0, armor_class: 6, to_hit: 8, damage: 7 },
217
+ resistances: { fire: -1, water: -1, mind: 0 },
218
+ rank: 'Novice',
219
+ summary: 'Brom, Novice knight of level 7',
220
+ skills: [{ name: 'Strike', damage: 7 }, { name: 'Shield Wall' }],
221
+ }
222
+ ```
223
+
224
+ Ilse, a level 12 sorcerer with intellect 22 and luck 17, has 60 hit points and 120 spell points, and
225
+ her skills are Strike, Fireball (damage 48, cost 8) and Lucky Dodge. Tam, a level 4 cleric with
226
+ personality 19, gets Heal, which restores 11.
227
+
228
+ Order in the file does not matter: `stats.hit_points` reads `hero_class`, which reads `classes`, and
229
+ `attributes.endurance`, which calls `from_gear`. Each is computed when first needed.
230
+
231
+ ## The library
232
+
233
+ ```ts
234
+ import { ScriptedYaml } from 'scripted-yaml';
235
+
236
+ class Script {
237
+ constructor(readonly js: string) {}
238
+ }
239
+
240
+ // The only option: one function per marker. `action!js: openCheckout()` calls `js("openCheckout()")`.
241
+ const scripted = new ScriptedYaml({
242
+ markers: { js: (source: string) => new Script(source) },
243
+ });
244
+
245
+ const problems = await scripted.validate('ui.yml'); // checks the file; runs nothing
246
+ for (const problem of problems) console.log(problem.severity, problem.toString());
247
+ // error ui.yml:10 paid! unknown name "var"; did you mean "vars"?
248
+
249
+ const document = await scripted.load('ui.yml'); // validates, applies markers; computes nothing
250
+ document.data.paid.source; // 'vars.plan != "free"' (a Formula)
251
+ document.data.paid.reads; // ["vars.plan"]
252
+ document.data.sidebar[2].action; // Script { js: "openCheckout()" }
253
+
254
+ const result = await document.resolve({ vars: { plan: 'team' } }); // all variables in, all values out
255
+ result.paid; // true
256
+ result.theme.accent; // "gold"
257
+ ```
258
+
259
+ - `validate(path)` returns `Problem`s: `file`, `line`, `column`, `key`, `message`, `severity`. It needs no values. Where files are only checked, markers may be given by name: `new ScriptedYaml({ markers: ['js'] })`.
260
+ - `load(path)` validates first and throws `ValidationFailed` (with `.problems`) on an error. Then `$extends` is applied, each `$import` is loaded and each marker function is called once. Formulas stay formulas.
261
+ - `validateText(text, { file })` and `loadText(textOrData, { file })` do the same for text that is not in a file: a form field, a database row, the front matter of a Markdown file. `file` names it in the problems and is where its `$dsl`, `$extends` and `$import` paths start from.
262
+ - `document.resolve({ vars })` returns plain data: every formula computed, `$if` / `$unless` / `$each` / `$when` applied. It throws `ResolveFailed` when a required variable is missing, a formula gives a FEEL warning, or a rule of the schema is broken.
263
+ - `document.test()` runs the file's `$tests` and returns one `TestResult` (`about`, `passed`, `failures`) per test.
264
+ - `document.variables` lists what the file declares under `$vars`.
265
+
266
+ ## The command line
267
+
268
+ ```
269
+ scripted-yaml validate <file>... [--markers sh,mdq]
270
+ scripted-yaml parse <file> [--var NAME=value]... [--vars file.json] [--markers sh,mdq]
271
+ ```
272
+
273
+ `validate` prints one line per problem and exits with 1 when there is an error. `parse` prints the
274
+ resolved file as JSON; a marked value is shown as `{ "marker": "sh", "source": "…" }`. A `.md` file is
275
+ read by its front matter.
276
+
277
+ ```
278
+ $ scripted-yaml validate ui.yml --markers js
279
+ ok ui.yml
280
+ ```
281
+
282
+ ## Rules worth knowing
283
+
284
+ - A file is self-contained. It reaches outside only through `$dsl`, `$extends` and `$import`, by path.
285
+ - Functions a formula calls come from FEEL, from `$functions`, or from `$import` (`.ts`, `.js`, `.yml`, `.yaml`, `.md`). They are synchronous.
286
+ - Nothing is computed until something reads it. Keys are definitions, not steps.
287
+ - A marker's value that a formula reads is taken through its `toString()`; `"1"` is true, `"0"` is false. Once read, the result holds that value; a value nothing reads stays as the marker function returned it.
288
+ - Validation checks a formula's syntax and that each name it uses is defined; it computes nothing. Inside `[ ]` an unknown name is taken as a field of the item.
289
+ - Any warning of `feelin` is an error with the file and key, except reading a field of null.
290
+ - `$if!` and `$unless!` must give true or false: null is an error, because FEEL has no truthiness.
291
+
292
+ ## In the repository
293
+
294
+ Source: <https://github.com/DavertMik/scripted-yaml>
295
+
296
+ | Path | What |
297
+ |---|---|
298
+ | `src/` | the library and the command line |
299
+ | `test/scripted-yaml.test.ts` | the contract |
300
+ | `test/edge.test.ts`, `test/files.test.ts` | edge cases; `$extends`, `$schema`, `$dsl`, `$tests`; the files of `examples/` loaded whole |
301
+ | `test/parsers/` | five small applications built on the library: pipeline, router, markdown, ui, shop |
302
+ | `examples/` | files in the format: the three above, a longer shop, a router, pipelines, Markdown with front matter |
303
+ | `skills/scripted-yaml/SKILL.md` | a skill that teaches an agent to write and check these files |
304
+
305
+ ```
306
+ bun test # everything; test/package.test.ts builds dist/ first
307
+ bun run typecheck
308
+ bun run build # dist/index.js, dist/cli.js and the type declarations
309
+ ```
310
+
311
+ [`SPEC.md`](https://github.com/DavertMik/scripted-yaml/blob/main/SPEC.md) is the full specification. Licence: MIT.
@@ -0,0 +1,7 @@
1
+ /** Tells whether a name is a function FEEL ships. `feelin` does not export its list, so it is asked. */
2
+ export declare class Builtins {
3
+ private static readonly known;
4
+ static has(name: string): boolean;
5
+ /** Calls `name()` with nothing: `feelin` warns NO_FUNCTION_FOUND for a name it does not ship. */
6
+ private static ask;
7
+ }
@@ -0,0 +1,41 @@
1
+ import type { Problems } from './problem.js';
2
+ import { Source } from './source.js';
3
+ /** Validates one source: SPEC 7.2. It runs nothing: no marker function, no formula, no import. */
4
+ export declare class Checker {
5
+ private readonly source;
6
+ private readonly markers;
7
+ private readonly problems;
8
+ private static readonly structure;
9
+ private static readonly conditions;
10
+ private static readonly patching;
11
+ private readonly scope;
12
+ /** Every node that holds a formula or a text template. */
13
+ private readonly computed;
14
+ private readonly undeclared;
15
+ constructor(source: Source, markers: string[], problems: Problems);
16
+ run(): void;
17
+ private checkMap;
18
+ /** True when the `$` key is a word of the language that may stand here. */
19
+ private keyword;
20
+ private when;
21
+ private checkEntry;
22
+ private checkValue;
23
+ private formula;
24
+ private expression;
25
+ /** A function may not have the name of a FEEL built-in, and a key may not have the name of a function. */
26
+ private checkFunctionNames;
27
+ private at;
28
+ private checkNames;
29
+ /** Reports what is wrong with one name. False when it names nothing; a Reach when it names a key. */
30
+ private checkRef;
31
+ /**
32
+ * One formula cannot read a node as a value and also a key beside that value: FEEL is handed one
33
+ * thing under one name. So `local` (its $value) and `local.message` cannot be in the same formula.
34
+ */
35
+ private checkOverlap;
36
+ /** The computed nodes a node needs before it can be computed. */
37
+ private needs;
38
+ /** Every computed node that reading a node asks for. */
39
+ private under;
40
+ private checkCycles;
41
+ }
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};