Pincher

Pincher is the editor-agnostic Language Server Protocol (LSP) implementation for the Arturo programming language. It provides intelligent editing features for any LSP-compatible editor.

The name is intentionally not 'pincer'.

Supported Editors

| Editor | Status | Documentation | |--------|--------|---------------| | Zed | First-class | docs/zed/README.md | | Neovim | First-class | docs/nvim/README.md | | Sublime Text 4 | First-class | docs/st4/README.md | | Helix | First-class | docs/helix/README.md | | JetBrains Rider | First-class | docs/rider/README.md | | Emacs | First-class | docs/emacs/README.md |

The Zed extension that consumes Pincher is Stinger.

Features

Language Intelligence

Diagnostics — type errors, contract violations, and undefined symbol warnings published to the editor gutter.

Navigation — Go-to-Definition, Go-to-Type-Definition, Go-to-Implementation, Find All References, and Workspace Symbols.

Call Hierarchy — incoming and outgoing call trees for any user-defined function.

Completion — intelligent completion for 500+ built-in functions, user-defined symbols, and member/method completions for custom types, with ranked results.

Hover — signatures, type annotations, and full documentation for built-ins and user symbols.

Signature Help — active parameter highlighting as you type inside a function call.

Formatting — document-level and range formatting for .art files.

Inlay Hints — parameter name hints displayed at call sites for user-defined and enforced functions (e.g. divideValues ‹x:› 10 ‹y:› 2), and type hints on variable assignments where the type can be inferred.

Code Actions — quick fixes and refactors available via the editor lightbulb. Includes:

• Wrap in enforced with .pre stub — rewrites a function definition to enforced and inserts a .pre: [ ensure [...] ] stub immediately after the body, pre-filled with the first parameter name.
• Wrap in enforced with .pre and .post stubs — same, but also inserts a .post: [ ensure [result <> 0] ] stub.
• Extract to function — extracts a selected block into a new top-level function.
• Add type annotation — inserts an inferred type annotation on a variable assignment.

Rename — safe rename across all references in the workspace.

Code Lens — inline annotations above function definitions:

• Run — appears above zero-argument functions. Clicking executes the function via arturo and shows the output in an editor notification. Requires arturo on PATH.
• N references — appears above every user-defined function. Clicking triggers editor.action.showReferences, which opens the editor's native references panel pre-populated with all call sites.
• N contracts — appears above enforced functions that have ensure clauses.

Design by Contract

Pincher enforces preconditions and postconditions declared in Arturo source using the enforced keyword. Violations appear as diagnostics with the violated clause highlighted.

An enforced function is declared with a body block and annotated with .pre and .post attribute blocks:

divideValues: enforced [x, y][
    x / y
]
.pre:  [ ensure [y <> 0] ]
.post: [ ensure [result > 0] ]

Calling divideValues 10 0 produces:

Contract violation: Pre-condition check failed -> y <> 0

Calling divideValues -10 2 (result = -5) produces:

Contract violation: Post-condition check failed -> result > 0

Postcondition checking is static: Pincher resolves the return expression at the call site using the supplied literal arguments. Calls where arguments cannot be resolved to literals are skipped silently.

and and or combinators are supported in both pre and postconditions:

.pre: [ ensure [and [x > 0] [y > 0]] ]

See docs/general/dbc.md for the full contract syntax reference.

Installation

npm install -g pincher

Confirm: pincher --version.

From Source

git clone https://codeberg.org/DaZhi-the-Revelator/pincher
cd pincher
npm install
npm run build

Usage

Pincher speaks LSP over stdio. Pass --stdio to start:

pincher --stdio

Most editors handle this automatically when configured to use Pincher as the Arturo language server. See the per-editor documentation linked in the table above.

Configuration

Pincher reads configuration from two locations, merged in this order (later overrides earlier):

1. Global user config: ~/.config/pincher/config.toml on Linux/macOS, %APPDATA%\pincher\config.toml on Windows.
2. Per-project config: .pincher/config.toml at the project root.
3. LSP initializationOptions from the editor (highest priority).

Generate a per-project config:

pincher init

Place a pincher.toml at the project root to configure Pincher. All keys are optional:

[server]
completions = "on"       # "on" | "off"
signatures  = "on"       # "on" | "off"
formatting  = "on"       # "on" | "off"
highlights  = "on"       # "on" | "off"
log_level   = "warn"     # "off" | "error" | "warn" | "info" | "debug"

[contracts]
enabled  = true          # enable DbC checking
strict   = false         # treat contract warnings as errors

[code_lens]
run        = true        # Show Run above zero-argument functions
references = true        # Show reference count above every function
contracts  = true        # Show contract summary above enforced functions

A JSON Schema for pincher.toml is available at pincher.schema.json.

CLI Commands

| Command | Description | |---|---| | pincher init | Create .pincher/config.toml; prints existing contents if already present | | pincher check | Static pass over all .art files in the current directory; flags: --json, --quiet, --no-color; exit codes: 0 = clean, 1 = warnings, 2 = errors | | pincher doctor | Print a structured environment report for bug reports | | pincher --version | Print the installed Pincher version |

Troubleshooting

Pincher Does Not Start

1. Confirm Node.js 14 or later is installed: node --version.
2. Confirm Pincher is on your PATH: pincher --version.
3. Check your editor's LSP log for startup errors.

No Completions or Hover

Ensure completions and signatures are "on" in pincher.toml (they are on by default).

Contract Diagnostics Not Appearing

Ensure contracts.enabled = true in pincher.toml (default: true). Contract checking requires the function to be declared with enforced and annotated with .pre or .post blocks.

Links

• Arturo Language
• Stinger — Zed extension powered by Pincher
• tree-sitter-arturo — grammar
• zed-arturo — predecessor extension
• LSP Specification

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE for details.