Sage X3 .src support for Visual Studio Code, focused on snippets, keyword-aware function suggestions, hover help, outline symbols, and navigation.
Features
- Registers
.src files as the x3 language.
- Provides standard Sage X3 / AIMSYS snippets.
- Provides keyword-aware completions from configured Sage X3 source directories.
- Shows hover documentation for recognized function calls.
- Adds Outline View / Document Symbols for
$ labels, Subprog, and Funprog.
- Supports Go to Definition / Peek Definition for
Call, Gosub, and func references.
- Can optionally render clickable document links for references.
- Can optionally watch configured source directories and refresh the function index after
.src files change.
- Indexes configured source roots asynchronously with visible progress and a persistent cache.
Setup
The extension does not ship proprietary source files such as AIMGENLIB.src or AIMGENCHECK.src. Configure local directories that contain your own .src files.
Run these commands from the Command Palette:
Sage X3: Configure Source Directories
Source directories are scanned recursively for custom function suggestions, hover/signature help, Go to Definition, and Peek Definition.
Supported References
Navigation and hover support these patterns:
Call FOO(ARG1, ARG2) From BAR
Call FOO From BAR
Gosub FOO From BAR
Gosub FOO
func BAR.FOO(ARG1, ARG2)
Call FOO(ARG1, ARG2)
func FOO(ARG1, ARG2)
Navigation resolves by reference type. Call FOO From BAR resolves only to Subprog FOO in BAR.src; func BAR.FOO() resolves only to Funprog FOO in BAR.src; Gosub FOO From BAR resolves only to $FOO in BAR.src. When no module is present, the extension resolves in the current .src module when possible.
Function Documentation
Custom function suggestions are built from documented Subprog and Funprog declarations:
# Short description
# @keywords keyword1 keyword2 keyword3
# @param VALUE: description
# @return: description
Funprog MYFUNC(VALUE)
The description, keywords, parameters, and return details are shown in completion details and hover text.
Future Keyword Catalog
Currently, custom completions use information that already exists in the .src files: function names, module names, parameters, descriptions, @keywords, and return comments. Functions without useful comments or keywords are still suggested by name, but they may not appear for intent-based searches such as import file or validate site.
A future enhancement may add an optional external keyword catalog, so users can maintain extra descriptions, aliases, and search terms for standard or proprietary functions without editing the original .src files.
Settings
{
"sageX3.sourceDirectories": [
"C:/path/to/sagex3/sources"
],
"sageX3.watchSourceFiles": false,
"sageX3.indexOnStartup": false,
"sageX3.enableDocumentLinks": false,
"sageX3.maxCompletionItems": 200
}
For large repositories, configure the narrowest folders that contain the .src files you need. Full-root indexing is supported, but the first refresh may take several minutes for very large trees.
By default, the extension does not index on startup and does not watch source folders. Run this command when you want to build or refresh the function index:
Sage X3: Refresh Function Index
Refresh runs asynchronously, shows progress, supports cancellation, and caches parsed results. Later refreshes only reparse files whose size or modified time changed.
If refresh fails, run Sage X3: Show Log from the Command Palette. The Sage X3 output channel records the refresh stage, file currently being processed, cache activity, and the full error stack. This is the most useful information to include when reporting a problem.
The cache is written as one JSON record per source file rather than one giant JSON string. This avoids JavaScript Invalid string length failures on very large source trees. The cache format is automatically recreated on the next successful refresh.
The cached custom function index is not loaded automatically when startup indexing is disabled. This keeps standard snippets available immediately when a .src file opens. After you run Sage X3: Refresh Function Index, custom completions, hover, signature help, and navigation use the in-memory index. Edits to an open .src file update only that file's functions after a short debounce instead of rebuilding the whole index while you type.
Document links are disabled by default because they require scanning visible documents for links and can be expensive with very large files or very large indexes. Go to Definition, hover, and completion still work when document links are disabled.
Project Layout
The repository is organized so the current VS Code extension can keep working while the language-server version is prepared:
src/client/ VS Code extension client and current providers
src/server/ future local Language Server Protocol process
src/shared/ editor-neutral constants, models, and utilities
The current release still runs through the VS Code extension client. The server folder is a placeholder for the future LSP process, and shared code will gradually move there when it no longer depends directly on VS Code APIs.
Future LSP Direction
The language server runs locally on the user's machine. VS Code, Sublime Text, or another editor can start that local server and communicate with it through the Language Server Protocol. No hosted service is required for completions, hover, definition lookup, symbols, or future diagnostics.
Over time, parser and indexing code can move from src/client into src/shared or src/server, then the VS Code extension becomes a thinner adapter around the same Sage X3 language engine.
The first LSP implementation is experimental and opt-in for development testing:
{
"sageX3.useLanguageServer": true
}
When enabled, the extension starts the local server from src/server and uses it for completions, hover, Go to Definition, signature help, and document symbols. Diagnostics/error checking are intentionally left for a later step.
The current release package still uses the existing VS Code providers by default. Before turning the LSP on for Marketplace users, the language client/server runtime dependencies should be bundled into the VSIX.
Development Commands
Install dependencies:
npm install
Compile:
npm run compile
For every new release containing changes, increment the extension version before packaging. The Marketplace requires a new version for each update. Keep package.json and package-lock.json in sync; use a patch increment for fixes (for example, 1.1.5 to 1.1.6):
npm version patch --no-git-tag-version
Run this once per release, then rebuild the VSIX. Rebuilding the same release for verification does not require another increment.
Package locally:
npx vsce package --no-dependencies --allow-missing-repository
Package into the local release folder:
npm run package:release
Use GitHub Releases for published VSIX artifacts instead of committing generated .vsix files. Keep source files in git, and attach the packaged VSIX to a release tag such as v1.1.6.
License
See LICENSE.txt.
