Schema documentation transformation - #4 (#160)

fixes #4 

---------

Co-authored-by: James Mortemore <[email protected]>

Author: velias

README.md

@@ -306,6 +306,81 @@ app.use(
 app.listen(4000);
 
 ```
+### Schema documentation
+
+You can use the provided schema transformation to automatically add `@constraint` documentation into fields and arguments descriptions. By default directives are not typically present in the exposed introspected schema
+
+```js
+const { constraintDirectiveTypeDefs, constraintDirectiveDocumentation } = require('graphql-constraint-directive')
+const { makeExecutableSchema } = require('@graphql-tools/schema')
+
+const typeDefs = ...
+
+let schema = makeExecutableSchema({
+      typeDefs: [constraintDirectiveTypeDefs, typeDefs]
+})
+
+schema = constraintDirectiveDocumentation()(schema);
+
+// any constraint directive handler implementation
+```
+
+This transformation appends `constraint documentation header`, and then a list of `constraint conditions descriptions` to the description of each field and argument where the `@constraint` directive is used.
+
+Original schema:
+```graphql
+"""
+Existing field or argument description.
+"""
+fieldOrArgument: String @constraint(minLength: 10, maxLength: 50)
+```
+
+Transformed schema:
+```graphql
+"""
+Existing field or argument description.
+
+*Constraints:*
+* Minimum length: `10`
+* Maximum length: `50`
+"""
+fieldOrArgument: String @constraint(minLength: 10, maxLength: 50)
+```
+
+[CommonMark](https://spec.commonmark.org) is used in the desccription for better readability.
+
+If `constraint documentation header` already exists in the field or argument description, then
+constraint documentation is not appended. This allows you to override constraint description
+when necessary, or use this in a chain of subgraph/supergraph schemes.
+
+Both `constraint documentation header` and `constraint conditions descriptions` can be customized
+during the transformation creation, eg. to localize them.
+
+```js
+schema = constraintDirectiveDocumentation(
+  {
+    header: '*Changed header:*',
+    descriptionsMap: {
+      minLength: 'Changed Minimum length',
+      maxLength: 'Changed Maximum length',
+      startsWith: 'Changed Starts with',
+      endsWith: 'Changed Ends with',
+      contains: 'Changed Contains',
+      notContains: 'Changed Doesn\'t contain',
+      pattern: 'Changed Must match RegEx pattern',
+      format: 'Changed Must match format',
+      min: 'Changed Minimum value',
+      max: 'Changed Maximum value',
+      exclusiveMin: 'Changed Grater than',
+      exclusiveMax: 'Changed Less than',
+      multipleOf: 'Changed Must be a multiple of',
+      minItems: 'Changed Minimum number of items',
+      maxItems: 'Changed Maximum number of items'
+    }
+  }
+)(schema);
+```
+
 
 ## API
 ### String

index.d.ts

@@ -2,14 +2,68 @@ import {GraphQLSchema, GraphQLError, DocumentNode, ValidationContext} from "grap
 import {PluginDefinition} from "apollo-server-core";
 import QueryValidationVisitor from "./lib/query-validation-visitor";
 
+/**
+ * Schema transformer which adds custom types performing validations based on the @constraint directives.
+ */
 export function constraintDirective () : (schema: GraphQLSchema) => GraphQLSchema;
 
+interface DocumentationOptions {
+    /** Header for the constraints documentation block in the field or argument description */
+    header?: string;
+    /** Names for distinct constraint types */
+    descriptionsMap?: {
+        minLength: string,
+        maxLength: string,
+        startsWith: string,
+        endsWith: string,
+        contains: string,
+        notContains: string,
+        pattern: string,
+        format: string,
+        min: string,
+        max: string,
+        exclusiveMin: string,
+        exclusiveMax: string,
+        multipleOf: string,
+        minItems: string,
+        maxItems: string
+    };
+}
+
+/**
+ * Schema transformer which adds @constraint directives documentation to the fields and arguments descriptions.
+ * Documentation not added if it already exists (`header` is present in the field or argument description)
+ * 
+ * @param options options to customize the documentation process
+ */
+export function constraintDirectiveDocumentation (options: DocumentationOptions) : (schema: GraphQLSchema) => GraphQLSchema;
+
+/**
+ * Type definition for @constraint directive.
+ */
 export const constraintDirectiveTypeDefs: string
 
+/**
+ * Method for query validation based on the @constraint directives defined in the schema.
+ * 
+ * @param schema GraphQL schema to look for directives
+ * @param query GraphQL query to validate
+ * @param variables used in the query to validate
+ * @param operationName optional name of the GraphQL operation to validate
+ */
 export function validateQuery () : (schema: GraphQLSchema, query: DocumentNode, variables: Record<string, any>, operationName?: string) => Array<GraphQLError>;
 
+/**
+ * Create Apollo 3 plugin performing query validation.
+ */
 export function createApolloQueryValidationPlugin ( options: { schema: GraphQLSchema } ) : PluginDefinition;
 
+/**
+ * Create JS GraphQL Validation Rule performing query validation.
+ */
 export function createQueryValidationRule( options: { [key: string]: any }) : (context: ValidationContext) => QueryValidationVisitor;
 
+/**
+ * Create Envelop plugin performing query validation.
+ */
 export function createEnvelopQueryValidationPlugin() : object;

index.js

@@ -6,12 +6,13 @@ const {
   visit,
   visitWithTypeInfo,
   separateOperations,
-  GraphQLError
+  GraphQLError,
+  getDirectiveValues
 } = require('graphql')
 const QueryValidationVisitor = require('./lib/query-validation-visitor.js')
 const { getDirective, mapSchema, MapperKind } = require('@graphql-tools/utils')
 const { getConstraintTypeObject, getScalarType } = require('./lib/type-utils')
-const { constraintDirectiveTypeDefs } = require('./lib/type-defs')
+const { constraintDirectiveTypeDefs, constraintDirectiveTypeDefsObj } = require('./lib/type-defs')
 
 function constraintDirective () {
   const constraintTypes = {}
@@ -95,6 +96,77 @@ function constraintDirective () {
     })
 }
 
+function constraintDirectiveDocumentation (options) {
+  // Default descriptions, can be changed through options
+  let DESCRIPTINS_MAP = {
+    minLength: 'Minimal length',
+    maxLength: 'Maximal length',
+    startsWith: 'Starts with',
+    endsWith: 'Ends with',
+    contains: 'Contains',
+    notContains: 'Doesn\'t contain',
+    pattern: 'Must match RegEx pattern',
+    format: 'Must match format',
+    min: 'Minimal value',
+    max: 'Maximal value',
+    exclusiveMin: 'Grater than',
+    exclusiveMax: 'Less than',
+    multipleOf: 'Must be a multiple of',
+    minItems: 'Minimal number of items',
+    maxItems: 'Maximal number of items'
+  }
+
+  if (options?.descriptionsMap) {
+    DESCRIPTINS_MAP = options.descriptionsMap
+  }
+
+  let HEADER = '*Constraints:*'
+  if (options?.header) {
+    HEADER = options.header
+  }
+
+  function documentConstraintDirective (fieldConfig, directiveArgumentMap) {
+    if (fieldConfig.description) {
+      // skip documentation if it is already here
+      if (fieldConfig.description.includes(HEADER)) return
+
+      // add two new lines to separate from previous description by paragraph
+      fieldConfig.description += '\n\n'
+    } else {
+      fieldConfig.description = ''
+    }
+
+    fieldConfig.description += HEADER + '\n'
+
+    Object.entries(directiveArgumentMap).forEach(([key, value]) => {
+      if (key === 'uniqueTypeName') return
+      fieldConfig.description += `* ${DESCRIPTINS_MAP[key] ? DESCRIPTINS_MAP[key] : key}: \`${value}\`\n`
+    })
+  }
+
+  return (schema) =>
+    mapSchema(schema, {
+      [MapperKind.FIELD]: (fieldConfig) => {
+        const directiveArgumentMap = getDirectiveValues(constraintDirectiveTypeDefsObj, fieldConfig.astNode)
+
+        if (directiveArgumentMap) {
+          documentConstraintDirective(fieldConfig, directiveArgumentMap)
+
+          return fieldConfig
+        }
+      },
+      [MapperKind.ARGUMENT]: (fieldConfig) => {
+        const directiveArgumentMap = getDirectiveValues(constraintDirectiveTypeDefsObj, fieldConfig.astNode)
+
+        if (directiveArgumentMap) {
+          documentConstraintDirective(fieldConfig, directiveArgumentMap)
+
+          return fieldConfig
+        }
+      }
+    })
+}
+
 function validateQuery (schema, query, variables, operationName) {
   const typeInfo = new TypeInfo(schema)
 
@@ -159,4 +231,4 @@ function createQueryValidationRule (options) {
   }
 }
 
-module.exports = { constraintDirective, constraintDirectiveTypeDefs, validateQuery, createApolloQueryValidationPlugin, createEnvelopQueryValidationPlugin, createQueryValidationRule }
+module.exports = { constraintDirective, constraintDirectiveDocumentation, constraintDirectiveTypeDefs, validateQuery, createApolloQueryValidationPlugin, createEnvelopQueryValidationPlugin, createQueryValidationRule }

package.json

@@ -6,6 +6,7 @@
   "types": "index.d.ts",
   "scripts": {
     "test": "standard && nyc --reporter=html --reporter=text --reporter=lcov mocha test/**/testsuite-full.js",
+    "test-documentation": "standard && nyc --reporter=html --reporter=text --reporter=lcov mocha test/**/testsuite-documentation.js",
     "test-schema-wrapper": "standard && nyc --reporter=html --reporter=text --reporter=lcov mocha test/**/testsuite-schema-wrapper.js",
     "test-apollo-plugin": "standard && nyc --reporter=html --reporter=text --reporter=lcov mocha test/**/testsuite-apollo-plugin.js",
     "test-apollo4-plugin": "standard && nyc --reporter=html --reporter=text --reporter=lcov mocha test/**/testsuite-apollo4-plugin.js",

test/snapshots/ws-1.txt

@@ -0,0 +1,50 @@
+directive @constraint(minLength: Int, maxLength: Int, startsWith: String, endsWith: String, contains: String, notContains: String, pattern: String, format: String, min: Float, max: Float, exclusiveMin: Float, exclusiveMax: Float, multipleOf: Float, minItems: Int, maxItems: Int, uniqueTypeName: String) on INPUT_FIELD_DEFINITION | FIELD_DEFINITION | ARGUMENT_DEFINITION
+
+type Query {
+  """Query books field documented"""
+  books(
+    "*Constraints:*\n* Minimal value: `1`\n* Maximal value: `3`\n"
+    size: Int
+
+    " Query argument documented \n\n*Constraints:*\n* Minimal length: `1`\n"
+    first: String
+  ): [Book]
+
+  """ Query book field documented """
+  book: Book
+}
+
+type Book {
+  "*Constraints:*\n* Maximal length: `10`\n"
+  title: String
+
+  "Book description already documented\n\n*Constraints:*\n* Minimal length: `10`\n* Maximal length: `50`\n"
+  description: String
+  authors(
+    "Book authors argument documented\n\n*Constraints:*\n* Maximal value: `4`\n"
+    size: Int
+
+    """
+    Already documented
+    
+    *Constraints:*
+    * Minimal length as documented: 1
+    """
+    first: String
+  ): [String]
+}
+
+type Mutation {
+  createBook(input: BookInput): Book
+}
+
+input BookInput {
+  "*Constraints:*\n* Minimal value: `3`\n"
+  title: Int!
+  author: AuthorInput
+}
+
+input AuthorInput {
+  "*Constraints:*\n* Minimal length: `2`\n"
+  name: String!
+}

test/snapshots/ws-2-2.txt

@@ -0,0 +1,45 @@
+directive @constraint(minLength: Int, maxLength: Int, startsWith: String, endsWith: String, contains: String, notContains: String, pattern: String, format: String, min: Float, max: Float, exclusiveMin: Float, exclusiveMax: Float, multipleOf: Float, minItems: Int, maxItems: Int, uniqueTypeName: String) on INPUT_FIELD_DEFINITION | FIELD_DEFINITION | ARGUMENT_DEFINITION
+
+type Query {
+  """Query books field documented"""
+  books(
+    "My header:\n* Minimal value: `1`\n* Maximal value: `3`\n"
+    size: Int
+
+    " Query argument documented \n\nMy header:\n* Minimal length: `1`\n"
+    first: String
+  ): [Book]
+
+  """ Query book field documented """
+  book: Book
+}
+
+type Book {
+  "My header:\n* Maximal length: `10`\n"
+  title: String
+
+  "Book description already documented\n\nMy header:\n* Minimal length: `10`\n* Maximal length: `50`\n"
+  description: String
+  authors(
+    "Book authors argument documented\n\nMy header:\n* Maximal value: `4`\n"
+    size: Int
+
+    "Already documented\n\n*Constraints:*\n* Minimal length as documented: 1\n\nMy header:\n* Minimal length: `1`\n"
+    first: String
+  ): [String]
+}
+
+type Mutation {
+  createBook(input: BookInput): Book
+}
+
+input BookInput {
+  "My header:\n* Minimal value: `3`\n"
+  title: Int!
+  author: AuthorInput
+}
+
+input AuthorInput {
+  "My header:\n* Minimal length: `2`\n"
+  name: String!
+}