diff command

[david-crespo]

Now that we're versioning the external API in omicron, it's hard to see the schema diff, because every time we change the schema, we add a whole new copy of the schema file. To see the diff, we need to diff the old file and the new file. This change does that.

To keep it orthogonal to the other commands, it assumes you have already run generate — it doesn't run generate for you. If you have made code changes but haven't generated the new schema for them, the diff will be empty.

$ cargo xtask openapi diff -h
Show differences between local and blessed OpenAPI documents

Usage: omicron-dropshot-apis diff [OPTIONS]

Options:
      --dir <DIRECTORY>
          Loads this workspace's OpenAPI documents from local path DIRECTORY [env:
          OPENAPI_MGR_DIR=]
      --blessed-from-git <REVISION[:PATH]>
          Loads blessed OpenAPI documents from path PATH in the given Git REVISION [env:
          OPENAPI_MGR_BLESSED_FROM_GIT=]
      --blessed-from-dir <DIRECTORY>
          Loads blessed OpenAPI documents from a local directory (instead of the default,
          from Git) [env: OPENAPI_MGR_BLESSED_FROM_DIR=]
  -h, --help
          Print help (see more with '--help')

Global options:
      --color <COLOR>  Color output [default: auto] [possible values: auto, always, never]

What it doesn't do (yet)

In the console I have a somewhat different script api-diff (which doesn't take advantage of any openapi-manager machinery) that is fully GitHub-driven — it takes a PR number (or two refs) and prints the diff of either the schema or the generated TS client (more readable).

I find it pretty useful to be able to see the diff for a PR without checking the PR out locally. I see openapi-manager is already git remote-aware, so maybe some version of this isn't much of a stretch. Less clear that putting the TS client diff in is appropriate, but it is an npx one-liner to generate the client from a spec file, so it would be pretty easy.

[david-crespo]

I bet the windows failure is some kind of silly CRLF situation.

[david-crespo]

This is the most interesting test.

[david-crespo]

I'm not clear on whether you can have both a blessed and local file with the same version and a non-empty diff. Is this something that we expect to happen, or is check/generate is supposed to catch it, in which case we should maybe error out here too?

[david-crespo]

@sunshowers I did this in a way that fits with the tools already here, but I'm curious what you think about what @davepacheco and I discussed here: how this tool might incorporate (or not) functionality like my api-diff script, which works based on a PR number.