psc

Perl Structural Checker. Analyzes and inspects Perl source code using a pure-Go tree-sitter parser.

psc <command> [options] <file|directory>

Commands

parse <file|directory>

Parse a Perl file and display its syntax tree. Walks directories recursively for .pl and .pm files.

--format <tree|sexpr>

Output format. tree prints an indented tree; sexpr prints S-expression notation. Default: tree.

psc parse lib/MyModule.pm
psc parse --format sexpr lib/MyModule.pm
psc parse lib/

analyze <file|directory>

Analyze Perl files and list dependencies. Extracts use and require statements, showing pragmas and modules. Walks directories recursively.

psc analyze lib/MyModule.pm
psc analyze lib/

check <file|directory>

Type-check Perl files and report diagnostics. Runs type inference analysis. Walks directories recursively.

Output format:

filename:line:col: severity: message [code]

Diagnostic codes:

arity-mismatch

Call site passes the wrong number of arguments for the inferred signature.

type-mismatch

A value's inferred type is incompatible with how it is used.

unknown-builtin

A built-in function name was not recognized.

Guard suggestions appear as hint lines beneath a diagnostic when a type mismatch can be resolved by a runtime check:

  hint: Add guard: if (defined($x)) { ... }

psc check lib/MyModule.pm
psc check lib/

lsp

Start a Language Server Protocol server on stdin/stdout. Intended for use with LSP-capable editors.

Hover

Tooltips showing the inferred type of the symbol under the cursor.

Diagnostics

Type mismatch and arity errors published to the editor as you edit.

Document symbols

Symbol table for the current file, usable for outline views and navigation.

Definition

Go-to-definition for symbols with a known declaration site.

psc lsp

See the Editor Setup guide for copy-paste configurations for each editor.