Pi-native version compatibility checker for pi.dev extensions — detect which pi APIs you use, check version support, and get migration suggestions.
pi install npm:@realvendex/pi-compatpi-compat analyzes your extension's TypeScript source code to detect pi.dev API usage patterns, then checks them against a versioned API catalog to tell you:
- Which pi versions your extension supports (compatibility matrix)
- Which APIs you're using that are deprecated (with replacement suggestions)
- What migration changes are needed to target a specific pi version
It fills the version compatibility gap in the pi.dev QA toolchain:
pi-lint→ checks API anti-patternspi-extension-toolkit→ checks structure/scaffoldingpi-test-harness→ runs runtime testspi-compat→ checks version compatibility ← this package
Analyze extension source for pi API usage and validate against known version constraints. Returns a compatibility matrix.
Parameters:
source(string, required) — TypeScript source code to analyzetargetVersion(string, optional) — Specific pi version to check against (e.g.'1.2.0'). If omitted, checks all known versions.
Example:
Use the compat_check tool with source="<your TypeScript code>"
Generate a detailed compatibility report with deprecated API usage, version matrix, and migration suggestions.
Parameters:
source(string, required) — TypeScript source code to analyzetargetVersion(string, optional) — Target pi version. Defaults to latest.includeCatalog(boolean, optional) — Include the full API catalog reference. Default: false.
Example:
Use the compat_report tool with source="<your TypeScript code>" includeCatalog=true
Auto-suggest migration changes for deprecated or removed APIs between two pi versions.
Parameters:
source(string, required) — TypeScript source code to analyzefromVersion(string, optional) — Current pi version. Defaults to detected minimum.toVersion(string, required) — Target pi version to migrate to.
Example:
Use the compat_migrate tool with source="<your TypeScript code>" toVersion="1.4.0"
pi-compat maintains a versioned catalog of pi.dev APIs covering:
- Core APIs:
registerTool,registerCommand,ExtensionAPI - Schema:
Type.Object,Type.String,Type.Boolean,Type.Array,Type.Optional,Type.Union,Type.Enum - Return patterns:
content_text_return,details_field,string_return(deprecated) - UI/Context:
ctx.hasUI,ctx.workspace,ctx.env,onUpdate - Imports: All
@earendil-works/*peer deps,typebox, deprecated@mariozechner/*
Versions tracked: 1.0.0 through 1.4.0
- Static analysis — regex-based scanning of TypeScript source for pi API patterns
- Catalog lookup — each detected API is checked against the versioned catalog
- Matrix generation — builds a compatibility matrix across all known pi versions
- Migration engine — maps deprecated/removed APIs to their replacements
Fits into the existing pi.dev QA pipeline:
pi-commit-lint → pi-changelog → pi-lint → pi-compat → pi-release
MIT