@words-lang/parser 0.1.0

package/dist/analyser/diagnostics.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * diagnostics.ts
+ *
+ * Defines the Diagnostic type returned by the parser and analyser.
+ * Diagnostics are never thrown — they are collected and returned alongside
+ * the AST so the caller always receives the fullest possible picture of
+ * what the source contains, even when it is malformed.
+ *
+ * The LSP server maps these directly to VS Code diagnostics, using the
+ * `range` to underline the offending token in the editor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticCode = void 0;
+exports.rangeFromToken = rangeFromToken;
+exports.parseDiagnostic = parseDiagnostic;
+exports.analyserDiagnostic = analyserDiagnostic;
+// ── Diagnostic codes ──────────────────────────────────────────────────────────
+/**
+ * Every diagnostic code the parser and analyser can produce.
+ * Codes are namespaced by layer:
+ *   P_* — parse errors (structural / syntactic problems)
+ *   A_* — analyser errors (semantic problems)
+ *   W_* — warnings
+ *   H_* — hints
+ */
+var DiagnosticCode;
+(function (DiagnosticCode) {
+    // ── Parse errors ────────────────────────────────────────────────────────────
+    /** An unexpected token was encountered where a specific token was required. */
+    DiagnosticCode["P_UNEXPECTED_TOKEN"] = "P001";
+    /** The source ended before the construct was complete. */
+    DiagnosticCode["P_UNEXPECTED_EOF"] = "P002";
+    /** An opening `(` was not matched by a closing `)`. */
+    DiagnosticCode["P_UNCLOSED_PAREN"] = "P003";
+    /** A string literal was opened with `"` but never closed. */
+    DiagnosticCode["P_UNCLOSED_STRING"] = "P004";
+    /** A construct keyword was found in a position where it is not valid. */
+    DiagnosticCode["P_INVALID_CONSTRUCT_POSITION"] = "P005";
+    /** A `when` rule is missing its `enter` clause. */
+    DiagnosticCode["P_MISSING_ENTER"] = "P006";
+    /** A `when` rule is missing its `returns` clause. */
+    DiagnosticCode["P_MISSING_RETURNS"] = "P007";
+    /** A type annotation `(Type)` was expected but not found. */
+    DiagnosticCode["P_MISSING_TYPE"] = "P008";
+    /** An identifier (PascalCase or camelCase) was expected but not found. */
+    DiagnosticCode["P_MISSING_IDENTIFIER"] = "P009";
+    /** An `is` keyword was expected in an argument assignment but not found. */
+    DiagnosticCode["P_MISSING_IS"] = "P010";
+    // ── Analyser errors ─────────────────────────────────────────────────────────
+    /**
+     * A state referenced in a `when` rule or `start` declaration has no
+     * corresponding state definition in the module's directory.
+     */
+    DiagnosticCode["A_UNDEFINED_STATE"] = "A001";
+    /**
+     * A context referenced in a `when` rule, `receives`, or `returns` clause
+     * has no corresponding context definition in the module's directory.
+     */
+    DiagnosticCode["A_UNDEFINED_CONTEXT"] = "A002";
+    /**
+     * A context listed in a state's `returns` block has no corresponding
+     * `when` rule in any of the module's processes.
+     */
+    DiagnosticCode["A_UNHANDLED_RETURN"] = "A003";
+    /**
+     * A state is defined but never referenced in any process `when` rule
+     * and is not the module's `start` state.
+     */
+    DiagnosticCode["A_UNREACHABLE_STATE"] = "A004";
+    /**
+     * A module listed in the system's `modules` block has no corresponding
+     * module definition file.
+     */
+    DiagnosticCode["A_UNDEFINED_MODULE"] = "A005";
+    /**
+     * A component referenced by qualified name (e.g. `UIModule.LoginForm`)
+     * cannot be resolved — either the module does not exist or the component
+     * is not defined within it.
+     */
+    DiagnosticCode["A_UNDEFINED_COMPONENT"] = "A006";
+    /**
+     * The owning module declared at the top of a component file (e.g.
+     * `module AuthModule`) does not match the module the construct names itself.
+     */
+    DiagnosticCode["A_MODULE_MISMATCH"] = "A007";
+    /**
+     * A `state.return(contextName)` call references a context name that does
+     * not appear in the enclosing state's `returns` clause.
+     */
+    DiagnosticCode["A_INVALID_STATE_RETURN"] = "A008";
+    /**
+     * An `implements` block references a handler interface that is not declared
+     * in the named module.
+     */
+    DiagnosticCode["A_UNDEFINED_INTERFACE"] = "A009";
+    // ── Warnings ────────────────────────────────────────────────────────────────
+    /**
+     * A `when` rule has no transition narrative.
+     * Narratives are optional but strongly recommended for readability.
+     */
+    DiagnosticCode["W_MISSING_NARRATIVE"] = "W001";
+    /**
+     * A construct has no description string.
+     * Descriptions are optional but recommended for documentation.
+     */
+    DiagnosticCode["W_MISSING_DESCRIPTION"] = "W002";
+    // ── Hints ────────────────────────────────────────────────────────────────────
+    /**
+     * A state has no `uses` block — it is a transient state that holds a
+     * position in the process map while something external resolves.
+     * This is valid but worth flagging so the designer is aware.
+     */
+    DiagnosticCode["H_EMPTY_USES"] = "H001";
+})(DiagnosticCode || (exports.DiagnosticCode = DiagnosticCode = {}));
+// ── Convenience constructors ──────────────────────────────────────────────────
+/**
+ * Creates a Range from a 1-based line and column and the length of the
+ * offending text. Converts to the zero-based LSP convention internally.
+ */
+function rangeFromToken(line, column, length) {
+    return {
+        start: { line: line - 1, character: column - 1 },
+        end: { line: line - 1, character: column - 1 + length },
+    };
+}
+/**
+ * Creates a parser-layer Diagnostic.
+ */
+function parseDiagnostic(code, message, severity, range) {
+    return { code, message, severity, range, source: 'parser' };
+}
+/**
+ * Creates an analyser-layer Diagnostic.
+ */
+function analyserDiagnostic(code, message, severity, range) {
+    return { code, message, severity, range, source: 'analyser' };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/analyser/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/analyser/diagnostics.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAgMH,wCAKC;AAKD,0CAOC;AAKD,gDAOC;AAtLD,iFAAiF;AAEjF;;;;;;;GAOG;AACH,IAAY,cAiHX;AAjHD,WAAY,cAAc;IAEtB,+EAA+E;IAE/E,+EAA+E;IAC/E,6CAA2B,CAAA;IAE3B,0DAA0D;IAC1D,2CAAyB,CAAA;IAEzB,uDAAuD;IACvD,2CAAyB,CAAA;IAEzB,6DAA6D;IAC7D,4CAA0B,CAAA;IAE1B,yEAAyE;IACzE,uDAAqC,CAAA;IAErC,mDAAmD;IACnD,0CAAwB,CAAA;IAExB,qDAAqD;IACrD,4CAA0B,CAAA;IAE1B,6DAA6D;IAC7D,yCAAuB,CAAA;IAEvB,0EAA0E;IAC1E,+CAA6B,CAAA;IAE7B,4EAA4E;IAC5E,uCAAqB,CAAA;IAErB,+EAA+E;IAE/E;;;OAGG;IACH,4CAA0B,CAAA;IAE1B;;;OAGG;IACH,8CAA4B,CAAA;IAE5B;;;OAGG;IACH,6CAA2B,CAAA;IAE3B;;;OAGG;IACH,8CAA4B,CAAA;IAE5B;;;OAGG;IACH,6CAA2B,CAAA;IAE3B;;;;OAIG;IACH,gDAA8B,CAAA;IAE9B;;;OAGG;IACH,4CAA0B,CAAA;IAE1B;;;OAGG;IACH,iDAA+B,CAAA;IAE/B;;;OAGG;IACH,gDAA8B,CAAA;IAE9B,+EAA+E;IAE/E;;;OAGG;IACH,8CAA4B,CAAA;IAE5B;;;OAGG;IACH,gDAA8B,CAAA;IAE9B,gFAAgF;IAEhF;;;;OAIG;IACH,uCAAqB,CAAA;AACzB,CAAC,EAjHW,cAAc,8BAAd,cAAc,QAiHzB;AAwBD,iFAAiF;AAEjF;;;GAGG;AACH,SAAgB,cAAc,CAAC,IAAY,EAAE,MAAc,EAAE,MAAc;IACvE,OAAO;QACH,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC,EAAE;QAChD,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC,GAAG,MAAM,EAAE;KAC1D,CAAA;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC3B,IAAoB,EACpB,OAAe,EACf,QAA4B,EAC5B,KAAY;IAEZ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;AAC/D,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAC9B,IAAoB,EACpB,OAAe,EACf,QAA4B,EAC5B,KAAY;IAEZ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;AACjE,CAAC"}

package/dist/analyser/workspace.d.ts

@@ -0,0 +1,198 @@
+/**
+ * workspace.ts
+ *
+ * The Workspace scans a WORDS project directory, parses every `.wds` file it
+ * finds, and builds a cross-file index of all constructs organised by module.
+ *
+ * The index is the shared data structure consumed by the Analyser and later
+ * by the LSP server for go-to-definition and find-references. Neither the
+ * Analyser nor the LSP reads files directly — they always go through the
+ * Workspace.
+ *
+ * Design principles:
+ *
+ * - One parse per file. The Workspace caches parse results so the Analyser
+ *   can query the index repeatedly without re-parsing.
+ *
+ * - Flat index structure. Constructs are indexed by module name and construct
+ *   name so lookups are O(1) rather than requiring a tree walk.
+ *
+ * - Parse errors are preserved. Files that fail to parse partially are still
+ *   indexed — whatever nodes were recovered are included. Parse diagnostics
+ *   are stored alongside the index and returned with analyser diagnostics.
+ *
+ * - The Workspace is synchronous. File I/O uses Node's `fs` module directly.
+ *   The LSP layer wraps this in async when needed.
+ */
+import { ParseResult } from '../parser/parser';
+import { SystemNode, ModuleNode, StateNode, ContextNode, ScreenNode, ViewNode, ProviderNode, AdapterNode, InterfaceNode } from '../parser/ast';
+import { Diagnostic } from './diagnostics';
+/**
+ * A map from construct name to node, scoped to one module.
+ * e.g. states.get('AuthModule')?.get('Unauthenticated') → StateNode
+ */
+type ConstructMap<T> = Map<string, T>;
+/**
+ * A map from module name to a per-module construct map.
+ */
+type ModuleIndex<T> = Map<string, ConstructMap<T>>;
+/**
+ * Everything the Workspace knows about a single `.wds` file.
+ *
+ * `filePath`    — absolute path to the file on disk.
+ * `source`      — raw source text read from disk.
+ * `parseResult` — the result of parsing the source, including the document
+ *                 AST and any parse-layer diagnostics.
+ */
+export interface FileRecord {
+    filePath: string;
+    source: string;
+    parseResult: ParseResult;
+}
+/**
+ * The cross-file index of a WORDS project.
+ *
+ * Built by calling `Workspace.load(projectRoot)`. Consumers query the index
+ * directly via the public maps — there are no query methods, just data.
+ */
+export declare class Workspace {
+    /** Absolute path to the project root directory. */
+    readonly projectRoot: string;
+    /**
+     * All parsed files, keyed by absolute file path.
+     * Includes both successfully parsed files and files with parse errors.
+     */
+    readonly files: Map<string, FileRecord>;
+    /**
+     * All parse-layer diagnostics collected across all files.
+     * Indexed by absolute file path.
+     */
+    readonly parseDiagnostics: Map<string, Diagnostic[]>;
+    /**
+     * The single system declaration found in the project.
+     * Null if no system file was found or if it failed to parse.
+     */
+    system: SystemNode | null;
+    /**
+     * The file path of the system declaration, for diagnostic reporting.
+     */
+    systemFilePath: string | null;
+    /**
+     * All module definitions, keyed by module name.
+     * e.g. modules.get('AuthModule') → ModuleNode
+     */
+    readonly modules: Map<string, ModuleNode>;
+    /**
+     * File path of each module definition, for diagnostic reporting.
+     * e.g. modulePaths.get('AuthModule') → '/project/AuthModule/AuthModule.wds'
+     */
+    readonly modulePaths: Map<string, string>;
+    /**
+     * All state definitions, keyed by module name then state name.
+     * e.g. states.get('AuthModule')?.get('Unauthenticated') → StateNode
+     */
+    readonly states: ModuleIndex<StateNode>;
+    /**
+     * All context definitions, keyed by module name then context name.
+     */
+    readonly contexts: ModuleIndex<ContextNode>;
+    /**
+     * All screen definitions, keyed by module name then screen name.
+     */
+    readonly screens: ModuleIndex<ScreenNode>;
+    /**
+     * All view definitions, keyed by module name then view name.
+     */
+    readonly views: ModuleIndex<ViewNode>;
+    /**
+     * All provider definitions, keyed by module name then provider name.
+     */
+    readonly providers: ModuleIndex<ProviderNode>;
+    /**
+     * All adapter definitions, keyed by module name then adapter name.
+     */
+    readonly adapters: ModuleIndex<AdapterNode>;
+    /**
+     * All interface component definitions, keyed by module name then interface name.
+     */
+    readonly interfaces: ModuleIndex<InterfaceNode>;
+    /**
+     * File path of each construct, for go-to-definition.
+     * Key format: 'ModuleName/ConstructName' (e.g. 'AuthModule/Unauthenticated')
+     */
+    readonly constructPaths: Map<string, string>;
+    private constructor();
+    /**
+     * Scans `projectRoot` recursively for `.wds` files, parses each one,
+     * and returns a fully populated Workspace.
+     *
+     * Never throws — files that cannot be read or parsed are recorded with
+     * their errors and skipped during indexing.
+     */
+    static load(projectRoot: string): Workspace;
+    /**
+     * Reloads a single file and rebuilds the index.
+     * Used by the LSP server when a file changes on disk.
+     */
+    reload(filePath: string): void;
+    /**
+     * Returns the StateNode for the given module and state name, or null.
+     */
+    getState(moduleName: string, stateName: string): StateNode | null;
+    /**
+     * Returns the ContextNode for the given module and context name, or null.
+     */
+    getContext(moduleName: string, contextName: string): ContextNode | null;
+    /**
+     * Returns the ScreenNode for the given module and screen name, or null.
+     */
+    getScreen(moduleName: string, screenName: string): ScreenNode | null;
+    /**
+     * Returns the ViewNode for the given module and view name, or null.
+     * Also searches other modules if moduleName is null.
+     */
+    getView(moduleName: string, viewName: string): ViewNode | null;
+    /**
+     * Returns all parse diagnostics across all files as a flat array,
+     * each annotated with the file path that produced it.
+     */
+    allParseDiagnostics(): Array<{
+        filePath: string;
+        diagnostic: Diagnostic;
+    }>;
+    /**
+     * Reads and parses a single `.wds` file, storing the result in `this.files`.
+     * Silently records any read error as a parse diagnostic.
+     */
+    private loadFile;
+    /**
+     * Recursively finds all `.wds` files under `dir`.
+     * Skips `node_modules` and hidden directories.
+     */
+    private findWdsFiles;
+    /**
+     * Clears all index maps. Called before a rebuild.
+     */
+    private clearIndex;
+    /**
+     * Walks all parsed documents and populates the index maps.
+     * Called once after all files are loaded, and again after each reload.
+     */
+    private buildIndex;
+    /**
+     * Indexes all top-level nodes in a single document into the appropriate maps.
+     */
+    private indexDocument;
+    /**
+     * Indexes a single top-level node into the appropriate map.
+     * Uses `ownerModule` from the ownership declaration if the node's own
+     * `module` field is empty (component files).
+     */
+    private indexNode;
+    /**
+     * Ensures a per-module map exists for the given module name.
+     */
+    private ensureModuleMap;
+}
+export {};
+//# sourceMappingURL=workspace.d.ts.map

package/dist/analyser/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/analyser/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,EAAU,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,EACH,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EAGhB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAI1C;;;GAGG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAErC;;GAEG;AACH,KAAK,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAIlD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,WAAW,CAAA;CAC3B;AAID;;;;;GAKG;AACH,qBAAa,SAAS;IAClB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAY;IAEnD;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAY;IAEhE;;;OAGG;IACH,MAAM,EAAE,UAAU,GAAG,IAAI,CAAO;IAEhC;;OAEG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAO;IAEpC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAY;IAErD;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAY;IAErD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAY;IAEnD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,WAAW,CAAC,CAAY;IAEvD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAAU,CAAC,CAAY;IAErD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAY;IAEjD;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC,CAAY;IAEzD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,WAAW,CAAC,CAAY;IAEvD;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,aAAa,CAAC,CAAY;IAE3D;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAY;IAExD,OAAO;IAMP;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS;IAY3C;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIjE;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAIvE;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIpE;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAI9D;;;OAGG;IACH,mBAAmB,IAAI,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC;IAY1E;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA2BhB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA4BpB;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAoBlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAiFjB;;OAEG;IACH,OAAO,CAAC,eAAe;CAK1B"}