# thisisthedarshan/pss-langserver architecture

> Architecture diagram of the GitHub repository thisisthedarshan/pss-langserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thisisthedarshan/pss-langserver
- Repository: https://github.com/thisisthedarshan/pss-langserver

## Overview

##### Project type and purpose
- This is a language-server implementation (an open-source tool) written in TypeScript/Node.js that implements the Language Server Protocol (LSP) for the Accellera Portable Stimulus Standard (PSS).
- Its purpose is to parse PSS source files, build an AST, and expose language-aware features (completion, hover, diagnostics, formatting, go-to) to any LSP-compatible IDE.

##### File structure
Top-level:
- src/pss-langserver.ts – entry point that sets up the LSP connection and registers feature handlers.
- src/grammar/… – ANTLR4 grammar definitions (.g4) and generated TS lexer/parser/visitor/listener.
- src/parser/… – custom AST nodes, advanced visitors, helper functions, the core parse+AST pipeline.
- src/providers/… – modules for each LSP feature: completion, hover, goto, formatting, semantic tokens, comments.
- src/definitions/… – static definitions for keywords, types, functions, data-structures, semantic tokens.
- scripts & configs – make-exec.js, genbuild.js, ANTLR jar, tsconfig.json, package.json, build/test scripts.

##### README for additional insights
- It describes planned/in-progress features: Syntax Analysis, Code Completion, Signature Help, Diagnostics, Hover Documentation, Embedded Code Support.
- It confirms NodeJS/TypeScript stack, LSP protocol usage, and IDE setup instructions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External IDE
    subgraph "IDE"
        IDE["IDE (VSCode, etc.)"]:::external
    end

    %% Language Server
    subgraph "Language Server"
        %% Pre-build / Codegen
        subgraph "Pre-build / Codegen"
            ANTLR_JAR["antlr.jar"]:::tool
            GenBuild["genbuild.js"]:::tool
            MakeExec["make-exec.js"]:::tool
            Makefile["Makefile"]:::tool
        end

        %% Runtime
        subgraph "Runtime"
            Launcher["CLI / Server Launcher\n(pss-langserver.ts)"]:::runtime
            Transport["LSP Transport Layer\n(vscode-languageserver)"]:::transport
        end

        %% Parsing Pipeline
        subgraph "Parsing Pipeline"
            Grammar["ANTLR Grammar Definitions\n(.g4 files)"]:::grammar
            subgraph "Generated Lexer & Parser"
                PSS_TS["pss.ts"]:::grammar
                PSS_LEX["pssLex.ts"]:::grammar
                PSS_LIST["pssListener.ts"]:::grammar
                PSS_VIS["pssVisitor.ts"]:::grammar
                DOXY_PRS["doxygenParser.ts"]:::grammar
                DOXY_LEX["doxygenLexer.ts"]:::grammar
                DOXY_LIST["doxygenParserListener.ts"]:::grammar
                DOXY_VIS["doxygenParserVisitor.ts"]:::grammar
            end
            ASTModel["AST & Semantic Model"]:::model
            subgraph "Parser Helpers & Utilities"
                AST_HELPERS["helpers.ts"]:::model
                PARSER_HELPERS["src/parser/helpers.ts"]:::model
                COMMENT_PARSERS["src/parser/commentParsers.ts"]:::model
                LISTENER_TS["src/parser/listener.ts"]:::model
                WORKER_TS["src/parser/worker.ts"]:::model
                ADV_VISITOR["src/parser/advancedVisitor.ts"]:::model
                VISITORS_TS["src/parser/visitors.ts"]:::model
                TYPE_GUARDS["src/parser/typeGuards.ts"]:::model
            end
        end

        %% Feature Providers
        subgraph "Feature Providers"
            CP["CompletionProvider"]:::feature
            HO["HoverProvider"]:::feature
            GT["Go-To Definition Provider"]:::feature
            FP["FormattingProvider"]:::feature
            ST["SemanticTokenProvider"]:::feature
            OC["ObjectCommentsProvider"]:::feature
        end

        %% Definitions
        Definitions["Definitions Repository"]:::definitions
    end

    %% Connections IDE <-> Server
    IDE -->|"LSP Requests\n(textDocument/didOpen,\ncompletion, hover,\nformatting, diagnostics)"| Transport
    Transport -->|"initializes"| Launcher
    Launcher -->|"on startup"| Grammar

    %% Pre-build to Generated
    ANTLR_JAR -->|"used by"| GenBuild
    GenBuild -->|"generates"| PSS_TS
    GenBuild --> PSS_LEX
    GenBuild --> PSS_LIST
    GenBuild --> PSS_VIS
    GenBuild --> DOXY_PRS
    GenBuild --> DOXY_LEX
    GenBuild --> DOXY_LIST
    GenBuild --> DOXY_VIS

    %% Runtime to Parsing Pipeline
    Launcher -->|"spawns"| Transport
    Launcher -->|"builds parser"| Grammar
    Grammar -->|"feeds grammar"| PSS_TS
    PSS_TS -->|"parses text"| ASTModel
    PSS_LEX --> ASTModel
    DOXY_PRS --> ASTModel
    DOXY_LEX --> ASTModel

    ASTModel -->|"uses"| PARSER_HELPERS
    ASTModel -->|"constructs AST"| ADV_VISITOR
    ASTModel -->|"constructs AST"| VISITORS_TS

    %% Providers consume AST and Definitions
    ASTModel -->|"AST input"| CP
    ASTModel --> HO
    ASTModel --> GT
    ASTModel --> FP
    ASTModel --> ST
    ASTModel --> OC

    Definitions --> CP
    Definitions --> HO
    Definitions --> GT
    Definitions --> FP
    Definitions --> ST
    Definitions --> OC

    %% Providers respond via Transport
    CP -->|"completion lists"| Transport
    HO -->|"hover info"| Transport
    GT -->|"definition locations"| Transport
    FP -->|"formatted text"| Transport
    ST -->|"semantic tokens"| Transport
    OC -->|"comment objects"| Transport

    %% Click Events
    click Launcher "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/pss-langserver.ts"
    click Transport "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/pss-langserver.ts"
    click Grammar "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/antlr/*.g4"
    click PSS_TS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/pss.ts"
    click PSS_LEX "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/pssLex.ts"
    click PSS_LIST "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/pssListener.ts"
    click PSS_VIS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/pssVisitor.ts"
    click DOXY_PRS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/doxygenParser.ts"
    click DOXY_LEX "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/doxygenLexer.ts"
    click DOXY_LIST "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/doxygenParserListener.ts"
    click DOXY_VIS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/grammar/doxygenParserVisitor.ts"
    click ADV_VISITOR "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/advancedVisitor.ts"
    click VISITORS_TS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/visitors.ts"
    click TYPE_GUARDS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/typeGuards.ts"
    click PARSER_HELPERS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/helpers.ts"
    click AST_HELPERS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/helpers.ts"
    click COMMENT_PARSERS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/commentParsers.ts"
    click LISTENER_TS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/listener.ts"
    click WORKER_TS "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/parser/worker.ts"
    click CP "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/autoCompletionProvider.ts"
    click HO "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/hoverProvider.ts"
    click GT "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/gotoProvider.ts"
    click FP "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/formattingProvider.ts"
    click ST "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/semanticTokenProvider.ts"
    click OC "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/providers/objectCommentsProvider.ts"
    click Definitions "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/definitions/keywords.ts"
    click Definitions "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/definitions/dataTypes.ts"
    click Definitions "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/definitions/dataStructures.ts"
    click Definitions "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/definitions/builtinFunctions.ts"
    click Definitions "https://github.com/thisisthedarshan/pss-langserver/blob/main/src/definitions/semanticTokenDefinitions.ts"
    click ANTLR_JAR "https://github.com/thisisthedarshan/pss-langserver/blob/main/antlr.jar"
    click GenBuild "https://github.com/thisisthedarshan/pss-langserver/blob/main/genbuild.js"
    click MakeExec "https://github.com/thisisthedarshan/pss-langserver/blob/main/make-exec.js"
    click Makefile "https://github.com/thisisthedarshan/pss-langserver/tree/main/Makefile"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef tool fill:#bbb,stroke:#333,stroke-width:1px
    classDef runtime fill:#dff,stroke:#333,stroke-width:1px
    classDef transport fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef grammar fill:#99ccff,stroke:#333,stroke-width:1px
    classDef model fill:#cccccc,stroke:#333,stroke-width:1px
    classDef feature fill:#b3e6b3,stroke:#333,stroke-width:1px
    classDef definitions fill:#ffe599,stroke:#333,stroke-width:1px
```
