feat: Add rover contract describe and rover contract publish

[sachindshinde]

This PR implements the first phase of #1421

That is, this PR:

• Implements rover contract describe, which prints out a human-readable description of the configuration of a contract variant.

Describe the configuration of a contract variant from the Apollo graph registry

Usage: rover contract describe [OPTIONS] <GRAPH_REF>

Arguments:
  <GRAPH_REF>
          <NAME>@<VARIANT> of graph in Apollo Studio. @<VARIANT> may be left off, defaulting to @current

• Implements rover contract publish, which allows creating a contract variant (or updating its configuration) and optionally triggering a launch.

Publish an updated contract configuration to the Apollo graph registry and trigger launch in the graph router

Usage: rover contract publish [OPTIONS] <--include-tag <INCLUDE_TAG>|--no-include-tags> <--exclude-tag <EXCLUDE_TAG>|--no-exclude-tags> <--hide-unreachable-types|--no-hide-unreachable-types> <GRAPH_REF>

Arguments:
  <GRAPH_REF>
          <NAME>@<VARIANT> of graph in Apollo Studio. @<VARIANT> may be left off, defaulting to @current

Options:
      --source-variant <SOURCE_VARIANT>
          The source variant name for this contract variant. Once set, this cannot be changed

      --include-tag <INCLUDE_TAG>
          List of tag names to include in the contract schema (e.g. '--include-tag foo --include-tag bar'). To specify an empty list, use --no-include-tags instead

      --no-include-tags
          Use an empty include list of tag names for the contract schema. To specify a non-empty list, use --include-tag instead

      --exclude-tag <EXCLUDE_TAG>
          List of tag names to exclude from the contract schema (e.g. '--exclude-tag foo --exclude-tag bar'). To specify an empty list, use --no-exclude-tags instead

      --no-exclude-tags
          Use an empty exclude list of tag names for the contract schema. To specify a non-empty list, use --exclude-tag instead

      --hide-unreachable-types
          Automatically hide types that can never be reached in operations on the contract schema

      --no-hide-unreachable-types
          Do not automatically hide types that can never be reached in operations on the contract schema

      --no-launch
          Do not trigger a launch in Studio after updating the contract configuration

Some notes:

• The API for upserting a contract's configuration does not allow specifying a particular key as null to indicate "don't change this key's value". This means that most configuration is required to be specified each time the command is run.
  • The exception is --source-variant, which the API allows to be optional.
  • Follow-up work will take on making these configuration keys nullable in the API. I've set up the Rover code such that making the switch shouldn't be too much work.
    • Should mainly be changing the ArgGroups to use required(false), updating the runner.rs/types.rs, and removing the None check in run().
    • Note that instead of saying "not specifying --include or --no-include means use the pre-existing value", we could also introduce a new argument e.g. --keep-include that explicitly keeps the pre-existing value, and add --keep-include to the ArgGroup instead of making the ArgGroup not required. (Similar situation for the other configuration options.) This is something to consider in the follow-up work though/doesn't need to be considered here.

[EverlastingBugstopper]

After reading the docs PR (and re-learning about contracts) it looks like these includes/excludes are only related to tags, making me think we should rename --include and --no-include to --include-tags and --no-include-tags if we think we might have different filter kinds down the line.

Alllsssoo, I think it would be super helpful if rover contract describe spit out a suggestion for how to create that same contract (and let's tap @StephenBarlow on the shoulder for some copy help).

$ rover contract describe my-graph@my-contract-variant
Fetching description for configuration of my-graph@my-contract-variant using credentials from the default profile.

Configuration Description:

"my-graph@my-contract-variant" is derived from "my-graph@my-source-variant".

Included tags:

- "foo"
- "bar"

Excluded tags:

- "baz"

All unreachable types are hidden.

View the variant's full configuration at https://studio.apollographql.com/graph/my-graph/settings/variant?variant=my-contract-variant

💡 You can re-create this contract by running `rover contract publish my-graph@my-contract-variant --source-variant my-source-variant --include foo --include bar --exclude baz --hide-unreachable-types`

I think that callout at the end would be super helpful, especially for folks with existing contracts who want to port their contracts to CI.

[sachindshinde]

@EverlastingBugstopper

After reading the docs PR (and re-learning about contracts) it looks like these includes/excludes are only related to tags, making me think we should rename --include and --no-include to --include-tags and --no-include-tags if we think we might have different filter kinds down the line.

I'm down to rename to --include-tag and --no-include-tags. I'm not aware of any other kinds of including/excluding we'll be doing, but it definitely clarifies (it's not that much extra to type either for users).

Alllsssoo, I think it would be super helpful if rover contract describe spit out a suggestion for how to create that same contract (and let's tap @StephenBarlow on the shoulder for some copy help).

I think changing the description to be formatted like

"my-graph@my-contract-variant" is derived from "my-graph@my-source-variant".

Included tags:

- "foo"
- "bar"

Excluded tags:

- "baz"

All unreachable types are hidden.

is fine, I can file a quick backend PR for that.

Agreed that giving folks a command to recreate the contract would be nice, although it'll take adding another field to the platform API. Would you be down if we shift that to follow-up work?

[sachindshinde]

@EverlastingBugstopper
PR should be ready for review again. Some notes:

• As per @caydie-tran 's request, I've taken the changes she and I pushed up in Introduce contracts commands to Rover docs #1473 and cherry-picked them onto this PR.
• I've updated the arguments to be --include-tag/--no-include-tags and --exclude-tag/--no-exclude-tags (using singular for the non-zero case, since users specify one tag name per invocation), and updated docs accordingly.
• I've updated the configuration description output to be formatted in the styling you've suggested above (with some tweaks to wording). I've updated the example in the docs as well.

I'll file tickets for the remaining follow-up work (adding keep-old-value capabilities and showing users a command to recreate a variant) sometime tomorrow.

[EverlastingBugstopper]

Sounds good to me on getting the command construction in a follow-up. That being said, I think it might be easier to just include that code directly in Rover itself. If we keep backwards compatibility, it should be fine to just construct that on Rover's side so we can update usage down the line but old versions will continue to output the correct command suggestion.

[EverlastingBugstopper]

Two API errors I ran into during QA that were not the nicest:

$ rover contract publish averys-supercloud@contract --source-variant averys-supercloud@current --hide-unreachable-types --no-include-tags --no-exclude-tag
s
Publishing configuration to averys-supercloud@contract using credentials from the default profile.

error: Exception while fetching data (/graph/upsertContractVariant) : NOT_ALLOWED_BY_USER_ROLE
$ rover contract publish averys-supercloud@contract --source-variant averys-supercloud@current --hide-unreachable-types --no-include-tags --no-exclude-tags --profile github
Publishing configuration to averys-supercloud@contract using credentials from the github profile.

error: Exception while fetching data (/graph/upsertContractVariant) : Your accounts does not include access to contracts

[sachindshinde]

@EverlastingBugstopper

Sounds good to me on getting the command construction in a follow-up. That being said, I think it might be easier to just include that code directly in Rover itself. If we keep backwards compatibility, it should be fine to just construct that on Rover's side so we can update usage down the line but old versions will continue to output the correct command suggestion.

Makes sense. When we get around to YAML configs, I imagine there will be a way to fetch a config file from the backend, and if Rover sees it can't parse it fully (e.g. sees new options/a version it doesn't know about), it could notify the user to upgrade to latest.

Two API errors I ran into during QA that were not the nicest:

Yeah, we don't have a nice system/pattern for permission/capability errors unfortunately 😢

[EverlastingBugstopper]

i tried specifying --source-variant as averys-supercloud@current instead of just current and got an expected but unfortunately confusing error message as a result:

$ APOLLO_REGISTRY_URL="https://api-staging.apollographql.com/graphql" rover contract publish averys-supercloud-staging@contract --source-variant averys-su
percloud-staging@current --hide-unreachable-types --no-include-tags --no-exclude-tags
Publishing configuration to averys-supercloud-staging@contract using credentials from the staging profile.

error[E040]: While publishing the contract configuration and triggering launch, the following error occurred:
The source variant "averys-supercloud-staging@current" does not exist.

we could add in a check if there is an @ included, and if there is, run GraphRef::parse. then we just use the extracted variant name if it parses correctly and the graph id matches the contract graph id you're trying to create

[sachindshinde]

Unfortunately, we have some existing legacy variants in production that use the @ symbol in their variant name, so we can't unambiguously tell whether a string that represents a variant name or a graph ref is one or the other 😢 .

We could have two arguments: one named --source-variant and one named --source-variant-name (the first taking a graph ref, and the second taking a variant name), and put them in an optional ArgGroup. Would that be fine here?

[EverlastingBugstopper]

hmm - could we just call GraphRef::parse() on it directly and see if it spits out a variant? there's a regex in there that could help. I think the existing --source-variant argument is perfectly fine and we shouldn't add in --source-variant-name in addition, I'm just anticipating that this could be a common mistake (typing the full graph ref instead of just the variant) that we could handle a bit better. Specifically, seeing the text The source variant "averys-supercloud-staging@current" does not exist. for a variant that does exist is really confusing.

[sachindshinde]

Giving an update here -- we're going to change the backend API to accept both graph refs and variant names for sourceVariant.