CLS Type Maps: Generate Autocomplete Data for Editors

Type maps are JSON files that describe every declaration in a CLS source file — functions with full parameter signatures, variables with their types, classes with their members, interfaces, structures, modules, and imports. The clx maptype subcommand generates them by lexing and parsing each .clsx or .clsi file and extracting structured metadata into .type.json files that the VS Code extension and LSP server can read without re-parsing source code on every keystroke. They are the bridge between your source and the editor’s autocomplete, hover documentation, and type-aware completion.

Generating Type Maps

clx maptype src/main.clsx -o .cls-types/src/main.type.json

When the input is a directory, clx maptype walks it recursively, skips .-prefixed directories and well-known build output folders (modules/, dist/, libs/, target/), and preserves the relative directory structure inside the output directory. For example, src/utils/math.clsx becomes .cls-types/src/utils/math.type.json. When the input is a single file, the -o flag can point to either a directory (the .type.json will be placed inside it) or an explicit output path. Default output directory is ./.cls-types/ when -o / --out is omitted.

Watch Mode

Pass --watch (or -w) to keep clx maptype running. It polls for file modifications every 2 seconds using mtime comparison and regenerates only the files that changed:

clx maptype . -o .cls-types --watch
# Watch mode activo (polling cada 2s)...
#   src/main.clsx -> .cls-types/src/main.type.json (12 entradas)

Run clx maptype . --watch in a background terminal alongside clx lsp so that autocomplete data stays in sync as you edit source files.

What Type Maps Contain

Each .type.json file is a TypeMap object with two top-level keys:

Key	Type	Description
`source`	`string`	Path of the source file that was parsed
`entries`	`TypeEntry[]`	Array of extracted declarations

Every TypeEntry carries:

Field	Description
`name`	Declaration name
`kind`	`"function"`, `"async function"`, `"variable"`, `"constant"`, `"class"`, `"structure"`, `"interface"`, `"module"`, `"namespace"`, `"import"`
`line` / `col` / `end_line` / `end_col`	Source location (1-indexed)
`doc`	Extracted `@description` text
`version`	From `@version` annotation, if present
`deprecated`	From `@deprecated` annotation, if present
`signature`	Full call signature string (e.g. `"add(a: int, b: int) -> int"`)
`params`	Array of `{ name, type_, doc }` objects
`return_type`	Return type string, or `null`
`return_doc`	From `@return` annotation
`fields`	For structures and classes: array of `{ name, type_ }`
`members`	For classes, interfaces, modules, namespaces: member name list
`type_`	For variables and constants: declared type
`value`	Reserved, currently `null`

Documentation Annotations in `.clsx`

clx maptype reads # @tag comments written directly above a declaration. All annotation lines must start with # @ (or #@):

# @description Adds two integers together
# @params a First operand
# @params b Second operand
# @return int The sum of a and b
# @version 1.2
function add(a: int, b: int) -> int {
    return a + b;
};

# @description A deprecated helper — use add() instead
# @deprecated Use add() from utils module
function sum(a: int, b: int) -> int {
    return a + b;
};

Supported annotation tags:

Tag	Appears in	Description
`@description`	`doc` field	Summary shown in hover tooltips
`@params <name> <text>`	`params[i].doc`	Per-parameter documentation
`@return <type> <text>`	`return_doc`	Return value documentation
`@version <semver>`	`version`	API version
`@deprecated <reason>`	`deprecated`	Deprecation notice (shown with strikethrough in hover)

A # @title comment is treated as a module-level separator and stops upward annotation scanning, so module headers do not bleed into the first function’s docs.

`.clsi` Interface Files

.clsi files are pure type declaration files — they contain function signatures, variable declarations, interfaces, classes, and structures with no implementation. The standard library ships its type information as .clsi files in cls-runtime/clsi/:

cls-runtime/clsi/
├── core.clsi    # Intrinsics: print, input, len, type, now, exit, sleep, throw, …
├── math.clsi    # math module
├── json.clsi    # json module
├── fs.clsi      # fs module (desktop only)
├── http.clsi    # http module (desktop only)
├── Lib.clsi     # Lib (compiled library loader)
└── async.clsi   # async module

clx maptype processes .clsi files the same way it processes .clsx files. The LSP server embeds all builtin .clsi definitions directly in the binary via include_str!, so they are always available without any file lookup.

Example: `core.type.json`

The following is the real generated type map for cls-runtime/clsi/core.clsi, which describes the CLS intrinsic functions:

{
  "source": "cls-runtime/clsi\\core.clsi",
  "entries": [
    {
      "name": "print",
      "kind": "function",
      "line": 8,
      "col": 1,
      "end_line": 8,
      "end_col": 1,
      "doc": "Imprime valores en consola",
      "version": null,
      "deprecated": null,
      "signature": "print(val: Any)",
      "params": [{ "name": "val", "type_": "Any", "doc": null }],
      "return_type": null,
      "return_doc": null,
      "fields": [],
      "members": [],
      "type_": null,
      "value": null
    },
    {
      "name": "input",
      "kind": "function",
      "line": 11,
      "col": 1,
      "end_line": 11,
      "end_col": 1,
      "doc": "Lee una linea desde la entrada estandar",
      "version": null,
      "deprecated": null,
      "signature": "input() -> String",
      "params": [],
      "return_type": "String",
      "return_doc": null,
      "fields": [],
      "members": [],
      "type_": null,
      "value": null
    },
    {
      "name": "len",
      "kind": "function",
      "line": 29,
      "col": 1,
      "end_line": 29,
      "end_col": 1,
      "doc": "Devuelve la longitud de arrays, strings o records",
      "version": null,
      "deprecated": null,
      "signature": "len(val: Any) -> int",
      "params": [{ "name": "val", "type_": "Any", "doc": null }],
      "return_type": "int",
      "return_doc": null,
      "fields": [],
      "members": [],
      "type_": null,
      "value": null
    }
  ]
}

The full core.clsi type map also includes toString, int, float, str, bool, type, now, exit, sleep, and throw.

Integration with VS Code

When cls.options.unnestableFeatures.useMapClsi is true (the default), the VS Code extension reads every .type.json file found under .cls-types/ in the workspace root and adds its entries to the completion list. As you type, the extension queries these maps for:

Function completions — name, signature, parameter hints
Variable completions — name and declared type
Module completions — module name and its member list
Hover documentation — doc, params, return_doc, deprecated fields rendered as Markdown

The LSP server (clx lsp) uses the same type map data loaded via type_defs::load_all_type_definitions, which merges the embedded builtin definitions with any workspace .clsi files found in a clsi/ directory at the project root.

Add .cls-types/ to your .gitignore — type maps are auto-generated build artifacts and should not be committed to version control.

# .gitignore
.cls-types/
dist/

VS Code Extension

Architecture

CLS Type Maps: Generate Autocomplete Data for Editors

Generating Type Maps

Watch Mode

What Type Maps Contain

Documentation Annotations in `.clsx`

`.clsi` Interface Files

Example: `core.type.json`

Integration with VS Code

Build docs developers (and LLMs) love

VS Code Extension

Architecture

Documentation Index

​Generating Type Maps

​Watch Mode

​What Type Maps Contain

​Documentation Annotations in .clsx

​.clsi Interface Files

​Example: core.type.json

​Integration with VS Code

Build docs developers (and LLMs) love

Generating Type Maps

Watch Mode

What Type Maps Contain

Documentation Annotations in `.clsx`

`.clsi` Interface Files

Example: `core.type.json`

Integration with VS Code