@words-lang/parser 0.1.0

package/dist/parser/ast.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ast.js.map

package/dist/parser/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":""}

package/dist/parser/parser.d.ts

@@ -0,0 +1,411 @@
+/**
+ * parser.ts
+ *
+ * The WORDS parser. Consumes a flat token stream produced by the Lexer and
+ * builds an AST described in ast.ts.
+ *
+ * Design principles:
+ *
+ * - Recursive descent. Each grammar rule has a corresponding private method.
+ *   Methods consume tokens and return AST nodes.
+ *
+ * - Error recovery. When an unexpected token is encountered the parser emits
+ *   a diagnostic, skips tokens until it finds a safe synchronisation point
+ *   (typically a newline, a closing paren, or a known top-level keyword), and
+ *   continues. This means a single parse pass collects all errors in the file.
+ *
+ * - No exceptions for parse errors. All problems are collected in `this.diagnostics`
+ *   and returned alongside the partial AST in the `ParseResult`.
+ *
+ * - Comments and newlines are consumed transparently by the `skip()` helper
+ *   unless the calling rule explicitly needs them (e.g. ownership declaration
+ *   detection requires newlines).
+ *
+ * - `system` and `state` are both keywords and identifier prefixes in access
+ *   expressions (`system.setContext`, `state.context`). The parser disambiguates
+ *   by context — inside a `uses` block or argument value position, these are
+ *   treated as access expression roots, not construct keywords.
+ */
+import { DocumentNode } from './ast';
+import { Token } from '../lexer/token';
+import { Diagnostic } from '../analyser/diagnostics';
+/**
+ * The value returned by `Parser.parse()`.
+ * Always contains both a (possibly partial) document and all diagnostics
+ * collected during the parse — even when errors were encountered.
+ */
+export interface ParseResult {
+    document: DocumentNode;
+    diagnostics: Diagnostic[];
+}
+export declare class Parser {
+    /** The full token stream from the lexer, including EOF. */
+    private tokens;
+    /** Current position in the token stream. */
+    private pos;
+    /** Diagnostics collected during this parse. */
+    private diagnostics;
+    constructor(tokens: Token[]);
+    /**
+     * Parses the entire token stream and returns a ParseResult containing
+     * the document AST and all collected diagnostics.
+     * Never throws — all errors are collected as diagnostics.
+     */
+    parse(): ParseResult;
+    /**
+     * Parses a complete `.wds` file.
+     *
+     * Detects the ownership declaration pattern — a bare `module ModuleName`
+     * on its own line at the top of component files. If the first non-trivial
+     * content is `module PascalIdent Newline` (with no opening `(`), it is
+     * captured as `ownerModule` and the next construct is parsed normally.
+     */
+    private parseDocument;
+    /**
+     * Parses one top-level construct and returns it, or emits a diagnostic
+     * and returns null if the current token does not start a known construct.
+     */
+    private parseTopLevel;
+    /**
+     * Parses:
+     *   system SystemName "description" (
+     *     modules ( ModuleOne ModuleTwo )
+     *     interface ( ... )
+     *   )
+     */
+    private parseSystem;
+    /**
+     * Parses:
+     *   module ModuleName "description" (
+     *     process ... ( when ... )
+     *     start StateName
+     *     implements Module.Handler ( methodName param(Type) ( if ... ) )
+     *     system.Module.subscribeRoute ...
+     *     interface HandlerName ( ... )
+     *   )
+     */
+    private parseModule;
+    /**
+     * Parses:
+     *   process ProcessName "description" (
+     *     when State returns Context
+     *       enter NextState "narrative"
+     *     ...
+     *   )
+     */
+    private parseProcess;
+    /**
+     * Parses:
+     *   when CurrentState returns ProducedContext
+     *     enter NextState "narrative" ( inlineContext? )
+     */
+    private parseWhenRule;
+    /**
+     * Parses an inline context construction block:
+     *   ( reason is "..." code is "..." )
+     */
+    private parseInlineContext;
+    /**
+     * Parses:
+     *   implements Module.HandlerInterface (
+     *     methodName param(Type) (
+     *       if param is "/path"
+     *         enter State "narrative"
+     *     )
+     *   )
+     *
+     * The method name (e.g. `switch`) is a plain camelCase identifier chosen
+     * by the designer on the handler interface — it is not a reserved keyword.
+     */
+    private parseImplements;
+    /**
+     * Parses one branch inside an implements handler body:
+     *   if param is "/path"
+     *     enter State "narrative"
+     */
+    private parseImplementsBranch;
+    /**
+     * Parses:
+     *   state StateName receives ?ContextName (
+     *     returns ContextA, ContextB
+     *     uses screen ScreenName
+     *   )
+     */
+    private parseState;
+    /**
+     * Parses:
+     *   context ContextName (
+     *     field(Type),
+     *     field(Type)
+     *   )
+     */
+    private parseContext;
+    /**
+     * Parses:
+     *   screen ScreenName "description" (
+     *     uses ( ... )
+     *   )
+     */
+    private parseScreen;
+    /**
+     * Parses:
+     *   view ViewName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     uses ( ... )
+     *   )
+     */
+    private parseView;
+    /**
+     * Parses:
+     *   provider ProviderName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     interface ( methods... )
+     *   )
+     */
+    private parseProvider;
+    /**
+     * Parses:
+     *   adapter AdapterName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     interface ( methods... )
+     *   )
+     */
+    private parseAdapter;
+    /**
+     * Parses:
+     *   interface InterfaceName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     uses ( ... )
+     *     methodName param(Type) returns(Type) "description"
+     *     ...
+     *   )
+     *
+     * When used as a module-level handler interface, the body contains a
+     * method declaration whose body is a series of `if` branches. The method
+     * name (e.g. `switch`) is a plain camelCase identifier — not a keyword.
+     */
+    private parseInterface;
+    /**
+     * Parses either the simple or expanded form of a returns clause.
+     *
+     * Simple:   returns ContextA, ContextB
+     * Expanded: returns ( ContextA ( sideEffects ) ContextB ( sideEffects ) )
+     */
+    private parseReturns;
+    /**
+     * Parses a `uses` block and returns its entries.
+     * Handles both the single-entry form and the parenthesised list form.
+     *
+     * Single: `uses screen LoginScreen`
+     * List:   `uses ( view A, view B, if ... )`
+     */
+    private parseUsesBlock;
+    /**
+     * Parses a comma-separated sequence of use entries inside a `uses ( ... )` block.
+     */
+    private parseUseEntries;
+    /**
+     * Parses a single use entry — a component use, a conditional block, or
+     * an iteration block.
+     */
+    private parseUseEntry;
+    /**
+     * Parses a single component use:
+     *   view UIModule.LoginForm ( args... uses... )
+     *   adapter SessionAdapter.checkSession
+     *   screen LoginScreen
+     */
+    private parseComponentUse;
+    /**
+     * Parses:
+     *   if condition ( useEntries... )
+     */
+    private parseConditionalBlock;
+    /**
+     * Parses:
+     *   for collection as binding ( useEntries... )
+     *   for collection as key, value ( useEntries... )
+     */
+    private parseIterationBlock;
+    /**
+     * Parses a condition expression:
+     *   state.context is AccountDeauthenticated
+     *   state.context.status is "pending"
+     *   state.context is not AccountRecovered
+     */
+    private parseCondition;
+    /**
+     * Parses a comma-separated list of `name is value` arguments.
+     * Used inside parenthesised component use bodies and system calls.
+     */
+    private parseArguments;
+    /**
+     * Parses a comma-separated list of inline `name is value` arguments
+     * without an enclosing paren block. Stops at newline, `)`, or EOF.
+     */
+    private parseInlineArgList;
+    /**
+     * Parses a single argument: `name is value`
+     */
+    private parseArgument;
+    /**
+     * Parses an expression — a value on the right-hand side of an `is` assignment
+     * or a condition operand.
+     *
+     * Handles:
+     *   - Block expressions:          `( state.return(x) )`
+     *   - state.return():             `state.return(contextName)`
+     *   - Access expressions:         `state.context.fullName`, `props.items`
+     *   - Call expressions:           `system.getContext(SystemUser)`
+     *   - Literals:                   `"string"`, `42`, `3.14`, `true`, `false`, `[]`, `{}`
+     *   - PascalCase type references: `SystemUser` (e.g. in system.getContext(SystemUser))
+     */
+    private parseExpression;
+    /**
+     * Parses a block expression: `( statements... )`
+     * The body contains either state.return() calls or assignment statements.
+     */
+    private parseBlockExpression;
+    /**
+     * Parses a statement inside a block expression body.
+     *
+     * `state.return(contextName)` → StateReturnStatement
+     * `state.fieldName is value`  → AssignmentStatement
+     */
+    private parseStatement;
+    /**
+     * Parses an access expression or call expression starting with a camelCase
+     * name, 'state', or 'system'.
+     *
+     * If the path ends with `(...)`, it becomes a CallExpression.
+     * If the path ends with `return(...)`, it becomes a StateReturnExpression.
+     */
+    private parseAccessOrCall;
+    /**
+     * Parses a dot-separated access path — always returns an AccessExpressionNode.
+     * Used in conditions and iteration blocks where a call is not expected.
+     */
+    private parseAccessExpression;
+    private parseStringLiteral;
+    private parseIntegerLiteral;
+    private parseFloatLiteral;
+    private parseBooleanLiteral;
+    private parseListLiteral;
+    private parseMapLiteral;
+    /**
+     * Parses a comma-separated list of prop declarations inside a `props` or
+     * `state` or `context` block. Stops at `)` or EOF.
+     *
+     * Forms:
+     *   `name(Type)`                  — typed data prop
+     *   `name(Type) is default`       — typed prop with default value
+     *   `name argName(Type)`          — interaction prop with argument variable
+     *   `name`                        — interaction prop with no payload
+     *   `?name(Type)`                 — optional typed prop (in context fields)
+     */
+    private parsePropList;
+    /**
+     * Parses a type annotation. Called when the cursor is on the type keyword or name.
+     */
+    private parseType;
+    /**
+     * Parses a standard method declaration in a provider, adapter, or interface body.
+     * Delegates to `parseInterfaceMethod` which also handles handler method bodies.
+     */
+    private parseMethod;
+    /**
+     * Parses a method declaration that may optionally have a body block of
+     * `if` branches — used for handler interface method declarations.
+     *
+     * Forms:
+     *   `methodName "description"`
+     *   `methodName param(Type) returns(Type) "description"`
+     *   `methodName param(Type) ( if param is "/path" enter State "narrative" )`
+     */
+    private parseInterfaceMethod;
+    /**
+     * Parses a dot-separated qualified name.
+     * e.g. `UIModule.LoginForm`, `system.setContext`, `SessionAdapter.checkSession`
+     */
+    private parseQualifiedName;
+    /**
+     * Parses a literal value used as a default in a prop or state declaration.
+     * Handles strings, integers, floats, booleans, `[]`, and `{}`.
+     */
+    private parseLiteralValue;
+    /** Returns the token at the current position. */
+    private current;
+    /** Returns true if the current token has the given type. */
+    private check;
+    /**
+     * Consumes and returns the current token, advancing the position.
+     */
+    private advance;
+    /**
+     * Consumes the current token if it matches `type` and returns it.
+     * If it does not match, emits a diagnostic and returns null without advancing.
+     */
+    private expect;
+    /**
+     * Consumes a PascalIdent or CamelIdent and returns its value.
+     * Emits a diagnostic if neither is present.
+     */
+    private expectIdent;
+    /**
+     * Consumes and returns the string value if the current token is a StringLit.
+     * Returns null without advancing if it is not.
+     */
+    private parseOptionalString;
+    /**
+     * Skips comment tokens only.
+     */
+    private skipComments;
+    /**
+     * Skips comments and newlines — the whitespace between meaningful tokens.
+     */
+    private skipTrivia;
+    /**
+     * Returns true if the current token looks like a system.* call.
+     */
+    private checkSystemCall;
+    /**
+     * Returns true if the current token can start an argument (`name is value`).
+     * Arguments start with a camelCase identifier.
+     */
+    private checkArgumentStart;
+    /**
+     * Returns true if the current token can start a use entry (component kind,
+     * if, or for).
+     */
+    private isUseEntry;
+    /**
+     * Returns true if the current two tokens form a `[` `]` list literal.
+     * The lexer does not produce bracket tokens — `[]` is detected by checking
+     * for an Unknown token with value `[` followed by one with value `]`.
+     */
+    private checkListLiteral;
+    /**
+     * Returns true if the current two tokens form a `{` `}` map literal.
+     */
+    private checkMapLiteral;
+    /**
+     * Parses a system.* call expression appearing at the statement level
+     * (e.g. inside a module body or a uses block).
+     */
+    private parseSystemCall;
+    /**
+     * Emits a diagnostic at the given token's position.
+     */
+    private error;
+    /**
+     * Advances past tokens until a safe synchronisation point is found.
+     * Used after an unrecoverable parse error to resume at the next construct.
+     * Synchronisation points: top-level keyword, closing paren, or EOF.
+     */
+    private synchronise;
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"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"}