pi-lint

Pi-native extension linter that checks for pi-specific API anti-patterns — deterministic, no LLM calls, catches runtime bugs before npm publish.

Installation

pi install npm:@realvendex/pi-lint

What It Does

pi-lint scans your pi.dev extension source code for common anti-patterns that cause runtime bugs. Unlike general code quality tools, pi-lint understands pi.dev-specific APIs and conventions.

Key features:

• 8 rules covering enum handling, tool naming, UI guards, exports, error handling, partial results, blocking, and output truncation
• Deterministic pattern matching — no LLM calls, instant results
• Auto-fix for simple patterns (kebab-to-snake names, StringEnum imports)
• Structured output with file, line, column, rule, severity, and fix suggestions
• Text and markdown report formats

Tools

lint_extension

Scan a pi.dev extension source directory for API anti-patterns.

Parameters:

• path (string, required) — Path to the extension source directory
• rules (string[], optional) — Specific rules to check (default: all)
• severity (string, optional) — Filter by severity: "error" or "warning"
• exclude (string[], optional) — File path patterns to exclude

Example:

Use the lint_extension tool with path="./extensions"

lint_report

Generate a formatted markdown lint report from scan results.

Parameters:

• path (string, required) — Path to the extension source directory
• rules (string[], optional) — Specific rules to check
• format (string, optional) — Output format: "text" or "markdown"

Example:

Use the lint_report tool with path="./extensions" format="markdown"

lint_fix

Auto-fix simple anti-patterns. Currently supports:

• Converting kebab-case tool names to snake_case
• Adding StringEnum import when Union/Literal enum pattern detected

Parameters:

• path (string, required) — Path to the extension source directory
• rules (string[], optional) — Rules to auto-fix
• dryRun (boolean, optional) — Show what would be fixed without making changes

Example:

Use the lint_fix tool with path="./extensions" dryRun=true

Rules

Rule	Severity	Description
no-union-enum	error	Type.Union/Type.Literal instead of StringEnum (breaks Google API enum handling)
kebab-tool-name	error	Tool names in kebab-case instead of snake_case (pi.dev requires snake_case)
missing-hasui-guard	error	Missing ctx.hasUI guard before UI operations in tool execute
missing-default-export	error	Missing export default function in extension.ts
return-not-throw	warning	Returning error objects instead of throwing Error (pi.dev convention: throw)
unhandled-partial	warning	Not handling isPartial/expanded in renderResult
unconditional-block	warning	block: true set unconditionally (should be conditional on context)
missing-output-truncation	warning	Tool output not truncated (large outputs cause UI issues)

Resources

• npm
• GitHub
• pi.dev

License

MIT