Visibility followups (#174)

Author: gmac

docs/visibility.md

@@ -1,8 +1,8 @@
 # Visibility
 
-Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences.
+Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences, and provides a flexible analog to Apollo Federation's `@inaccessible` rule.
 
-Under the hood, this system wraps `GraphQL::Schema::Visibility` (with nil profile support) and requires at least GraphQL Ruby v2.5.3.
+Under the hood, this system wraps [GraphQL visibility](https://graphql-ruby.org/authorization/visibility) (specifically, the newer `GraphQL::Schema::Visibility` with nil profile support) and requires at least GraphQL Ruby v2.5.3.
 
 ## Example
 
@@ -41,7 +41,7 @@ type Query {
 }
 ```
 
-When composing a stitching client, the names of all possible visibility profiles that the supergraph should respond to must be specified in composer options:
+When composing a stitching client, the names of all possible visibility profiles that the supergraph should respond to are specified in composer options:
 
 ```ruby
 client = GraphQL::Stitching::Client.new(
@@ -61,7 +61,7 @@ client = GraphQL::Stitching::Client.new(
 )
 ```
 
-The client can then execute requests with a `visibility_profile` parameter in context that specifies the name of any profile the supergraph was composed with:
+The client can then execute requests with a `visibility_profile` parameter in context that specifies one of these names:
 
 ```ruby
 query = %|{
@@ -84,7 +84,7 @@ The `visibility_profile` parameter will select which visibility distribution to
 - Using `visibility_profile: "private"` will accesses the `msrp` field as usual. 
 - Providing no profile parameter (or `visibility_profile: nil`) will access the entire graph without any visibility constraints.
 
-The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for the stitching implementation.
+The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for use by the stitching implementation.
 
 ## Adding visibility directives
 
@@ -165,4 +165,14 @@ type Query {
 }
 ```
 
-In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it.
+In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it. You can review materialized visibility profiles by printing their respective schemas:
+
+```ruby
+public_schema = client.supergraph.to_definition(visibility_profile: "public")
+File.write("schemas/supergraph_public.graphql", public_schema)
+
+private_schema = client.supergraph.to_definition(visibility_profile: "private")
+File.write("schemas/supergraph_private.graphql", private_schema)
+```
+
+It's helpful to commit these outputs to your repo where you can monitor their diffs during the PR process.

lib/graphql/stitching/supergraph.rb

@@ -58,8 +58,10 @@ def initialize(schema:, fields: {}, resolvers: {}, visibility_profiles: [], exec
         end
       end
 
-      def to_definition
-        @schema.to_definition
+      def to_definition(visibility_profile: nil)
+        @schema.to_definition(context: { 
+          visibility_profile: visibility_profile,
+        }.tap(&:compact!))
       end
 
       def resolvers_by_version

test/graphql/stitching/supergraph/visibility_test.rb

@@ -24,6 +24,37 @@ def test_activates_visibility_profile_definitions_and_nil_profile
     assert_equal ["", "private", "public"], profiles.sort
   end
 
+  def test_to_definition_prints_specific_profile
+    schema_sdl = %|
+      #{visibility_definition_with_profiles(["public", "private"])}
+      type Query { 
+        a: String
+        b: String @visibility(profiles: ["private"])
+        c: String @visibility(profiles: [])
+      }
+    |
+
+    expected_public = %|
+      #{visibility_definition_with_profiles(["public", "private"])}
+      type Query { 
+        a: String
+      }
+    |
+
+    expected_private = %|
+      #{visibility_definition_with_profiles(["public", "private"])}
+      type Query { 
+        a: String
+        b: String @visibility(profiles: ["private"])
+      }
+    |
+
+    supergraph = GraphQL::Stitching::Supergraph.from_definition(schema_sdl, executables: @exec)
+    assert_equal squish_string(schema_sdl), squish_string(supergraph.to_definition)
+    assert_equal squish_string(expected_public), squish_string(supergraph.to_definition(visibility_profile: "public"))
+    assert_equal squish_string(expected_private), squish_string(supergraph.to_definition(visibility_profile: "private"))
+  end
+
   def test_controls_field_visibility
     schema_sdl = %|
       #{visibility_definition_with_profiles(["public", "private"])}
@@ -337,7 +368,7 @@ def test_controls_union_visibility
   def visibility_definition_with_profiles(profiles)
     VISIBILITY_DEFINITION.sub(
       %|@visibility(profiles: [String!]!)|, 
-      %|@visibility(profiles: [String!]! = #{profiles.to_json})|,
+      %|@visibility(profiles: [String!]! = #{profiles.to_json.gsub!(%|","|, %|", "|)})|,
     )
   end
 

test/test_helper.rb

@@ -20,7 +20,7 @@
 CompositionError = GraphQL::Stitching::CompositionError
 ValidationError = GraphQL::Stitching::ValidationError
 STITCH_DEFINITION = "directive @stitch(key: String!, arguments: String, typeName: String) repeatable on FIELD_DEFINITION\n"
-VISIBILITY_DEFINITION = "directive @visibility(profiles: [String!]!) on OBJECT | INTERFACE | UNION | INPUT_OBJECT | ENUM | SCALAR | FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE\n"
+VISIBILITY_DEFINITION = "directive @visibility(profiles: [String!]!) on ARGUMENT_DEFINITION | ENUM | ENUM_VALUE | FIELD_DEFINITION | INPUT_FIELD_DEFINITION | INPUT_OBJECT | INTERFACE | OBJECT | SCALAR | UNION\n"
 
 class Matcher
   def match?(value)