Proposal

Create an AstHelper class with well defined and tested methods to perform common operations on the abstract syntax tree.

Methods

• getRecursivelyReferencedFragments() - Given a node in the AST, return all fragments referenced by the node.
• detectDeprecatedFields() - Given a query and a reference to a graphql schema, detect if the query references any fields marked deprecated by the schema.

Implementation

getRecursivelyReferencedFragments()

We don't want to traverse the whole tree here so we will use a modified depth first search. In pseudo code:

List<Fragment> getRecursivelyReferencedFragments(Node operation) {
  List fragments = [];
  Set<String> collectedNames = Set<String>();
  Array<SelectionSetNode> nodesToVisit = Stack<Node>;
  nodesToVisit.push(operation);
  while ((node = nodesToVisit.pop())) {
		List<Node> fragmentSpreads = getFragmentSpreads(node);
    for (spread in fragmentSpreads) {
      const fragName = spread.name;
      if (collectedNames[fragName] !== true) {
        collectedNames[fragName] = true;
        fragments.push(spread);
        nodesToVisit.push(fragment.getChildren());
      }
    }
  }
  return fragments;
}

List<Fragment> getFragmentSpreads(Node root) {
	// Use NodeTraverser to walk the subtree, and return all fragment spreads
}

detectDeprecatedFields()

Detecting deprecated fields is more straightforwards. We can use the QueryTraverser visitor pattern. In (mostly) pseudo code:

List<Node> detectDeprecatedFields(Document document, Schema graphqlSchema) {
	QueryTraverser queryTraverser = QueryTraverser.newQueryTraverser()
	                .document(document)
	                .operationName(operation)
	                .schema(graphQLSchema)
	                .variables(variables)
	                .build();
	
	final List<String> deprecatedFieldList = new ArrayList<>();
	queryTraverser.visitPreOrder(new QueryVisitorStub() {
	    @Override
	    public TraversalControl visitFieldWithControl(QueryVisitorFieldEnvironment fieldEnvironment) {
	        collectDeprecated(fieldEnvironment, deprecatedFieldList);
	        return TraversalControl.CONTINUE;
	    }
	});
	return deprecatedFieldList;
}

Testing

We will write unit tests in Groovy to achieve 100% code coverage AstHelper class. I am unaware of any other testing requirements, please let me know if I am missing anything.

Extension

We can evolve this class in the future to add more functionality. For example:

• normalizeExecutableQuery() - Given a query, return a normalized version. his represents the AST collapsed into its eventual "field" with schema types and so on all resolved.

Open Questions

Where in the directory structure should this class live?
My initial thought is src/main/java/graphql/AstHelper.java