@words-lang/parser 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 (41) hide show
  1. package/dist/analyser/analyser.d.ts +106 -0
  2. package/dist/analyser/analyser.d.ts.map +1 -0
  3. package/dist/analyser/analyser.js +291 -0
  4. package/dist/analyser/analyser.js.map +1 -0
  5. package/dist/analyser/diagnostics.d.ts +166 -0
  6. package/dist/analyser/diagnostics.d.ts.map +1 -0
  7. package/dist/analyser/diagnostics.js +139 -0
  8. package/dist/analyser/diagnostics.js.map +1 -0
  9. package/dist/analyser/workspace.d.ts +198 -0
  10. package/dist/analyser/workspace.d.ts.map +1 -0
  11. package/dist/analyser/workspace.js +403 -0
  12. package/dist/analyser/workspace.js.map +1 -0
  13. package/dist/index.d.ts +8 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +31 -0
  16. package/dist/index.js.map +1 -0
  17. package/dist/lexer/lexer.d.ts +120 -0
  18. package/dist/lexer/lexer.d.ts.map +1 -0
  19. package/dist/lexer/lexer.js +365 -0
  20. package/dist/lexer/lexer.js.map +1 -0
  21. package/dist/lexer/token.d.ts +247 -0
  22. package/dist/lexer/token.d.ts.map +1 -0
  23. package/dist/lexer/token.js +250 -0
  24. package/dist/lexer/token.js.map +1 -0
  25. package/dist/parser/ast.d.ts +685 -0
  26. package/dist/parser/ast.d.ts.map +1 -0
  27. package/dist/parser/ast.js +3 -0
  28. package/dist/parser/ast.js.map +1 -0
  29. package/dist/parser/parser.d.ts +411 -0
  30. package/dist/parser/parser.d.ts.map +1 -0
  31. package/dist/parser/parser.js +1600 -0
  32. package/dist/parser/parser.js.map +1 -0
  33. package/package.json +23 -0
  34. package/src/analyser/analyser.ts +403 -0
  35. package/src/analyser/diagnostics.ts +232 -0
  36. package/src/analyser/workspace.ts +457 -0
  37. package/src/index.ts +7 -0
  38. package/src/lexer/lexer.ts +379 -0
  39. package/src/lexer/token.ts +331 -0
  40. package/src/parser/ast.ts +798 -0
  41. package/src/parser/parser.ts +1815 -0
@@ -0,0 +1,685 @@
1
+ import { Token } from '../lexer/token';
2
+ /**
3
+ * Every AST node extends BaseNode.
4
+ * The `kind` discriminant lets TypeScript narrow union types safely.
5
+ * The `token` is the first token that produced this node — used by the
6
+ * analyser to report diagnostics at the correct source location, and by
7
+ * the LSP to implement go-to-definition and find-references.
8
+ */
9
+ export interface BaseNode {
10
+ kind: string;
11
+ token: Token;
12
+ }
13
+ /**
14
+ * The built-in scalar types available in WORDS.
15
+ * `context` is a special type used only in the system interface declaration
16
+ * (getContext / setContext) to represent an opaque stored context value.
17
+ */
18
+ export type PrimitiveType = 'string' | 'integer' | 'float' | 'boolean' | 'context';
19
+ /**
20
+ * A scalar built-in type — string, integer, float, boolean, or context.
21
+ * e.g. `name(string)`, `total(float)`
22
+ */
23
+ export interface PrimitiveTypeNode extends BaseNode {
24
+ kind: 'PrimitiveType';
25
+ name: PrimitiveType;
26
+ }
27
+ /**
28
+ * A parameterised list type.
29
+ * e.g. `list(OrderItem)`, `list(string)`
30
+ */
31
+ export interface ListTypeNode extends BaseNode {
32
+ kind: 'ListType';
33
+ elementType: TypeNode;
34
+ }
35
+ /**
36
+ * A parameterised map type with explicit key and value types.
37
+ * e.g. `map(string, OrderSummary)`
38
+ */
39
+ export interface MapTypeNode extends BaseNode {
40
+ kind: 'MapType';
41
+ keyType: TypeNode;
42
+ valueType: TypeNode;
43
+ }
44
+ /**
45
+ * A reference to a named interface component used as a type.
46
+ * e.g. `Product`, `?AuthError`, `OrderItem`
47
+ * The `optional` flag is set when the type is prefixed with `?`.
48
+ */
49
+ export interface NamedTypeNode extends BaseNode {
50
+ kind: 'NamedType';
51
+ name: string;
52
+ optional: boolean;
53
+ }
54
+ /**
55
+ * Union of all type annotation forms that can appear after a name
56
+ * in a prop, method parameter, or returns clause.
57
+ */
58
+ export type TypeNode = PrimitiveTypeNode | ListTypeNode | MapTypeNode | NamedTypeNode;
59
+ /**
60
+ * A dot-separated name that references a construct across module boundaries,
61
+ * or a runtime system call. Parts are stored as an array so the analyser can
62
+ * resolve each segment independently.
63
+ *
64
+ * Examples:
65
+ * UIModule.LoginForm → ['UIModule', 'LoginForm']
66
+ * system.setContext → ['system', 'setContext']
67
+ * system.RoutingModule.dispatch → ['system', 'RoutingModule', 'dispatch']
68
+ * SessionAdapter.checkSession → ['SessionAdapter', 'checkSession']
69
+ */
70
+ export interface QualifiedName extends BaseNode {
71
+ kind: 'QualifiedName';
72
+ parts: string[];
73
+ }
74
+ /**
75
+ * A single named, typed entry in a `props` or `state` block.
76
+ *
77
+ * Props declared with a type are data props:
78
+ * `error(AuthError)`
79
+ * → name='error', type=NamedTypeNode('AuthError'), argName=null
80
+ *
81
+ * Props declared with an argument name and type are interaction props.
82
+ * The argument name is the variable the parent passes into the handler body:
83
+ * `onSubmit credentials(AccountCredentials)`
84
+ * → name='onSubmit', type=NamedTypeNode('AccountCredentials'), argName='credentials'
85
+ *
86
+ * Props declared with no type are interaction props with no payload.
87
+ * The handler body receives no variable:
88
+ * `onConfirm`
89
+ * → name='onConfirm', type=null, argName=null
90
+ *
91
+ * Interaction prop names are chosen by the designer — there are no reserved
92
+ * names. `onSubmit`, `onConfirm`, `onDismiss`, `onLoad` are all plain prop
93
+ * names with no special meaning to the language.
94
+ *
95
+ * In a `state` block:
96
+ * `inputEmail(string) is ""`
97
+ * → name='inputEmail', type=PrimitiveTypeNode('string'), defaultValue=StringLiteralNode('')
98
+ *
99
+ * `optional` is true when the type is prefixed with `?` — e.g. `?Product`.
100
+ * `argName` is the argument variable name declared on an interaction prop,
101
+ * inferred by the parser and used downstream at call sites.
102
+ */
103
+ export interface PropNode extends BaseNode {
104
+ kind: 'Prop';
105
+ name: string;
106
+ type: TypeNode | null;
107
+ optional: boolean;
108
+ defaultValue: LiteralNode | null;
109
+ argName: string | null;
110
+ }
111
+ /** A double-quoted string value. e.g. `"The user authenticated successfully"` */
112
+ export interface StringLiteralNode extends BaseNode {
113
+ kind: 'StringLiteral';
114
+ value: string;
115
+ }
116
+ /** A whole number value. e.g. `42`, `5000` */
117
+ export interface IntegerLiteralNode extends BaseNode {
118
+ kind: 'IntegerLiteral';
119
+ value: number;
120
+ }
121
+ /** A decimal number value. e.g. `0.0`, `3.14` */
122
+ export interface FloatLiteralNode extends BaseNode {
123
+ kind: 'FloatLiteral';
124
+ value: number;
125
+ }
126
+ /** A boolean value — `true` or `false`. */
127
+ export interface BooleanLiteralNode extends BaseNode {
128
+ kind: 'BooleanLiteral';
129
+ value: boolean;
130
+ }
131
+ /**
132
+ * An empty list literal `[]`.
133
+ * Non-empty list literals do not appear in WORDS source — `[]` is the only
134
+ * form used as a default value in props and state declarations.
135
+ */
136
+ export interface ListLiteralNode extends BaseNode {
137
+ kind: 'ListLiteral';
138
+ elements: LiteralNode[];
139
+ }
140
+ /**
141
+ * An empty map literal `{}`.
142
+ * Non-empty map literals do not appear in WORDS source — `{}` is the only
143
+ * form used as a default value in props and state declarations.
144
+ */
145
+ export interface MapLiteralNode extends BaseNode {
146
+ kind: 'MapLiteral';
147
+ entries: Array<{
148
+ key: LiteralNode;
149
+ value: LiteralNode;
150
+ }>;
151
+ }
152
+ /**
153
+ * Union of all literal value forms.
154
+ * Literals appear as default values in props/state declarations and as
155
+ * argument values in component use and system calls.
156
+ */
157
+ export type LiteralNode = StringLiteralNode | IntegerLiteralNode | FloatLiteralNode | BooleanLiteralNode | ListLiteralNode | MapLiteralNode;
158
+ /**
159
+ * A method exposed by a provider, adapter, or interface component.
160
+ * Methods appear directly in the body after `props`, without a keyword prefix.
161
+ * Method names are chosen by the designer — there are no reserved names.
162
+ *
163
+ * Examples:
164
+ * `getProducts returns(list(Product)) "Returns all products"`
165
+ * `login credentials(AccountCredentials) returns(SystemUser) "Authenticates the user"`
166
+ * `clear "Empties the cart"` — no params, no return type
167
+ *
168
+ * `returnType` is null when the method produces no output.
169
+ * `description` is the optional quoted string following the method signature.
170
+ */
171
+ export interface MethodNode extends BaseNode {
172
+ kind: 'Method';
173
+ name: string;
174
+ params: PropNode[];
175
+ returnType: TypeNode | null;
176
+ description: string | null;
177
+ }
178
+ /**
179
+ * The simple form of a returns clause — a comma-separated list of context names.
180
+ * e.g. `returns AccountCredentials, AuthError`
181
+ * Each name must have a corresponding `when` rule in the module's process.
182
+ */
183
+ export interface SimpleReturnsNode extends BaseNode {
184
+ kind: 'SimpleReturns';
185
+ contexts: string[];
186
+ }
187
+ /**
188
+ * A side effect declared inside an expanded returns entry.
189
+ * Side effects execute before the context is produced and the module transitions.
190
+ *
191
+ * Examples:
192
+ * `system.setContext name is SessionToken, value is state.context`
193
+ * `system.dropContext name is SessionToken`
194
+ */
195
+ export interface SideEffectNode extends BaseNode {
196
+ kind: 'SideEffect';
197
+ call: QualifiedName;
198
+ args: ArgumentNode[];
199
+ }
200
+ /**
201
+ * A single entry inside an expanded returns block — one context name with
202
+ * zero or more side effects that execute before the context is produced.
203
+ */
204
+ export interface ExpandedReturnNode extends BaseNode {
205
+ kind: 'ExpandedReturn';
206
+ contextName: string;
207
+ sideEffects: SideEffectNode[];
208
+ }
209
+ /**
210
+ * The expanded form of a returns clause, used when one or more returned
211
+ * contexts need to carry side effects.
212
+ *
213
+ * Example:
214
+ * returns (
215
+ * SessionToken (
216
+ * system.setContext name is SessionToken, value is state.context
217
+ * )
218
+ * SessionValidationError (
219
+ * system.dropContext name is SessionToken
220
+ * )
221
+ * )
222
+ */
223
+ export interface ExpandedReturnsNode extends BaseNode {
224
+ kind: 'ExpandedReturns';
225
+ entries: ExpandedReturnNode[];
226
+ }
227
+ /**
228
+ * Union of the two forms a returns clause can take inside a state definition.
229
+ * The analyser resolves context names from both forms identically.
230
+ */
231
+ export type ReturnsNode = SimpleReturnsNode | ExpandedReturnsNode;
232
+ /**
233
+ * A named argument passed to a component, system call, or method.
234
+ * Always written as `name is value`.
235
+ *
236
+ * The argument name on the left of `is` is either a prop name being wired up
237
+ * (e.g. `type`, `message`, `orderId`) or an interaction prop name defined by
238
+ * the designer on the target component (e.g. `onSubmit`, `onConfirm`, `onDismiss`).
239
+ *
240
+ * Examples:
241
+ * `type is "warning"`
242
+ * `message is state.context.reason`
243
+ * `name is SessionToken, value is state.context`
244
+ */
245
+ export interface ArgumentNode extends BaseNode {
246
+ kind: 'Argument';
247
+ name: string;
248
+ value: ExpressionNode;
249
+ }
250
+ /**
251
+ * A dot-separated property access path.
252
+ * Used wherever a value is read from state, props, or a bound iteration variable.
253
+ *
254
+ * Examples:
255
+ * `state.context.fullName` → path = ['state', 'context', 'fullName']
256
+ * `props.items` → path = ['props', 'items']
257
+ * `notification.message` → path = ['notification', 'message']
258
+ */
259
+ export interface AccessExpressionNode extends BaseNode {
260
+ kind: 'AccessExpression';
261
+ path: string[];
262
+ }
263
+ /**
264
+ * A function or method call expression.
265
+ * Used for system calls and adapter method invocations with arguments.
266
+ *
267
+ * Examples:
268
+ * `system.getContext(SystemUser)`
269
+ * `props.onConfirm(orderId is props.orderId, action is "Confirmed")`
270
+ *
271
+ * Note: `onConfirm` in the second example is not a language keyword — it is
272
+ * an interaction prop name defined by the designer on the target component.
273
+ */
274
+ export interface CallExpressionNode extends BaseNode {
275
+ kind: 'CallExpression';
276
+ callee: AccessExpressionNode | QualifiedName;
277
+ args: ArgumentNode[];
278
+ }
279
+ /**
280
+ * A `state.return(contextName)` expression — the mechanism through which
281
+ * a screen drives a state transition by producing a named context.
282
+ * The contextName must match one of the state's declared `returns` entries.
283
+ */
284
+ export interface StateReturnExpressionNode extends BaseNode {
285
+ kind: 'StateReturnExpression';
286
+ contextName: string;
287
+ }
288
+ /**
289
+ * An inline block expression written as `( ... )`.
290
+ * Used as the value of an interaction prop argument to group one or more
291
+ * statements. The interaction prop name is defined by the designer — the
292
+ * language places no restriction on what it is called.
293
+ *
294
+ * Example:
295
+ * onSubmit is (
296
+ * state.return(credentials)
297
+ * )
298
+ *
299
+ * Here `onSubmit` is a prop name declared by the view designer, not a keyword.
300
+ */
301
+ export interface BlockExpressionNode extends BaseNode {
302
+ kind: 'BlockExpression';
303
+ statements: StatementNode[];
304
+ }
305
+ /**
306
+ * Union of all expression forms that can appear as the value of an argument,
307
+ * a condition operand, or a prop default.
308
+ */
309
+ export type ExpressionNode = AccessExpressionNode | CallExpressionNode | StateReturnExpressionNode | BlockExpressionNode | LiteralNode;
310
+ /**
311
+ * An assignment statement inside a block expression.
312
+ * Used inside interaction prop handler bodies to write values into
313
+ * the component's local state when the interaction fires.
314
+ *
315
+ * The prop name that wraps this block is defined by the designer
316
+ * (e.g. a prop named `onLoad` on a view, or `onSuccess` on an adapter use).
317
+ * The statement itself assigns the received value into a state field.
318
+ *
319
+ * Example: `state.reviews is reviews`
320
+ * — inside a block that is the value of a designer-named interaction prop.
321
+ */
322
+ export interface AssignmentStatementNode extends BaseNode {
323
+ kind: 'AssignmentStatement';
324
+ target: AccessExpressionNode;
325
+ value: ExpressionNode;
326
+ }
327
+ /**
328
+ * A `state.return(contextName)` statement inside a block expression.
329
+ * This is the statement form of StateReturnExpressionNode — it appears
330
+ * as the body of an interaction prop handler, driving the state transition
331
+ * when the user performs the corresponding action.
332
+ *
333
+ * The interaction prop that wraps this statement is named by the designer.
334
+ * e.g. `onConfirm is ( state.return(confirmDetails) )`
335
+ */
336
+ export interface StateReturnStatementNode extends BaseNode {
337
+ kind: 'StateReturnStatement';
338
+ contextName: string;
339
+ }
340
+ /**
341
+ * Union of all statement forms that can appear inside a block expression body.
342
+ */
343
+ export type StatementNode = AssignmentStatementNode | StateReturnStatementNode;
344
+ /**
345
+ * A boolean condition evaluated inside a `uses` block.
346
+ * The `left` side is always a property access — `state.context`,
347
+ * `state.context.status`, or `props.someField`.
348
+ * The `right` side is the value being compared against.
349
+ * `operator` is either `'is'` (equality) or `'is not'` (inequality).
350
+ *
351
+ * Examples:
352
+ * `state.context is AccountDeauthenticated`
353
+ * `state.context.status is "pending"`
354
+ * `state.context is not AccountRecovered`
355
+ */
356
+ export interface ConditionNode extends BaseNode {
357
+ kind: 'Condition';
358
+ left: AccessExpressionNode;
359
+ operator: 'is' | 'is not';
360
+ right: ExpressionNode;
361
+ }
362
+ /**
363
+ * A conditional component mount — `if <condition> ( ... )`.
364
+ * The body contains the same entries as a `uses` block and is only
365
+ * activated when the condition evaluates to true at runtime.
366
+ */
367
+ export interface ConditionalBlockNode extends BaseNode {
368
+ kind: 'ConditionalBlock';
369
+ condition: ConditionNode;
370
+ body: UseEntryNode[];
371
+ }
372
+ /**
373
+ * A `for <collection> as <binding> ( ... )` iteration block.
374
+ * Produces one instance of each child component per item in the collection.
375
+ *
376
+ * For a list: `bindings` has one entry — the item variable name.
377
+ * For a map: `bindings` has two entries — the key variable and the value variable.
378
+ *
379
+ * Examples:
380
+ * `for state.context.notifications as notification ( ... )`
381
+ * → collection = AccessExpression(['state','context','notifications']),
382
+ * bindings = ['notification']
383
+ * `for state.context.productsByCategoryMap as category, products ( ... )`
384
+ * → bindings = ['category', 'products']
385
+ */
386
+ export interface IterationBlockNode extends BaseNode {
387
+ kind: 'IterationBlock';
388
+ collection: AccessExpressionNode;
389
+ bindings: string[];
390
+ body: UseEntryNode[];
391
+ }
392
+ /**
393
+ * A single component activation inside a `uses` block.
394
+ * Covers all five component kinds — screen, view, adapter, provider, interface.
395
+ *
396
+ * `name` is a QualifiedName because components can be referenced across modules:
397
+ * `view UIModule.LoginForm ( ... )`
398
+ * `adapter SessionAdapter.checkSession`
399
+ * `screen LoginScreen`
400
+ *
401
+ * `args` are the named arguments passed to the component via `is` assignments.
402
+ * Argument names on the left of `is` correspond to prop names declared by the
403
+ * designer on the target component — the language imposes no naming convention.
404
+ *
405
+ * `uses` holds any nested component uses declared inline (view composition).
406
+ */
407
+ export interface ComponentUseNode extends BaseNode {
408
+ kind: 'ComponentUse';
409
+ componentKind: 'screen' | 'view' | 'adapter' | 'provider' | 'interface';
410
+ name: QualifiedName;
411
+ args: ArgumentNode[];
412
+ uses: UseEntryNode[];
413
+ }
414
+ /**
415
+ * Union of everything that can appear as an entry inside a `uses` block:
416
+ * - A direct component activation (screen, view, adapter, provider, interface)
417
+ * - A conditional block (`if ...`)
418
+ * - An iteration block (`for ... as ...`)
419
+ */
420
+ export type UseEntryNode = ComponentUseNode | ConditionalBlockNode | IterationBlockNode;
421
+ /**
422
+ * An inline context construction block following a transition narrative.
423
+ * Used when a state is entered from an external trigger (e.g. an implements
424
+ * handler) and the incoming data must be shaped into the context the
425
+ * receiving state expects.
426
+ *
427
+ * Example:
428
+ * enter Unauthenticated "The user's session has expired" (
429
+ * reason is "The session has expired"
430
+ * code is "ERR:01"
431
+ * )
432
+ */
433
+ export interface InlineContextNode extends BaseNode {
434
+ kind: 'InlineContext';
435
+ args: ArgumentNode[];
436
+ }
437
+ /**
438
+ * A single `when` rule inside a process body.
439
+ * Declares that when the module is in `currentState` and produces `producedContext`,
440
+ * it should enter `nextState`.
441
+ *
442
+ * `narrative` is the optional quoted explanation of why the transition occurs.
443
+ * `inlineContext` is present only when the transition is triggered externally
444
+ * and the context must be constructed inline.
445
+ */
446
+ export interface WhenRuleNode extends BaseNode {
447
+ kind: 'WhenRule';
448
+ currentState: string;
449
+ producedContext: string;
450
+ nextState: string;
451
+ narrative: string | null;
452
+ inlineContext: InlineContextNode | null;
453
+ }
454
+ /**
455
+ * A process definition inside a module.
456
+ * Contains the complete transition map for one scenario — every state the
457
+ * module can be in under that scenario, what each state produces, and
458
+ * where the module goes next.
459
+ */
460
+ export interface ProcessNode extends BaseNode {
461
+ kind: 'Process';
462
+ name: string;
463
+ description: string | null;
464
+ rules: WhenRuleNode[];
465
+ }
466
+ /**
467
+ * The body of a single `if` branch inside an `implements` switch handler.
468
+ * Maps a path condition to a state transition.
469
+ *
470
+ * Example:
471
+ * if path is "/products"
472
+ * enter ProductList "The /products path activates the product list"
473
+ */
474
+ export interface ImplementsBranchNode extends BaseNode {
475
+ kind: 'ImplementsBranch';
476
+ condition: ConditionNode;
477
+ targetState: string;
478
+ narrative: string | null;
479
+ }
480
+ /**
481
+ * An `implements ModuleName.HandlerInterface ( ... )` block inside a module.
482
+ * Declares that this module implements the named handler interface and
483
+ * provides the switch logic for routing incoming events to local states.
484
+ *
485
+ * Example:
486
+ * implements RoutingModule.RouteSwitchHandler (
487
+ * switch path(string) (
488
+ * if path is "/products"
489
+ * enter ProductList "The /products path activates the product list"
490
+ * )
491
+ * )
492
+ */
493
+ export interface ImplementsHandlerNode extends BaseNode {
494
+ kind: 'ImplementsHandler';
495
+ interfaceName: QualifiedName;
496
+ switchParam: string;
497
+ switchParamType: TypeNode;
498
+ branches: ImplementsBranchNode[];
499
+ }
500
+ /**
501
+ * The root construct of a WORDS project — appears exactly once, in the
502
+ * system file at the project root.
503
+ * Names the application, lists every module it contains, and declares
504
+ * the three built-in system interface methods (getContext, setContext, dropContext).
505
+ */
506
+ export interface SystemNode extends BaseNode {
507
+ kind: 'System';
508
+ name: string;
509
+ description: string | null;
510
+ modules: string[];
511
+ interfaceMethods: MethodNode[];
512
+ }
513
+ /**
514
+ * A module definition — the primary organisational unit below the system level.
515
+ * Contains the module's process definitions, starting state, cross-module
516
+ * implements blocks, and any top-level system subscription calls.
517
+ *
518
+ * `startState` is the state the module enters autonomously on initialisation.
519
+ * It is null for stateless modules or modules triggered externally.
520
+ *
521
+ * `subscriptions` are top-level `system.ModuleName.subscribeRoute ...` calls
522
+ * declared directly in the module body.
523
+ *
524
+ * `inlineInterfaces` are interface declarations written inline inside the
525
+ * module body (e.g. handler interface shapes in RoutingModule).
526
+ */
527
+ export interface ModuleNode extends BaseNode {
528
+ kind: 'Module';
529
+ name: string;
530
+ description: string | null;
531
+ processes: ProcessNode[];
532
+ startState: string | null;
533
+ implements: ImplementsHandlerNode[];
534
+ subscriptions: CallExpressionNode[];
535
+ inlineInterfaces: InterfaceNode[];
536
+ }
537
+ /**
538
+ * A state definition — the smallest behavioral unit in a WORDS specification.
539
+ * Represents a stable condition the module is in, what it expects on entry,
540
+ * what it can produce to drive the next transition, and what it uses while resident.
541
+ *
542
+ * `module` is the owning module name from the ownership declaration line.
543
+ * `receives` is the name of the context expected on entry, or null if the state
544
+ * takes no context. `receivesOptional` is true when prefixed with `?`.
545
+ * `returns` is null for transient states that produce no output.
546
+ * `uses` is empty for states with no components.
547
+ */
548
+ export interface StateNode extends BaseNode {
549
+ kind: 'State';
550
+ module: string;
551
+ name: string;
552
+ receives: string | null;
553
+ receivesOptional: boolean;
554
+ returns: ReturnsNode | null;
555
+ uses: UseEntryNode[];
556
+ }
557
+ /**
558
+ * A context definition — the structured, typed data that flows between states.
559
+ * Every context is named, belongs to a module, and declares its fields as props.
560
+ * Referenced by name in state `receives` and `returns` clauses and in process
561
+ * `when` rules.
562
+ */
563
+ export interface ContextNode extends BaseNode {
564
+ kind: 'Context';
565
+ module: string;
566
+ name: string;
567
+ fields: PropNode[];
568
+ }
569
+ /**
570
+ * A screen definition — the top-level UI unit used by a state.
571
+ * Has implicit access to `state.context` and `state.return()`.
572
+ * Can only be used by a state, never by another component.
573
+ * Its `uses` block activates view components and may contain
574
+ * conditional blocks and iteration blocks.
575
+ */
576
+ export interface ScreenNode extends BaseNode {
577
+ kind: 'Screen';
578
+ module: string;
579
+ name: string;
580
+ description: string | null;
581
+ uses: UseEntryNode[];
582
+ }
583
+ /**
584
+ * A view definition — a reusable rendering unit.
585
+ * Receives all data and interaction props via `props`.
586
+ * Interaction prop names are defined by the designer — the language
587
+ * imposes no naming convention on them.
588
+ * Has no access to `state.context` or `state.return()`.
589
+ * Can declare local mutable `state` for concerns it owns entirely
590
+ * (input values, toggle states, hover conditions).
591
+ * Can use other views in its own `uses` block.
592
+ */
593
+ export interface ViewNode extends BaseNode {
594
+ kind: 'View';
595
+ module: string;
596
+ name: string;
597
+ description: string | null;
598
+ props: PropNode[];
599
+ state: PropNode[];
600
+ uses: UseEntryNode[];
601
+ }
602
+ /**
603
+ * A provider definition — computes and exposes in-memory derived data.
604
+ * Never performs I/O — delegates all external data fetching to adapters
605
+ * received through `props`. Exposes its data through named methods.
606
+ * Maintains its own internal `state` between method calls.
607
+ */
608
+ export interface ProviderNode extends BaseNode {
609
+ kind: 'Provider';
610
+ module: string;
611
+ name: string;
612
+ description: string | null;
613
+ props: PropNode[];
614
+ state: PropNode[];
615
+ methods: MethodNode[];
616
+ }
617
+ /**
618
+ * An adapter definition — the I/O boundary of the system.
619
+ * The only construct permitted to communicate with the outside world
620
+ * (HTTP APIs, databases, local storage, hardware).
621
+ * The only construct permitted to be async.
622
+ * Receives environment-level configuration through `props`.
623
+ * Maintains runtime state (connection state, cached tokens, retry counters)
624
+ * in its own `state` block.
625
+ * Exposes all external communication through named methods.
626
+ * Method names are defined by the designer.
627
+ */
628
+ export interface AdapterNode extends BaseNode {
629
+ kind: 'Adapter';
630
+ module: string;
631
+ name: string;
632
+ description: string | null;
633
+ props: PropNode[];
634
+ state: PropNode[];
635
+ methods: MethodNode[];
636
+ }
637
+ /**
638
+ * An interface component definition — a named, typed contract for anything
639
+ * that does not fit the role of screen, view, provider, or adapter.
640
+ * Used as a data model (Product, CartItem), a helper (CatalogueFilter),
641
+ * a handler shape (RouteSwitchHandler), or a callable contract (Pagination).
642
+ *
643
+ * Interface components are the typed vocabulary that all other components
644
+ * reference in their own props and method declarations.
645
+ *
646
+ * When an interface component has a `uses` block, it activates adapters
647
+ * or providers to populate its internal `state`. The interaction props
648
+ * that wire adapter results into state are declared by the designer on
649
+ * the interface component itself — they are plain prop names, not keywords.
650
+ */
651
+ export interface InterfaceNode extends BaseNode {
652
+ kind: 'Interface';
653
+ module: string;
654
+ name: string;
655
+ description: string | null;
656
+ props: PropNode[];
657
+ state: PropNode[];
658
+ methods: MethodNode[];
659
+ uses: UseEntryNode[];
660
+ }
661
+ /**
662
+ * Union of all constructs that can appear as top-level nodes in a document.
663
+ * A document typically contains exactly one top-level node (e.g. one state,
664
+ * one screen, one context) plus an optional ownership declaration line.
665
+ * The system file and module files may contain more complex structures.
666
+ */
667
+ export type TopLevelNode = SystemNode | ModuleNode | StateNode | ContextNode | ScreenNode | ViewNode | ProviderNode | AdapterNode | InterfaceNode;
668
+ /**
669
+ * The root node produced by parsing a single `.wds` file.
670
+ *
671
+ * `ownerModule` captures the bare `module ModuleName` ownership declaration
672
+ * that appears on its own line at the top of component files (states, screens,
673
+ * views, etc.). It is null in the system file and in module files where the
674
+ * module declaration opens a body block rather than standing alone.
675
+ *
676
+ * `nodes` contains all top-level constructs found in the file. Most component
677
+ * files will have exactly one node. Module files may have one (the module itself).
678
+ * The system file will have one SystemNode.
679
+ */
680
+ export interface DocumentNode {
681
+ kind: 'Document';
682
+ ownerModule: string | null;
683
+ nodes: TopLevelNode[];
684
+ }
685
+ //# sourceMappingURL=ast.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"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"}