Project Checking

tcl-check runs the same parser, metadata registry, and resolver used by the language server, but reports diagnostics in a terminal-friendly format.

Common Commands

Analyze a directory or a single file:

uv run tcl-check path/to/project
uv run tcl-check path/to/file.tcl

Show source context and fail the command when diagnostics are present:

uv run tcl-check --context-lines 2 --fail-on-diagnostics path/to/project

Load extra project metadata explicitly:

uv run tcl-check --plugin-path .tcl-ls path/to/project

Control worker count:

uv run tcl-check --threads 4 path/to/project

What The Checker Does

The checker prepares package-scoped workspaces, indexes source files, and then prints grouped diagnostics with a summary at the end. In an interactive terminal, it also shows live progress as workspaces and source files are analyzed.

The checker currently focuses on high-confidence diagnostics, including areas such as:

  • unresolved commands, packages, and variables

  • ambiguous command or variable resolution

  • duplicate procedures

  • malformed static command forms such as if and switch

  • metadata-driven option, subcommand, and arity checks

For the full diagnostic catalog and severity/source conventions, see Diagnostics.

Project And Dependency Discovery

tcl-check understands local package layouts instead of treating every file as an isolated script:

  • pkgIndex.tcl roots define package workspaces

  • dependent files can be pulled in as background sources when package metadata points at them

  • lib-path and library-path extend the set of external package roots

  • plugin-path adds extra metadata files or Tcl plugin helpers

For repeated workflows against the bundled tcllib checkout in this repository, use:

make check-tcllib