Capabilities: what is guaranteed vs best-effort
Upshift combines deterministic tooling (your package manager, tests, lockfiles) with optional AI (explain --ai, fix). This page sets expectations so you know what CI and docs promise versus what depends on models and prompts.
Guaranteed in automated tests (CLI)
These paths are exercised in-repo on fixtures and (where noted) pinned public repos:
| Area | Coverage |
|---|---|
| npm | scan, scan --json, scan --report, suggest, plan, upgrade --dry-run on tests/fixtures/minimal and workspace / no-test fixtures |
| pnpm / yarn | Same commands when pnpm / yarn are on PATH (see tests/fixtures/minimal-pnpm, minimal-yarn) |
| npm workspaces | scan / suggest / plan on tests/fixtures/minimal-workspace |
| Python | scan, scan --licenses, upgrade --dry-run on tests/fixtures/minimal-python |
| JSON shape (Node) | Top-level keys for scan --json and scan --report per tests/golden/node-scan-json-keys.json |
| Pure semver helpers | Unit tests (npm run test:unit) for getUpgradeType in src/lib/version-bump-kind.ts |
| Corpus (optional job) | Read-only upshift scan, plus selected explain <pkg> --risk (no --ai) on pinned tags in tests/corpus/repos.json (npm run test:corpus, weekly workflow) |
Platform, site parity, and Playwright checks run via npm test as documented in CONTRIBUTING.md.
Best-effort (AI and models)
| Capability | Notes |
|---|---|
explain --ai | Quality varies by model, prompt, and package; not snapshotted in default CI. |
fix / codemods | Node-first; review diffs and run tests. Use --dry-run before applying. |
| Risk scores & changelog summaries | Heuristic + network; treat as guidance, not proof. |
Optional AI eval rubrics (npm run test:ai-eval, key-gated) give a repeatable smoke check for a small prompt set—see ai-eval.md in the repo.
Deepest product investment (“hero stack”)
Strongest workflows and templates target npm / yarn / pnpm on Node, especially React / Next.js (explain, fix, migrations). Other ecosystems are supported for scan (and many for upgrade) with varying depth—see ROADMAP.md and the README hero-stack callouts.
Beta feedback
If something fails in the wild, use the Beta feedback issue template on GitHub: include CLI version, OS, package manager, and a redacted upshift scan --json when possible so we can reproduce shape without leaking secrets.