tia-lsp.nvim/AGENTS.md

AGENTS.md - SCL Language Server (Unified)

This is a unified Neovim/LazyVim plugin for Siemens SCL language support.

Project Overview

The unified scl_lsp project provides:

• LSP Server - Language Server Protocol implementation
• Linter - Diagnostics and code validation
• Formatter - Document formatting
• Syntax Highlighting - Tree-sitter based
• Auto-completion - blink.cmp integration with smart context-aware completions
• Auto-prefix - Automatic # prefixing for variables
• Workspace Scanning - Automatic scanning of UDTs (.udt) and Global DBs (.db)

Reference Project for Testing

For testing and referencing SCL, UDT, DB, and XML files, use the reference project at:

~/dev/siemens/projects/scl_lang_support_lazyvim_ref_project

This project contains example SCL files, UDT definitions, and global data blocks.

Project Structure

scl_lsp/
├── src/                        # LSP server implementation
│   ├── main.lua               # Entry point, protocol handling
│   ├── parser.lua             # Regex-based SCL parser
│   ├── treesitter.lua         # Tree-sitter integration
│   ├── diagnostics.lua        # Linter diagnostics
│   ├── formatter.lua          # Document formatter
│   ├── json.lua               # JSON encoder/decoder
│   └── plc_json.lua           # External UDT loading
├── lua/
│   ├── scl/                   # Neovim plugin modules
│   │   ├── init.lua          # Main plugin setup
│   │   ├── auto_prefix.lua    # Auto-prefix variables with #
│   │   ├── blink_cmp_source.lua    # blink.cmp completion source
│   │   ├── db_parser.lua           # Global DB (.db) parser
│   │   ├── fb_parser.lua           # Function Block parser
│   │   ├── udt_parser.lua         # UDT (.udt) parser
│   │   ├── variables.lua          # Local variable extraction
│   │   ├── workspace_types.lua     # Workspace scanning (UDTs, DBs, FBs)
│   │   └── multiline_params.lua   # Multiline parameter filling
│   └── scl_lsp/
│       ├── init.lua           # Unified plugin setup
│       └── plugins/
│           └── scl.lua        # LazyVim plugin spec
├── queries/                   # Tree-sitter queries
│   ├── highlights.scm
│   ├── indents.scm
│   ├── folds.scm
│   ├── locals.scm
│   └── tags.scm
├── grammar.js                # Tree-sitter grammar
└── tree-sitter.json         # Parser config

Key Modules

Parser Modules

Module	Purpose
udt_parser.lua	Parses .udt files to extract TYPE definitions and STRUCT members
db_parser.lua	Parses .db files to extract DATA_BLOCK definitions and VAR members
fb_parser.lua	Parses .scl files to extract FUNCTION_BLOCK and FUNCTION interfaces
variables.lua	Extracts local variables from VAR sections

Completion System

Module	Purpose
blink_cmp_source.lua	Main completion source for blink.cmp. Handles:
	- Local variables (with # prefix after BEGIN)
	- UDT types (quoted: "MyUDT")
	- UDT members (after dot: #var.member)
	- Global DB names (available in general completion)
	- Global DB members (after quote+dot: "DBName".member)
	- FB parameter completions (inside FB calls)
	- Basic SCL types

Workspace Scanner

Module	Purpose
workspace_types.lua	Scans project for:
	- .udt files (UDT types)
	- .db files (Global Data Blocks)
	- .scl files (Function Blocks/Functions)
	- Uses project markers to find project root

Auto-Completion Features

Trigger Characters

• # - Local variables (after BEGIN)
• . - Member access (UDT/DB members)
• " - Global DB names and member access
• ( - FB/Function parameter completion
• (space) - General completion (variables, UDTs, DBs, types)

Completion Contexts

1. Variable Completion (after space or at start)

   • Local variables from VAR sections
   • UDT type names (quoted)
   • Global DB names (wrapped in quotes automatically)
   • Basic SCL types

2. Member Completion (after .)

   • UDT members (resolves through nested types)
   • DB members (resolves through nested types)
   • Supports multi-level nesting: #var.member.submember

3. Global DB Completion

   • Type " then select DB → shows DB members
   • Or type space → select DB from list → automatically wrapped in quotes

4. FB Parameter Completion (after fbName()

   • Input parameters (:=)
   • InOut parameters (:=)
   • Output parameters (=>)

Special Features

• Auto-Prefix: Adds # to variables automatically after BEGIN
• Quote Wrapping: DB names selected from general completion are automatically wrapped in quotes
• Nested Resolution: Multi-level member path resolution for both UDTs and DBs

Development

Running the LSP Server

# Direct execution
lua src/main.lua

# Via shell script
./scl_lsp.sh

# With test mode
lua src/main.lua --test

Testing

# Tree-sitter parser
npm test
tree-sitter generate

# Test file parsing
tree-sitter parse corpus/test/main_org_block.scl

Key Patterns

• LSP Protocol: JSON-RPC over stdin/stdout in src/main.lua
• Diagnostics: src/diagnostics.lua - validates SCL code
• Formatter: src/formatter.lua - formats SCL documents
• Syntax: Tree-sitter queries in queries/
• Plugin Setup: lua/scl_lsp/init.lua - LazyVim integration

Configuration

See README.md for configuration options and usage.

Commands

Command	Description
:SCLShowVariables	Show local variables in current file
:SCLShowWorkspaceTypes	Show workspace UDTs, FBs, and Global DBs count
:SCLRescanWorkspaceTypes	Rescan workspace for types and DBs
:SCLPrefixWord	Manually prefix current word with #
:SCLMultilineParams	Fill multiline parameters for FB/Function call
:LspSCLFormat	Format current SCL file
:SCLGeneratePlcJson	Generate plc.data.json from data_types/