Support @spectaql directive to ingest metadata

config-example.yml

@@ -79,6 +79,26 @@ introspection:
   #   - path/to/schema/part2.gql
   schemaFile: path/to/schema.gql
 
+
+  # Some helpful options for those who are an "SDL-first" shop and/or want to get your metadata into
+  # SpectaQL during the SDL ingestion.
+  spectaqlDirective:
+    # Boolean indicating whether to enable and process the @spectaql directive
+    #
+    # Default: true
+    enable: true
+
+    # String indicating the name to use for the SpectaQL directive
+    #
+    # Default: 'spectaql'
+    directiveName: 'spectaql'
+
+    # String indicating the name to use for the Type used in the "options" array that can be passed
+    # to the SpectaQL directive
+    #
+    # Default: 'SpectaQLOption'
+    optionsTypeName: 'SpectaQLOption'
+
   # File containing Introspection Query response in JS module export, or JSON format
   introspectionFile: path/to/introspection.js[on]
 

examples/config.yml

@@ -11,6 +11,9 @@ introspection:
   queryNameStrategy: capitalizeFirst
   fieldExpansionDepth: 2
 
+  spectaqlDirective:
+    enable: true
+
 extensions:
   graphqlScalarExamples: true
 

examples/data/schema.gql

@@ -41,7 +41,8 @@ interface MyInterface {
 
 "`Markdown` and reference interpolation like [`[String!]!`]({{Types.String}}) and [`myQuery`]({{Queries.myQuery}}) and [`myMutation`]({{Mutations.myMutation}}) are supported"
 type MyType implements MyInterface {
-  id: String!,
+  "I am an ID that will have my example value specified by the `@spectaql` directive"
+  id: String! @spectaql(options: [{key: "example", value: "\"idFromDirective\"" }]),
   url: URL,
   json: JSON,
   jso: JSONObject,
@@ -64,6 +65,9 @@ type MyType implements MyInterface {
   requiredArrayField: [String]!
 
   doubleRequiredArrayField: [String!]!
+
+  "This field will not show up thanks to the @spectaql directive options"
+  fieldThatWillNotShowUp: String! @spectaql(options: [{key: "undocumented", value: "true" }])
 }
 
 "This is a type that should probably be undocumented. Metadata will indicate this should be hidden"

index.js

@@ -6,6 +6,9 @@ const {
   loadData,
   buildSchemas,
   augmentData,
+  generateSpectaqlSdl,
+  generateDirectiveSdl,
+  generateOptionsSdl,
 } = require('./dist')
 
 module.exports = run
@@ -15,3 +18,6 @@ module.exports.resolveOptions = resolveOptions
 module.exports.loadData = loadData
 module.exports.buildSchemas = buildSchemas
 module.exports.augmentData = augmentData
+module.exports.generateSpectaqlSdl = generateSpectaqlSdl
+module.exports.generateDirectiveSdl = generateDirectiveSdl
+module.exports.generateOptionsSdl = generateOptionsSdl

package.json

@@ -65,6 +65,8 @@
     "@anvilco/grunt-embed": "^0.0.1",
     "@graphql-tools/load-files": "^6.3.2",
     "@graphql-tools/merge": "^8.1.2",
+    "@graphql-tools/schema": "^8.5.0",
+    "@graphql-tools/utils": "^8.8.0",
     "cheerio": "^1.0.0-rc.10",
     "coffeescript": "^2.6.1",
     "commander": "^9.1.0",
@@ -90,7 +92,7 @@
     "json5": "^2.2.0",
     "lodash": "^4.17.12",
     "marked": "^4.0.12",
-    "microfiber": "^1.1.0",
+    "microfiber": "^1.3.0",
     "sass": "^1.32.13",
     "sync-request": "^6.1.0",
     "tmp": "0.2.1"

src/index.js

@@ -12,6 +12,12 @@ import {
   pathToRoot,
 } from './spectaql/utils'
 
+export {
+  generateSpectaqlSdl,
+  generateDirectiveSdl,
+  generateOptionsSdl,
+} from './spectaql/directive'
+
 export { default as parseCliOptions } from './cli'
 
 const defaultAppDir = normalizePathFromRoot('dist')
@@ -64,9 +70,17 @@ const spectaqlOptionDefaults = Object.freeze({
   displayAllServers: false,
 })
 
+const spectaqlDirectiveDefault = Object.freeze({
+  enable: true,
+  directiveName: 'spectaql',
+  optionsTypeName: 'SpectaQLOption',
+})
+
 const introspectionOptionDefaults = Object.freeze({
   dynamicExamplesProcessingModule: false,
 
+  spectaqlDirective: Object.assign({}, spectaqlDirectiveDefault),
+
   removeTrailingPeriodFromDescriptions: false,
 
   fieldExpansionDepth: 1,
@@ -213,6 +227,11 @@ export function resolveOptions(cliOptions) {
     introspectionOptionDefaults
   )
 
+  opts.specData.introspection.spectaqlDirective = _.defaults(
+    opts.specData.introspection.spectaqlDirective,
+    spectaqlDirectiveDefault
+  )
+
   opts.specData.extensions = _.defaults(
     {},
     opts.specData.extensions,

src/spectaql/build-schemas.js

@@ -6,7 +6,10 @@ import {
   graphQLSchemaFromIntrospectionResponse,
 } from './graphql-loaders'
 
-import { addMetadataFromFile } from './metadata-loaders'
+import {
+  addMetadataFromFile,
+  addMetadataFromDirectables,
+} from './metadata-loaders'
 
 import {
   augmentData,
@@ -24,6 +27,7 @@ export function buildSchemas(opts) {
   const {
     introspection: introspectionOptions,
     introspection: {
+      spectaqlDirective: spectaqlDirectiveOptions = {},
       url: introspectionUrl,
       schemaFile,
       introspectionFile,
@@ -35,10 +39,22 @@ export function buildSchemas(opts) {
 
   let done = false
   let introspectionResponse
-
   if (schemaFile) {
-    const schema = loadSchemaFromSDLFile({ pathToFile: schemaFile })
+    const { schema, directables, directiveName } = loadSchemaFromSDLFile({
+      pathToFile: schemaFile,
+      spectaqlDirectiveOptions,
+    })
     introspectionResponse = introspectionResponseFromSchema({ schema })
+
+    if (spectaqlDirectiveOptions.enable) {
+      introspectionResponse = addMetadataFromDirectables({
+        ...introspectionOptions,
+        directables,
+        directiveName,
+        introspectionQueryResponse: introspectionResponse,
+      })
+    }
+
     done = 'loaded GraphQL SDL from file'
   }