Docs / Integrations / TypeScript SDK

TypeScript SDK

The CLI runs on top of a library. Import it to diagnose or migrate a repo from your own tooling.

Install

npm install kedgeway. It needs Node 22.12 or newer. Type declarations are bundled. See Getting started for the CLI.

API

Export	What it does
`diagnose(opts: { path; ecosystem?; fixture? })`	Scans the repo and returns a `Diagnosis` (`findings` and `summary`). Uses live Raven unless you pass `fixture` or an `ecosystem`.
`diagnoseDetailed(opts)`	Same options; returns `{ facts, snapshot, diagnosis }`.
`scanRepo(path)`	Reads manifests and returns `RepoFacts`. Throws if the path does not exist or is not a directory.
`diagnoseRepo(facts, snapshot)`	The pure rule engine: no I/O.
`createRavenEcosystem(opts?)`	An `EcosystemPort` backed by Stellar Raven. Options: `authPath` and `interactive` (set `false` to fail fast instead of starting OAuth).
`loadFixture(file)`, `FakeEcosystem`	Offline snapshots. See Fixtures.
`planMigration(facts, snapshot)`	Builds a `MigrationPlan` of version bumps and manual steps.
`buildGuide(plan, snapshot, hits)`	The migration guide: published version, protocol, steps, and the Raven notes whose title or url is a migration document.
`findImportHits(files, names)`	Pure search for import lines of the given package names.
`applyMigration(plan, { write })`	Dry run by default; edits files only when `write` is true.
`migrate(opts)`	Diagnose, plan and apply in one call. Adds `write?` to the diagnose options.
`toSarif(detailed, { cwd? })`	A SARIF 2.1.0 log. Same document as `diagnose --format sarif` or `--sarif`.
`toAnnotations(detailed, { cwd? })`	GitHub workflow commands, one per finding. Same lines as `--format annotations`.

Types: Diagnosis, Finding, Severity, EcosystemSnapshot, RepoFacts, MigrationPlan, MigrationStep, MigrationGuide, SourceHit.

Example, offline

Terminal

import { diagnose } from "kedgeway";

const diagnosis = await diagnose({
  path: ".",
  fixture: "snapshot.json", // see the Fixtures page for the shape
});

console.log(diagnosis.summary); // { critical, warning, info }
for (const f of diagnosis.findings) {
  console.log(f.severity, f.code, f.file);
}
process.exitCode = diagnosis.summary.critical > 0 ? 2 : 0;

For live data, drop fixture or pass ecosystem: createRavenEcosystem(). That needs a stored login (kedgeway login).