tools: api-diff --local

[david-crespo]

api-diff is a lovely tool (if I may say so) for seeing the effect of OpenAPI schema changes in Omicron on the generated TS client. Until this PR it can only look at GitHub. This is useful for pointing it at a PR number. However, while working on oxidecomputer/omicron#10673 and oxidecomputer/omicron#10675, which cause large diffs in the schema, I found I wanted to be able to see changes before I push them. This PR adds a --local flag that lets you run it against local Omicron commits.

While I think I wrote the original version of this script by hand, it's gone through a few iterations of full vibe-coding, so while I've skimmed the code, I am really not especially concerned about the details. The way this PR works is it adds a concept of Source, which is either GitHub or a local repo, and each has its corresponding methods for listing schema files and reading the schema contents, etc. Nice work from the robot.

/**
 * A source of schema files. The remote source reads from GitHub; the local
 * source reads from the git repo in the current directory. Both expose the
 * same primitives so the diff logic doesn't care where schemas come from.
 */
type Source = {
  /** Resolve a ref (PR number, SHA, branch, jj revset, or undefined for the default) to a commit id */
  resolveCommit: (ref?: string | number) => Promise<string>
  /** List schema filenames under openapi/nexus at a commit, or null if the dir is absent */
  listSchemaNames: (commit: string) => Promise<string[] | null>
  /** Read the filename that nexus-latest.json points to at a commit */
  readLatestPointer: (commit: string) => Promise<string>
  /** Read spec content at a commit (the remote source follows gitstub references) */
  readSpec: (commit: string, specPath: string) => Promise<string>
}

This implementation is also jj-aware — if the repo in question is a jj repo it will use jj revs instead of git, which is relevant because when you have a colocated jj/git repo, by default (without a rev specified) you probably want to look at @, but git's HEAD is at @-. If that doesn't mean anything to you, ignore it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
console	Ready	Preview	Jun 26, 2026 3:56pm