Malib Language Support

VS Code language support for Malib scripts.

Features

• Syntax highlighting for .malib files.
• Line and block comments.
• Strings and supported escape sequences.
• Core commands such as read columns, split chars, comment line, comment line at, comment block, match index, match case, span max, debug, coverage, string quotes, string multiline, param, const, let, flag, if, for, print, push, pop, clear, ruleset, analyzer, run, and when.
• Lifecycle and scoped blocks such as before, after, tokenizer, and local let.
• Relative rules with before when and after when.
• Rule gates with @requires(_flag, !_other_flag).
• when pattern items such as cap, push, in, as, at, int, real, string, span_until, max, any, opt, not, mask, line_end, and line_gap.
• Single-quoted Malib values and double-quoted source-token patterns.
• Arithmetic operators for runtime counters.
• Runtime properties and methods such as .count, .columns, .last, .mid(...), .trim, .contains(...), .replace(...), .split_protected(...), source.*, global.*, and match.*.
• Iteration forms such as for item, idx in list, for ... reverse, for i from a to b, and for i from a until b.
• Analyzer runs such as run analyzer name from text value with { ... } and run analyzer name in match.
• Scan-control commands such as cut, cut first, cut range, and cut all.
• Transformation commands such as replace match with, delete range, insert before, and insert after.
• Host value functions such as read_file, read_lines, and read_csv.
• Semantic token highlighting layered on top of TextMate scopes for real symbol meaning: functions, variables, params, flags, consts, loop indices, captures, properties, methods, keywords, and decorators.
• Snippets for common Malib commands and blocks.
• Hover documentation for reserved words, commands, pattern items, built-ins, and runtime properties.
• Symbol hover for param, let, const, flag, captures, fun, and ruleset declarations.
• Go to definition and find references across imported modules, including functions, globals, rulesets and analyzers.
• Rename with F2 across imports and references, respecting local parameters, execution frames and name collisions.
• Project completions and multiline signatures for imported functions.
• Type-aware member completions for text, lists, matrices, object fields, source/match values and AST captures. Unknown values retain general suggestions.
• Inlay hints for function call arguments and for loop item/index variables.
• Folding ranges for Malib brace blocks such as ruleset, analyzer, fun, when, if, for, before, after, and tokenizer.
• Document and selection formatting with conservative two-space indentation.
• Hierarchical document outline for params, flags, values, functions, rulesets, analyzers, lifecycle blocks, and when rules.
• Signature help for call function_name(...), plus ruleset/analyzer parameter hints during run expressions.
• Basic diagnostics for call, run, run analyzer, ref, @requires, flag declarations, const reassignment, unknown assignment targets, collection references, structural consume/audit residual children placement, relative before when/after when, and match transformation commands such as cut, replace match, delete range, and insert.
• Quick fixes for common diagnostics, including flag naming, run versus call, analyzer runs, const reassignment, missing variable declarations, and missing @requires flags.

Compiler And Runtime Commands

Configure the CLI once with Malib: Configure Executable, or set malib.executablePath to an installed malib binary. The CLI is not bundled. Open the project folder and a saved .malib file, then use the Command Palette:

• Malib: Check Program compiles the entrypoint and reports native errors in Problems.
• Malib: Run Program selects a source input and opens the JSON result beside the editor.
• Malib: Explain Rule selects a source, rule index or label, optional ruleset and token/AST kind.
• Malib: Diagnose Program runs doctor and opens its JSON report.
• Malib: Show Last Export opens the last successful run's exported data as editable JSON, which can be saved normally.

run and doctor execute your directives, including their file, database or system effects. CLI commands run only in trusted workspaces. They have progress, cancellation and a configurable timeout. Unsaved Malib documents must be saved before execution; automatic checks skip projects with unsaved Malib buffers.

Settings:

• malib.entrypoint: optional entrypoint, relative to the workspace or absolute. Also selects the editor context when a shared module has multiple callers.
• malib.workingDirectory: optional execution directory for relative data/database paths; defaults to the entrypoint's directory.
• malib.parameters: named string parameters passed as -a name=value.
• malib.checkOnSave: optional native validation on save, disabled by default.
• malib.timeoutMs: command timeout, default 30000 ms.

The editor index is conservative static analysis, not a replacement for the compiler. It cannot infer every dynamic return value or caller-provided value. When multiple entrypoints supply a shared name, select malib.entrypoint before renaming it. With the malib.check.v1 CLI contract, native errors point to the original imported file and full range, with UTF-8 offsets converted for VS Code. Older binaries without source identity attach modular errors to the entrypoint rather than guessing an imported file location.

Value member completions, hover documentation and parameter help use the structured metadata signatures, including receiver types, optional parameters, allowed option values and return types.

Development And Synchronization

Open editors/vscode-malib in VS Code and run the extension development host.

Run the extension test suite from this folder with:

npm test

The extension is intentionally editor-facing only. Malib parser, compiler, runtime, and diagnostics stay in matlalib-core.

Run npm run sync:language after changing docs/malib/language-metadata.json or docs/malib/language-reference.md. It generates the shipped function/member catalog and host-function TextMate pattern. Tests reject stale generated data. Members listed only in metadata without detailed reference remain marked as undocumented and are not offered as verified typed completions.

Optional integration test environment variables:

• MALIB_TEST_EXECUTABLE: native CLI binary used to exercise check/run/explain/doctor.
• MALIB_DIRECTIVES_TEST_DIR: directory of productive modular .malib files to audit.

tests/vscode/run.js is a real Extension Host smoke test. Launch VS Code with --extensionDevelopmentPath pointing here and --extensionTestsPath pointing to that script, using tests/fixtures/project as the workspace and an isolated --user-data-dir. The same MALIB_TEST_EXECUTABLE enables native command checks.

Use examples/full-syntax.malib as the living syntax fixture for highlighting decisions. When the Malib language grows, update that file first or alongside the grammar, then verify that the TextMate scopes still highlight the complete syntax shape.

The test suite also covers productive migration fixtures:

• comparison/cases/004-validaciones-estaticas/malib/validaciones_estaticas.malib
• comparison/cases/005-codigo-muerto/malib/program.malib

Packaging

Before packaging or publishing, run:

npm test
npm run package

Packaging runs tests first and removes older local vscode-malib-*.vsix files only after the new package succeeds. VSIX files remain excluded from Git.

To publish to the Visual Studio Marketplace, make sure the publisher field in package.json matches your Marketplace publisher id, then run:

npm run publish

Example

read columns 7..72
split chars ".(),;:"
comment line "//"
comment block "/*" "*/"
string quotes "'\""
match case insensitive
debug off
coverage on

const reserved_words = ['IF', 'ELSE', 'PERFORM']
flag _in_procedure = off
let found = 'NO'
let dsn_names = []
let last_dsn = ''

match index off

ruleset cobol_scan {
  debug on {
    tokens: true
    matches: true
    variables: ['found']
  }

  when (in reserved_words cap keyword) {
    found = 'SI'
    push dsn_names, keyword
  }
}

when ("TO" cap destino) {
  before when ("MOVE" cap origen) {
    found = 'SI'
    push dsn_names, origen
  }
}

run cobol_scan
pop dsn_names into last_dsn
pop dsn_names
print last_dsn, dsn_names.count