@words-lang/parser 0.1.0

package/dist/analyser/analyser.d.ts

@@ -0,0 +1,106 @@
+/**
+ * analyser.ts
+ *
+ * The WORDS semantic analyser. Walks the Workspace index and validates the
+ * rules that cannot be checked by the parser alone — rules that require
+ * cross-file knowledge of the full project.
+ *
+ * The analyser never reads files. It works entirely from the Workspace index
+ * built by `Workspace.load()`. All diagnostics are collected and returned
+ * as an array — nothing is thrown.
+ *
+ * Rules validated (first milestone):
+ *
+ *   A001 — Every module listed in system.modules has a ModuleNode definition.
+ *   A002 — Every state referenced in a when rule exists as a StateNode.
+ *   A003 — Every context referenced in a when rule exists as a ContextNode.
+ *   A004 — Every context in a state's returns has a when rule in the process.
+ *   A005 — Every state defined is reachable (referenced in a when rule or start).
+ *   A006 — state.return(x) in a screen references a context in the state's returns.
+ *   A007 — The module ownership declaration matches the construct's declared module.
+ */
+import { Workspace } from './workspace';
+import { Diagnostic } from './diagnostics';
+/**
+ * The value returned by `Analyser.analyse()`.
+ * Contains all semantic diagnostics collected across the project, annotated
+ * with the file path that produced each one.
+ */
+export interface AnalysisResult {
+    diagnostics: Array<{
+        filePath: string;
+        diagnostic: Diagnostic;
+    }>;
+}
+export declare class Analyser {
+    private workspace;
+    private diagnostics;
+    constructor(workspace: Workspace);
+    /**
+     * Runs all validation rules over the workspace index and returns the
+     * collected diagnostics. Never throws.
+     */
+    analyse(): AnalysisResult;
+    /**
+     * Every module listed in system.modules must have a corresponding ModuleNode.
+     * Reports on the system file using the module name token position.
+     */
+    private checkSystemModules;
+    /**
+     * For every when rule in every process:
+     * - The currentState must exist as a StateNode in the same module (A002)
+     * - The nextState must exist as a StateNode in the same module (A002)
+     * - The producedContext must exist as a ContextNode in the same module (A003)
+     */
+    private checkProcessRules;
+    /**
+     * For every state, every context listed in its returns clause must have
+     * a corresponding when rule in at least one of the module's processes.
+     */
+    private checkStateReturns;
+    /**
+     * Every state defined in a module must be either:
+     * - The module's start state, or
+     * - Referenced as the nextState in at least one when rule.
+     *
+     * States that are only currentState in when rules but never entered are
+     * considered unreachable entry points.
+     */
+    private checkStateReachability;
+    /**
+     * For every screen, for every state.return(contextName) call found in its
+     * uses tree, the contextName must appear in the enclosing state's returns.
+     *
+     * To find the enclosing state we look up which state uses this screen.
+     */
+    private checkScreenStateReturns;
+    /**
+     * Recursively walks a uses tree and validates every state.return() call.
+     */
+    private checkStateReturnsInUses;
+    /**
+     * Checks arguments for block expressions containing state.return() calls.
+     */
+    private checkStateReturnsInArgs;
+    /**
+     * For every file with an ownerModule declaration, every construct in that
+     * file must have its module field matching the ownerModule.
+     * (The module field is filled in by the Workspace during indexing.)
+     */
+    private checkOwnershipDeclarations;
+    /**
+     * Extracts all context names from a state's returns clause,
+     * handling both simple and expanded forms.
+     */
+    private extractReturnedContexts;
+    /**
+     * Finds the StateNode in `moduleName` that uses the given screen.
+     * Returns null if no state in the module uses this screen.
+     */
+    private findStateUsingScreen;
+    /**
+     * Emits a diagnostic at the position of the given token.
+     */
+    private report;
+}
+//# sourceMappingURL=analyser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analyser.d.ts","sourceRoot":"","sources":["../../src/analyser/analyser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EACH,UAAU,EAIb,MAAM,eAAe,CAAA;AActB;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC,CAAA;CACnE;AAID,qBAAa,QAAQ;IACjB,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,WAAW,CAA0D;gBAEjE,SAAS,EAAE,SAAS;IAMhC;;;OAGG;IACH,OAAO,IAAI,cAAc;IAezB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IA4CzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAyC9B;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA2B/B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAsBlC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;OAEG;IACH,OAAO,CAAC,MAAM;CAYjB"}

package/dist/analyser/analyser.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * analyser.ts
+ *
+ * The WORDS semantic analyser. Walks the Workspace index and validates the
+ * rules that cannot be checked by the parser alone — rules that require
+ * cross-file knowledge of the full project.
+ *
+ * The analyser never reads files. It works entirely from the Workspace index
+ * built by `Workspace.load()`. All diagnostics are collected and returned
+ * as an array — nothing is thrown.
+ *
+ * Rules validated (first milestone):
+ *
+ *   A001 — Every module listed in system.modules has a ModuleNode definition.
+ *   A002 — Every state referenced in a when rule exists as a StateNode.
+ *   A003 — Every context referenced in a when rule exists as a ContextNode.
+ *   A004 — Every context in a state's returns has a when rule in the process.
+ *   A005 — Every state defined is reachable (referenced in a when rule or start).
+ *   A006 — state.return(x) in a screen references a context in the state's returns.
+ *   A007 — The module ownership declaration matches the construct's declared module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analyser = void 0;
+const diagnostics_1 = require("./diagnostics");
+// ── Analyser ──────────────────────────────────────────────────────────────────
+class Analyser {
+    constructor(workspace) {
+        this.diagnostics = [];
+        this.workspace = workspace;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Runs all validation rules over the workspace index and returns the
+     * collected diagnostics. Never throws.
+     */
+    analyse() {
+        this.diagnostics = [];
+        this.checkSystemModules();
+        this.checkProcessRules();
+        this.checkStateReturns();
+        this.checkStateReachability();
+        this.checkScreenStateReturns();
+        this.checkOwnershipDeclarations();
+        return { diagnostics: this.diagnostics };
+    }
+    // ── Rule A001 — System modules have definitions ────────────────────────────
+    /**
+     * Every module listed in system.modules must have a corresponding ModuleNode.
+     * Reports on the system file using the module name token position.
+     */
+    checkSystemModules() {
+        const { system, systemFilePath } = this.workspace;
+        if (!system || !systemFilePath)
+            return;
+        for (const moduleName of system.modules) {
+            if (!this.workspace.modules.has(moduleName)) {
+                this.report(systemFilePath, diagnostics_1.DiagnosticCode.A_UNDEFINED_MODULE, `Module '${moduleName}' is listed in the system but has no definition`, system.token);
+            }
+        }
+    }
+    // ── Rules A002 + A003 — Process when rules reference valid constructs ───────
+    /**
+     * For every when rule in every process:
+     * - The currentState must exist as a StateNode in the same module (A002)
+     * - The nextState must exist as a StateNode in the same module (A002)
+     * - The producedContext must exist as a ContextNode in the same module (A003)
+     */
+    checkProcessRules() {
+        for (const [moduleName, moduleNode] of this.workspace.modules) {
+            const filePath = this.workspace.modulePaths.get(moduleName);
+            if (!filePath)
+                continue;
+            for (const process of moduleNode.processes) {
+                for (const rule of process.rules) {
+                    // Check currentState exists
+                    if (!this.workspace.getState(moduleName, rule.currentState)) {
+                        this.report(filePath, diagnostics_1.DiagnosticCode.A_UNDEFINED_STATE, `State '${rule.currentState}' referenced in process '${process.name}' is not defined in module '${moduleName}'`, rule.token);
+                    }
+                    // Check nextState exists
+                    if (!this.workspace.getState(moduleName, rule.nextState)) {
+                        this.report(filePath, diagnostics_1.DiagnosticCode.A_UNDEFINED_STATE, `State '${rule.nextState}' referenced in process '${process.name}' is not defined in module '${moduleName}'`, rule.token);
+                    }
+                    // Check producedContext exists
+                    if (!this.workspace.getContext(moduleName, rule.producedContext)) {
+                        this.report(filePath, diagnostics_1.DiagnosticCode.A_UNDEFINED_CONTEXT, `Context '${rule.producedContext}' referenced in process '${process.name}' is not defined in module '${moduleName}'`, rule.token);
+                    }
+                }
+            }
+        }
+    }
+    // ── Rule A004 — Every returned context has a when rule ─────────────────────
+    /**
+     * For every state, every context listed in its returns clause must have
+     * a corresponding when rule in at least one of the module's processes.
+     */
+    checkStateReturns() {
+        for (const [moduleName, stateMap] of this.workspace.states) {
+            const moduleNode = this.workspace.modules.get(moduleName);
+            if (!moduleNode)
+                continue;
+            // Build a set of all (currentState, producedContext) pairs covered by when rules
+            const coveredReturns = new Set();
+            for (const process of moduleNode.processes) {
+                for (const rule of process.rules) {
+                    coveredReturns.add(`${rule.currentState}::${rule.producedContext}`);
+                }
+            }
+            for (const [stateName, stateNode] of stateMap) {
+                const filePath = this.workspace.constructPaths.get(`${moduleName}/${stateName}`);
+                if (!filePath)
+                    continue;
+                const returnedContexts = this.extractReturnedContexts(stateNode);
+                for (const contextName of returnedContexts) {
+                    if (!coveredReturns.has(`${stateName}::${contextName}`)) {
+                        this.report(filePath, diagnostics_1.DiagnosticCode.A_UNHANDLED_RETURN, `Context '${contextName}' is listed in state '${stateName}' returns but has no corresponding when rule in module '${moduleName}'`, stateNode.token);
+                    }
+                }
+            }
+        }
+    }
+    // ── Rule A005 — Every state is reachable ───────────────────────────────────
+    /**
+     * Every state defined in a module must be either:
+     * - The module's start state, or
+     * - Referenced as the nextState in at least one when rule.
+     *
+     * States that are only currentState in when rules but never entered are
+     * considered unreachable entry points.
+     */
+    checkStateReachability() {
+        for (const [moduleName, stateMap] of this.workspace.states) {
+            const moduleNode = this.workspace.modules.get(moduleName);
+            if (!moduleNode)
+                continue;
+            // Collect all states that are entered (nextState in any when rule or start)
+            const reachable = new Set();
+            if (moduleNode.startState) {
+                reachable.add(moduleNode.startState);
+            }
+            for (const process of moduleNode.processes) {
+                for (const rule of process.rules) {
+                    reachable.add(rule.nextState);
+                }
+            }
+            // Also collect all states referenced in implements branches
+            for (const impl of moduleNode.implements) {
+                for (const branch of impl.branches) {
+                    reachable.add(branch.targetState);
+                }
+            }
+            for (const [stateName] of stateMap) {
+                if (!reachable.has(stateName)) {
+                    const filePath = this.workspace.constructPaths.get(`${moduleName}/${stateName}`);
+                    if (!filePath)
+                        continue;
+                    const stateNode = stateMap.get(stateName);
+                    this.report(filePath, diagnostics_1.DiagnosticCode.A_UNREACHABLE_STATE, `State '${stateName}' in module '${moduleName}' is never entered — it is not the start state and no when rule transitions into it`, stateNode.token);
+                }
+            }
+        }
+    }
+    // ── Rule A006 — state.return() references valid contexts ──────────────────
+    /**
+     * For every screen, for every state.return(contextName) call found in its
+     * uses tree, the contextName must appear in the enclosing state's returns.
+     *
+     * To find the enclosing state we look up which state uses this screen.
+     */
+    checkScreenStateReturns() {
+        for (const [moduleName, screenMap] of this.workspace.screens) {
+            for (const [screenName, screenNode] of screenMap) {
+                const filePath = this.workspace.constructPaths.get(`${moduleName}/${screenName}`);
+                if (!filePath)
+                    continue;
+                // Find the state that uses this screen
+                const enclosingState = this.findStateUsingScreen(moduleName, screenName);
+                if (!enclosingState)
+                    continue;
+                const validReturns = new Set(this.extractReturnedContexts(enclosingState));
+                // Walk the screen's uses tree and check every state.return()
+                this.checkStateReturnsInUses(screenNode.uses, validReturns, filePath, screenNode);
+            }
+        }
+    }
+    /**
+     * Recursively walks a uses tree and validates every state.return() call.
+     */
+    checkStateReturnsInUses(uses, validReturns, filePath, screenNode) {
+        for (const entry of uses) {
+            if (entry.kind === 'ComponentUse') {
+                this.checkStateReturnsInArgs(entry.args, validReturns, filePath);
+                this.checkStateReturnsInUses(entry.uses, validReturns, filePath, screenNode);
+            }
+            else if (entry.kind === 'ConditionalBlock') {
+                this.checkStateReturnsInUses(entry.body, validReturns, filePath, screenNode);
+            }
+            else if (entry.kind === 'IterationBlock') {
+                this.checkStateReturnsInUses(entry.body, validReturns, filePath, screenNode);
+            }
+        }
+    }
+    /**
+     * Checks arguments for block expressions containing state.return() calls.
+     */
+    checkStateReturnsInArgs(args, validReturns, filePath) {
+        for (const arg of args) {
+            if (arg.value.kind === 'BlockExpression') {
+                const block = arg.value;
+                for (const stmt of block.statements) {
+                    if (stmt.kind === 'StateReturnStatement') {
+                        const returnStmt = stmt;
+                        if (!validReturns.has(returnStmt.contextName)) {
+                            this.report(filePath, diagnostics_1.DiagnosticCode.A_INVALID_STATE_RETURN, `state.return('${returnStmt.contextName}') does not match any context in the enclosing state's returns clause`, returnStmt.token);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // ── Rule A007 — Ownership declarations match construct modules ─────────────
+    /**
+     * For every file with an ownerModule declaration, every construct in that
+     * file must have its module field matching the ownerModule.
+     * (The module field is filled in by the Workspace during indexing.)
+     */
+    checkOwnershipDeclarations() {
+        for (const [filePath, record] of this.workspace.files) {
+            const doc = record.parseResult.document;
+            if (!doc.ownerModule)
+                continue;
+            for (const node of doc.nodes) {
+                if (!('module' in node))
+                    continue;
+                const nodeModule = node.module;
+                if (nodeModule && nodeModule !== doc.ownerModule) {
+                    this.report(filePath, diagnostics_1.DiagnosticCode.A_MODULE_MISMATCH, `Construct declares module '${nodeModule}' but the ownership declaration says '${doc.ownerModule}'`, node.token);
+                }
+            }
+        }
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    /**
+     * Extracts all context names from a state's returns clause,
+     * handling both simple and expanded forms.
+     */
+    extractReturnedContexts(stateNode) {
+        if (!stateNode.returns)
+            return [];
+        if (stateNode.returns.kind === 'SimpleReturns') {
+            return stateNode.returns.contexts;
+        }
+        if (stateNode.returns.kind === 'ExpandedReturns') {
+            return stateNode.returns.entries.map(e => e.contextName);
+        }
+        return [];
+    }
+    /**
+     * Finds the StateNode in `moduleName` that uses the given screen.
+     * Returns null if no state in the module uses this screen.
+     */
+    findStateUsingScreen(moduleName, screenName) {
+        const stateMap = this.workspace.states.get(moduleName);
+        if (!stateMap)
+            return null;
+        for (const [, stateNode] of stateMap) {
+            for (const entry of stateNode.uses) {
+                if (entry.kind === 'ComponentUse' &&
+                    entry.componentKind === 'screen' &&
+                    (entry.name.parts.length === 1
+                        ? entry.name.parts[0] === screenName
+                        : entry.name.parts[entry.name.parts.length - 1] === screenName)) {
+                    return stateNode;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Emits a diagnostic at the position of the given token.
+     */
+    report(filePath, code, message, token) {
+        const range = (0, diagnostics_1.rangeFromToken)(token.line, token.column, token.value.length || 1);
+        this.diagnostics.push({
+            filePath,
+            diagnostic: (0, diagnostics_1.analyserDiagnostic)(code, message, 'error', range),
+        });
+    }
+}
+exports.Analyser = Analyser;
+//# sourceMappingURL=analyser.js.map

package/dist/analyser/analyser.js.map

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

package/dist/analyser/diagnostics.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+/**
+ * The severity of a diagnostic.
+ *
+ * `error`   — the source is invalid and cannot produce a correct implementation.
+ *             e.g. a `when` rule referencing a state that has no definition.
+ * `warning` — the source is valid but likely wrong or incomplete.
+ *             e.g. a process narrative omitted where one is strongly recommended.
+ * `hint`    — a stylistic or structural suggestion.
+ *             e.g. a module with no description.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'hint';
+/**
+ * A zero-based line and character position in the source.
+ * Matches the LSP `Position` type so diagnostics can be forwarded
+ * to VS Code without translation.
+ */
+export interface Position {
+    /** Zero-based line number. */
+    line: number;
+    /** Zero-based character offset within the line. */
+    character: number;
+}
+/**
+ * A start-inclusive, end-exclusive range in the source.
+ * Matches the LSP `Range` type.
+ */
+export interface Range {
+    start: Position;
+    end: Position;
+}
+/**
+ * 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
+ */
+export declare enum DiagnosticCode {
+    /** An unexpected token was encountered where a specific token was required. */
+    P_UNEXPECTED_TOKEN = "P001",
+    /** The source ended before the construct was complete. */
+    P_UNEXPECTED_EOF = "P002",
+    /** An opening `(` was not matched by a closing `)`. */
+    P_UNCLOSED_PAREN = "P003",
+    /** A string literal was opened with `"` but never closed. */
+    P_UNCLOSED_STRING = "P004",
+    /** A construct keyword was found in a position where it is not valid. */
+    P_INVALID_CONSTRUCT_POSITION = "P005",
+    /** A `when` rule is missing its `enter` clause. */
+    P_MISSING_ENTER = "P006",
+    /** A `when` rule is missing its `returns` clause. */
+    P_MISSING_RETURNS = "P007",
+    /** A type annotation `(Type)` was expected but not found. */
+    P_MISSING_TYPE = "P008",
+    /** An identifier (PascalCase or camelCase) was expected but not found. */
+    P_MISSING_IDENTIFIER = "P009",
+    /** An `is` keyword was expected in an argument assignment but not found. */
+    P_MISSING_IS = "P010",
+    /**
+     * A state referenced in a `when` rule or `start` declaration has no
+     * corresponding state definition in the module's directory.
+     */
+    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.
+     */
+    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.
+     */
+    A_UNHANDLED_RETURN = "A003",
+    /**
+     * A state is defined but never referenced in any process `when` rule
+     * and is not the module's `start` state.
+     */
+    A_UNREACHABLE_STATE = "A004",
+    /**
+     * A module listed in the system's `modules` block has no corresponding
+     * module definition file.
+     */
+    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.
+     */
+    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.
+     */
+    A_MODULE_MISMATCH = "A007",
+    /**
+     * A `state.return(contextName)` call references a context name that does
+     * not appear in the enclosing state's `returns` clause.
+     */
+    A_INVALID_STATE_RETURN = "A008",
+    /**
+     * An `implements` block references a handler interface that is not declared
+     * in the named module.
+     */
+    A_UNDEFINED_INTERFACE = "A009",
+    /**
+     * A `when` rule has no transition narrative.
+     * Narratives are optional but strongly recommended for readability.
+     */
+    W_MISSING_NARRATIVE = "W001",
+    /**
+     * A construct has no description string.
+     * Descriptions are optional but recommended for documentation.
+     */
+    W_MISSING_DESCRIPTION = "W002",
+    /**
+     * 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.
+     */
+    H_EMPTY_USES = "H001"
+}
+/**
+ * A single diagnostic produced by the parser or analyser.
+ *
+ * `code`     — the diagnostic code, used by the LSP to deduplicate and
+ *              provide quick-fix suggestions.
+ * `message`  — a human-readable explanation of the problem.
+ * `severity` — how serious the problem is.
+ * `range`    — the source range to underline in the editor. Derived from
+ *              the offending token's line, column, and value length.
+ * `source`   — identifies which layer produced the diagnostic:
+ *              `'parser'` for structural problems, `'analyser'` for semantic ones.
+ */
+export interface Diagnostic {
+    code: DiagnosticCode;
+    message: string;
+    severity: DiagnosticSeverity;
+    range: Range;
+    source: 'parser' | 'analyser';
+}
+/**
+ * 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.
+ */
+export declare function rangeFromToken(line: number, column: number, length: number): Range;
+/**
+ * Creates a parser-layer Diagnostic.
+ */
+export declare function parseDiagnostic(code: DiagnosticCode, message: string, severity: DiagnosticSeverity, range: Range): Diagnostic;
+/**
+ * Creates an analyser-layer Diagnostic.
+ */
+export declare function analyserDiagnostic(code: DiagnosticCode, message: string, severity: DiagnosticSeverity, range: Range): Diagnostic;
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/analyser/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAI7D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACrB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IAClB,KAAK,EAAE,QAAQ,CAAA;IACf,GAAG,EAAE,QAAQ,CAAA;CAChB;AAID;;;;;;;GAOG;AACH,oBAAY,cAAc;IAItB,+EAA+E;IAC/E,kBAAkB,SAAS;IAE3B,0DAA0D;IAC1D,gBAAgB,SAAS;IAEzB,uDAAuD;IACvD,gBAAgB,SAAS;IAEzB,6DAA6D;IAC7D,iBAAiB,SAAS;IAE1B,yEAAyE;IACzE,4BAA4B,SAAS;IAErC,mDAAmD;IACnD,eAAe,SAAS;IAExB,qDAAqD;IACrD,iBAAiB,SAAS;IAE1B,6DAA6D;IAC7D,cAAc,SAAS;IAEvB,0EAA0E;IAC1E,oBAAoB,SAAS;IAE7B,4EAA4E;IAC5E,YAAY,SAAS;IAIrB;;;OAGG;IACH,iBAAiB,SAAS;IAE1B;;;OAGG;IACH,mBAAmB,SAAS;IAE5B;;;OAGG;IACH,kBAAkB,SAAS;IAE3B;;;OAGG;IACH,mBAAmB,SAAS;IAE5B;;;OAGG;IACH,kBAAkB,SAAS;IAE3B;;;;OAIG;IACH,qBAAqB,SAAS;IAE9B;;;OAGG;IACH,iBAAiB,SAAS;IAE1B;;;OAGG;IACH,sBAAsB,SAAS;IAE/B;;;OAGG;IACH,qBAAqB,SAAS;IAI9B;;;OAGG;IACH,mBAAmB,SAAS;IAE5B;;;OAGG;IACH,qBAAqB,SAAS;IAI9B;;;;OAIG;IACH,YAAY,SAAS;CACxB;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,cAAc,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAA;CAChC;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAKlF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,KAAK,GACb,UAAU,CAEZ;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,KAAK,GACb,UAAU,CAEZ"}