Another docs & API pass (#945)

Co-authored-by: Iryna Shestak <[email protected]>

Author: SimonSapin

ARCHITECTURE.md

@@ -7,8 +7,8 @@ This document gives an overview of how various bits of `apollo-rs` work together
 theme for Rust as a language, and we want to make sure that all component APIs
 we provide are aligned with these principles.
 
-2. **Stability and reliability.** Spec-compliant, and idempotent APIs which,
-when complete, can be used safely in enterprise-grade codebases.
+2. **Stability and reliability.** Spec-compliant and idempotent APIs
+which can be used safely in enterprise-grade codebases.
 
 3. **Diagnostics.** The tools are to be written in a way that will allow us to
 produce detailed diagnostics. It does not panic or return early if there is a
@@ -20,19 +20,17 @@ maintaining this project.
 4. **Extensibility.** The parser is written to work with different use cases in
 our budding Rust GraphQL ecosystem, be it building schema-diagnostics for Rover,
 or writing out query planning and composition algorithms in Rust. These all have
-quite different requirements when it comes to CST manipulation. We wanted to
+quite different requirements when it comes to document manipulation. We wanted to
 make sure we account for them early on.
 
 ## `apollo-parser`
 
 `apollo-parser` is the parser crate of `apollo-rs`. Its job is to take GraphQL
-queries or schemas as input and produce an Concrete Syntax Tree (CST). Users of
-apollo-parser can then programmatically traverse the CST to get information
-about their input. 
+queries or schemas as string input and produce an Concrete Syntax Tree (CST).
+Users of apollo-parser can then programmatically traverse the CST to get information
+about their input.
 
-There are three main components of `apollo-parser`: the lexer, the parser, and the analyser. We already have the lexer and the parser, and the analyser is in the process of getting written.
-
-![An overview of apollo-parser diagram. We initially start of with input data. A Lexer performs lexical analysis on the data and produces tokens. Tokens get syntactically analysed by the parser, first into an untyped syntax tree, then into a typed syntax tree. "Future Work" indicates that a typed syntax tree will be semantically analysed by the "Analyser" to produce a semantic model.](images/apollo-parser-overview.png)
+There are two main components of `apollo-parser`: the lexer and the parser.
 
 `apollo-parser` is a hand-written recursive-descent parser. This is a type of
 parser that starts from the top of a file and recursively walks its way down
@@ -66,7 +64,8 @@ if has_exponent || has_fractional {
 }
 ```
 
-The lexer returns a `Vec<Token>` and `Vec<Error>` that the parser then uses to create a tree. If the error vec is empty, we can be sure that the input is lexically correct!
+The lexer is an iterator of `Result<Token, Error>` that the parser then uses to create a tree.
+If no error is emitted, we can be sure that the input is lexically correct!
 
 ### Parser
 The next step in our parsing pipeline is the parser. The parser’s job is to take the tokens produced by the lexer and create nodes with information and relationships that in the end make up a syntax tree. Much like with the lexer, the parser is error resilient. Syntactic errors, such as a missing `Name` in a `ScalarDefinition`, are added to parser’s error vector while the parser carries on parsing.

README.md

@@ -2,7 +2,7 @@
   <h1><code>apollo-rs</code></h1>
 
   <p>
-    <strong>Rust tooling for low-level manipulation of the GraphQL language.</strong>
+    <strong>Rust tooling for manipulation of the GraphQL language.</strong>
   </p>
 </div>
 
@@ -14,26 +14,23 @@ these libraries is specific to Apollo, and can freely be used by other
 projects which need standards-compliant GraphQL tooling written in Rust. The
 following crates currently exist:
 
-* [**`apollo-compiler`**](crates/apollo-compiler/) - a library to compile and semantically analyze GraphQL query language.
-* [**`apollo-parser`**](crates/apollo-parser) - a library to parse the GraphQL query language.
-* [**`apollo-smith`**](crates/apollo-smith) - a test case generator to test GraphQL code (SDL).
+* [**`apollo-compiler`**](crates/apollo-compiler/) - a library to manipulate, semantically analyze, and validate GraphQL schema definition and query language
+* [**`apollo-parser`**](crates/apollo-parser) - a library to parse the GraphQL (used by `apollo-compiler`)
+* [**`apollo-smith`**](crates/apollo-smith) - a test case generator to deterministically produce arbitrary GraphQL documents
 
 Please check out their respective READMEs for usage examples.
 
 ## Status
-`apollo-rs` is a work in progress. Please check out the
-[ROADMAP](ROADMAP.md) for upcoming features we are working on building.
-
-If you do end up trying out `apollo-rs` and run into trouble, we encourage you 
-to open an [issue].
+`apollo-rs` is a living project that keeps evolving and is being used in production.
+If you try out `apollo-rs` and run into trouble, we encourage you to open an [issue].
 
 ## Design Principles
 1. **Prioritizing developer experience.** Elegant and ergonomic APIs is the
 theme for Rust as a language, and we want to make sure that all component APIs
 we provide are aligned with these principles.
 
-2. **Stability and reliability.** Spec-compliant, and idempotent APIs which,
-when complete, can be used safely in enterprise-grade codebases.
+2. **Stability and reliability.** Spec-compliant, and idempotent APIs
+which can be used safely in enterprise-grade codebases.
 
 3. **Diagnostics.** The tools are to be written in a way that will allow us to
 produce detailed diagnostics. It does not panic or return early if there is a
@@ -45,7 +42,7 @@ maintaining this project.
 4. **Extensibility.** The parser is written to work with different use cases in
 our budding Rust GraphQL ecosystem, be it building schema-diagnostics for Rover,
 or writing out query planning and composition algorithms in Rust. These all have
-quite different requirements when it comes to AST manipulation. We wanted to
+quite different requirements when it comes to document manipulation. We wanted to
 make sure we account for them early on.
 
 ## Rust versions

ROADMAP.md

@@ -25,8 +25,10 @@
   created or modified programatically,
   and serialized.
 * Validation of schemas and executable documents, as defined [in the GraphQL specification][val].
+* Execution of the [schema introspection][introsp] portion of queries.
 
 [val]: https://spec.graphql.org/October2021/#sec-Validation
+[introsp]: https://spec.graphql.org/October2021/#sec-Introspection
 
 ## Getting started
 Add the dependency to start using `apollo-compiler`:
@@ -53,39 +55,19 @@ Older version may or may not be compatible.
 You can get started with `apollo-compiler`:
 ```rust
 use apollo_compiler::Schema;
+use apollo_compiler::ExecutableDocument;
 
-let input = r#"
-  interface Pet {
-    name: String
-  }
-
-  type Dog implements Pet {
-    name: String
-    nickname: String
-    barkVolume: Int
-  }
-
-  type Cat implements Pet {
-    name: String
-    nickname: String
-    meowVolume: Int
-  }
-
-  union CatOrDog = Cat | Dog
-
-  type Human {
-    name: String
-    pets: [Pet]
-  }
-
+let sdl = r#"
   type Query {
-    human: Human
+    field: Int
   }
 "#;
+let query = "{ field }";
 
 /// In case of validation errors, the panic message will be nicely formatted
 /// to point at relevant parts of the source file(s)
-let schema = Schema::parse_and_validate(input, "document.graphql").unwrap();
+let schema = Schema::parse_and_validate(sdl, "sdl.graphql").unwrap();
+let doc = ExecutableDocument::parse_and_validate(&schema, query, "query.graphql").unwrap();
 ```
 
 ### Examples
@@ -147,31 +129,22 @@ use apollo_compiler::{Schema, ExecutableDocument, Node, executable};
 let schema_input = r#"
 type Query {
   topProducts: Product
-  name: String
-  size: Int
 }
 
 type Product {
   inStock: Boolean @join__field(graph: INVENTORY)
   name: String @join__field(graph: PRODUCTS)
-  price: Int
-  shippingEstimate: Int
-  upc: String!
-  weight: Int
 }
 
 enum join__Graph {
   INVENTORY,
   PRODUCTS,
 }
-scalar join__FieldSet
-directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
+directive @join__field(graph: join__Graph) on FIELD_DEFINITION
 "#;
 let query_input = r#"
 query getProduct {
-  size
   topProducts {
-    name
     inStock
   }
 }
@@ -206,63 +179,11 @@ assert_eq!(in_stock_directive, ["join__field"]);
 
 #### Printing diagnostics for a faulty GraphQL document
 ```rust
-let input = r#"
-query {
-  cat {
-    name
-  }
-}
-
-query getPet {
-  cat {
-    owner {
-      name
-    }
-  }
-}
-
-query getPet {
-  cat {
-    treat
-  }
-}
+use apollo_compiler::parser::Parser;
 
-subscription sub {
-  newMessage {
-    body
-    sender
-  }
-  disallowedSecondRootField
-}
-
-type Query {
-  cat: Pet
-}
-
-type Subscription {
-  newMessage: Result
-}
-
-interface Pet {
-  name: String
-}
-
-type Dog implements Pet {
-  name: String
-  nickname: String
-  barkVolume: Int
-}
-
-type Cat implements Pet {
-  name: String
-  nickname: String
-  meowVolume: Int
-}
-
-union CatOrDog = Cat | Dog
-"#;
+let input = "{ ... }";
 
-if let Err(diagnostics) = apollo_compiler::parse_mixed_validate(input, "document.graphql") {
+if let Err(diagnostics) = Parser::new().parse_mixed_validate(input, "document.graphql") {
     println!("{diagnostics}")
 }
 ```

crates/apollo-compiler/README.md

@@ -1,5 +1,6 @@
 use anyhow::anyhow;
 use anyhow::Result;
+use apollo_compiler::parser::Parser;
 use apollo_compiler::validation::Valid;
 use apollo_compiler::ExecutableDocument;
 use apollo_compiler::Schema;
@@ -112,7 +113,9 @@ impl FileWatcher {
         src_path: PathBuf,
     ) -> Result<PathBuf, anyhow::Error> {
         let full_path = fs::canonicalize(&src_path)?;
-        let doc = apollo_compiler::parse_mixed_validate(proposed_document, src_path).unwrap();
+        let doc = Parser::new()
+            .parse_mixed_validate(proposed_document, src_path)
+            .unwrap();
         self.manifest.insert(full_path.clone(), doc);
         Ok(full_path)
     }

crates/apollo-compiler/examples/file_watcher.rs

@@ -1,4 +1,5 @@
 use apollo_compiler::executable;
+use apollo_compiler::parser::Parser;
 use apollo_compiler::Node;
 use std::fs;
 use std::path::Path;
@@ -7,7 +8,7 @@ fn compile_query() -> Option<Node<executable::Fragment>> {
     let file = Path::new("crates/apollo-compiler/examples/query_with_errors.graphql");
     let src = fs::read_to_string(file).expect("Could not read schema file.");
 
-    let (_, document) = apollo_compiler::parse_mixed_validate(src, file).unwrap();
+    let (_, document) = Parser::new().parse_mixed_validate(src, file).unwrap();
     let operation_names: Vec<_> = document
         .operations
         .named

crates/apollo-compiler/examples/hello_world.rs

@@ -1,4 +1,4 @@
-use apollo_compiler::parse_mixed_validate;
+use apollo_compiler::parser::Parser;
 use apollo_compiler::ExecutableDocument;
 use apollo_compiler::Schema;
 use std::fs;
@@ -19,7 +19,9 @@ fn compile_from_dir() -> io::Result<()> {
         for entry in fs::read_dir(dir)? {
             let entry = entry?;
             let src = fs::read_to_string(entry.path()).expect("Could not read document file.");
-            let (_schema, _executable) = parse_mixed_validate(&src, entry.path()).unwrap();
+            let (_schema, _executable) = Parser::new()
+                .parse_mixed_validate(&src, entry.path())
+                .unwrap();
         }
     }
     Ok(())

crates/apollo-compiler/examples/multi_source_validation.rs

@@ -1,3 +1,4 @@
+use apollo_compiler::parser::Parser;
 use std::io::Read;
 use std::process::ExitCode;
 
@@ -19,7 +20,7 @@ fn main() -> ExitCode {
         ),
     };
 
-    match apollo_compiler::parse_mixed_validate(source, filename) {
+    match Parser::new().parse_mixed_validate(source, filename) {
         Ok((_schema, _executable)) => ExitCode::SUCCESS,
         Err(errors) => {
             eprintln!("{errors:?}");