---
slug: "realvendex-pi-compat"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ZachDreamZ/pi-compat@master/README.md"
repo: "https://github.com/ZachDreamZ/pi-compat"
source_file: "README.md"
branch: "master"
---
# pi-compat

> Pi-native version compatibility checker for pi.dev extensions — detect which pi APIs you use, check version support, and get migration suggestions.

## Installation

```bash
pi install npm:@realvendex/pi-compat
```

## What It Does

pi-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-patterns
- `pi-extension-toolkit` → checks structure/scaffolding
- `pi-test-harness` → runs runtime tests
- **`pi-compat` → checks version compatibility** ← this package

## Tools

### `compat_check`

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 analyze
- `targetVersion` (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>"
```

### `compat_report`

Generate a detailed compatibility report with deprecated API usage, version matrix, and migration suggestions.

**Parameters:**
- `source` (string, required) — TypeScript source code to analyze
- `targetVersion` (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
```

### `compat_migrate`

Auto-suggest migration changes for deprecated or removed APIs between two pi versions.

**Parameters:**
- `source` (string, required) — TypeScript source code to analyze
- `fromVersion` (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"
```

## API Catalog

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**

## How It Works

1. **Static analysis** — regex-based scanning of TypeScript source for pi API patterns
2. **Catalog lookup** — each detected API is checked against the versioned catalog
3. **Matrix generation** — builds a compatibility matrix across all known pi versions
4. **Migration engine** — maps deprecated/removed APIs to their replacements

## Integration

Fits into the existing pi.dev QA pipeline:

```
pi-commit-lint → pi-changelog → pi-lint → pi-compat → pi-release
```

## Resources

- [npm](https://www.npmjs.com/package/@realvendex/pi-compat)
- [GitHub](https://github.com/ZachDreamZ/pi-compat)
- [pi.dev](https://pi.dev/packages/@realvendex/pi-compat)

## License

MIT