Solana Compat Pilot

Solana Compat Pilot is a conservative Codemod/JSSG migration package for moving
@solana/web3.js v1 projects onto the @solana/web3-compat bridge and preparing
them for progressive @solana/kit adoption.

DoraHacks / judge snapshot

Positioning: compat-bridge-first (official @solana/web3-compat path), not a fake “100% to Kit in one click” tool — see docs/HACKATHON_WIN_PLAN.md for what top BUIDLs did well and your P0 checklist before submit. Upstream issue draft: docs/FRAMEWORK_ADOPTION.md.
Trust signals: npm run fixtures:count (JSSG input.ts / expected.ts pairs), npm run test:pipeline (integration tests on the migration runner), npm run ci, two pinned dry-run corpora in case-study/EXTERNAL.md (solana-labs/explorer + solana-labs/solana-program-library / token/js), committed sample artifacts under case-study/artifacts/.
After registry publish: put the exact npx codemod … line in your BUIDL + README (winning entries always do). Steps: docs/REGISTRY_PUBLISH.md and workflow .github/workflows/publish-codemod.yml.

The goal is not to guess through hard semantic rewrites. The deterministic pass
handles changes that are safe at scale, while risky full-Kit migrations are
reported with clear AI/human follow-up instructions.

What It Does Now

Automates the low-risk bridge step for real Solana projects.
Minimizes false positives by only touching files that import or require
@solana/web3.js.
Leaves review markers for complex migration areas such as Connection,
PublicKey, Keypair, mutable transactions, and subscriptions.
Provides a runner that can analyze a target repo, update package.json, run
the Codemod workflow, write a JSON confidence report, and emit a rollback
patch for git-backed targets.

Usage

bash

Replayable public evidence for judges is documented under case-study/ (command checklist, npm run case-study:replay, committed case-study/artifacts/*.json samples, and pinned real-repo notes in case-study/EXTERNAL.md).

Pinned replay references in this repository are currently anchored at pilot commit c46d591f4f80d9cd88fe2331c702975a93e2afc9 and target-repo commit(s) listed in case-study/EXTERNAL.md.

The migration runner is split under scripts/pipeline/ (scan/manifest/direct Kit/report/rollback) so the CLI entry scripts/migration-pipeline.mjs stays a thin orchestrator.

Recommended pipeline:

bash

Apply mode refuses dirty git targets by default. Pass --allow-dirty only when
the target has intentional uncommitted changes and the rollback patch is enough
for the run.

Apply mode also requires at least one --check command by default so applies are
always tied to a real target validation gate. Use --skip-validation only when
you explicitly accept an unverified apply (for example in throwaway sandboxes).

Dry-run and report scans exclude common test and fixture directories (tests/,
__tests__/, fixtures/, *.test.*, *.spec.*, .cursor/, and similar) so
counts reflect product source. Pass --include-test-dirs to scan them anyway,
and --exclude-glob (repeatable) to add project-specific exclusions.

The apply report includes:

package manifest changes,
opt-in direct Kit transform changes,
changed source confidence buckets,
exact hotspots that still need review,
validation command results,
rollback command for git targets.

Current Scope

Automated:

ESM imports from @solana/web3.js to @solana/web3-compat.
CommonJS require("@solana/web3.js") to @solana/web3-compat.
Dynamic import("@solana/web3.js") to @solana/web3-compat.
import x = require("@solana/web3.js") to @solana/web3-compat.
package.json additions for @solana/web3-compat, @solana/kit, and
@solana/client for every scanned workspace manifest (root plus packages/*-style folders
resolved from npm workspaces and from pnpm-workspace.yaml).
Opt-in direct Kit rewrites (--direct-kit):
- unaliased new PublicKey("<literal>") when the imported PublicKey is only
  used for string-literal constructors and the constructed values are not used
  through legacy object/member APIs (address from @solana/kit);
- unaliased new Connection("<http(s) RPC URL>") when the compat Connection import matches
  the narrow constructor-only pattern (createSolanaRpc from @solana/kit).
- unaliased new Connection("<ws:// or wss:// URL>") with the same safety rules
  (createSolanaRpcSubscriptions from @solana/kit; opt-in websocket-connection-literals).
Dry-run JSON report, confidence buckets, validation command hooks, and git
rollback patch.
Review markers for full-Kit migration hotspots.

Additional automation gaps (still manual / AI review):

new Connection / PublicKey / Keypair cases outside the guarded literal patterns above.

Not automated yet (semantic / async boundary changes):

Keypair-style flows to Kit signers (generateKeyPair is async unlike Keypair.generate()).
Mutable Transaction builders to Kit transaction-message pipelines.

Those patterns remain for project-specific review (SOLANA_COMPAT_PILOT markers plus optional bounded Codemod AI step in workflow.yaml, which CI does not execute).

Migration score meaning

The headline score produced by scripts/migration-score.mjs is a file-level coverage ratio:
safeFilesCoveragePercent = safeFiles / legacyFilesBefore (rounded to two decimals).
It is not "% of the whole codebase migrated to Kit" and should be read together with
the needs-review hotspot list. Formula details are documented in
case-study/migration-score.md.

Registry

Ready to contribute?

solana-compat-pilot

Run locally