@graphql-markdown/docusaurus 1.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Grégory Heitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+[![GraphQL-Markdown](https://user-images.githubusercontent.com/324670/188957463-dae99daa-763d-466e-91f4-0629f455df74.svg)](https://graphql-markdown.github.io)
+
+<h1 align="center">GraphQL documentation generator for Docusaurus</h1>
+
+[![Latest Version](https://img.shields.io/npm/v/@graphql-markdown/docusaurus?style=flat-square)](https://www.npmjs.com/package/@graphql-markdown/docusaurus)
+[![GitHub License](https://img.shields.io/github/license/graphql-markdown/graphql-markdown?style=flat-square)](https://raw.githubusercontent.com/graphql-markdown/graphql-markdown/main/LICENSE)
+[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/graphql-markdown/graphql-markdown)
+[![Coverage Status](https://img.shields.io/coveralls/github/graphql-markdown/graphql-markdown?style=flat-square)](https://coveralls.io/github/graphql-markdown/graphql-markdown?branch=main)
+[![Mutation Score](https://img.shields.io/endpoint?label=mutation%20score&style=flat-square&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fgraphql-markdown%2Fgraphql-markdown%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/graphql-markdown/graphql-markdown/main)
+[![Sonar Tech Debt](https://img.shields.io/sonar/tech_debt/graphql-markdown_graphql-markdown/main?server=https%3A%2F%2Fsonarcloud.io&style=flat-square)](https://sonarcloud.io/project/overview?id=graphql-markdown_graphql-markdown)
+[![Snyk Package Health](https://snyk.io/advisor/npm-package/@graphql-markdown/docusaurus/badge.svg)](https://snyk.io/advisor/npm-package/@graphql-markdown/docusaurus)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+
+This plugin generates **Markdown pages** from a **GraphQL schema** for **Docusaurus** [docs feature](https://docusaurus.io/docs/docs-introduction).
+
+## Installation
+
+**`graphql` package is a peer-dependency, and it should be installed separately.**
+
+```shell
+npm install @graphql-markdown/docusaurus graphql
+```
+
+Add `@graphql-markdown/docusaurus` to your site's `docusaurus.config.js` plugins option:
+
+```js
+module.exports = {
+  // ...
+  plugins: ["@graphql-markdown/docusaurus"],
+};
+```
+
+## Usage
+
+The plugin adds a new command `graphql-to-doc` to the [Docusaurus CLI](https://docusaurus.io/docs/cli).
+
+```shell
+npx docusaurus graphql-to-doc
+```
+
+Command line options are described in the [documentation settings](https://graphql-markdown.github.io/docs/settings) page.
+
+## Configuration
+
+See [documentation settings](https://graphql-markdown.github.io/docs/settings) page.
+
+## Troubleshooting
+
+See [documentation troubleshooting](https://graphql-markdown.github.io/docs/troubleshooting) page.
+
+## License
+
+GraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).
+
+This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
+
+## Contributions
+
+[Contributions](https://github.com/graphql-markdown/graphql-markdown/blob/main/CONTRIBUTING.md), issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!
+
+<a href="https://github.com/graphql-markdown/graphql-markdown/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=graphql-markdown/graphql-markdown" />
+</a>
+
+Made with [contributors-img](https://contrib.rocks).

package/assets/generated.md

@@ -0,0 +1,19 @@
+---
+id: schema
+slug: ##baseURL##
+title: Schema Documentation
+sidebar_position: 1
+hide_table_of_contents: true
+pagination_next: null
+pagination_prev: null
+sidebar_class_name: navbar__toggle
+---
+
+This documentation has been automatically generated from the GraphQL schema.
+
+Use the docs in the sidebar to find out how to use the schema:
+
+- **Allowed operations**: queries and mutations.
+- **Schema-defined types**: scalars, objects, enums, interfaces, unions, and input objects.
+
+<small><i>Generated on ##generated-date-time##.</i></small>

package/assets/sidebar.json

@@ -0,0 +1,8 @@
+{
+  "schemaSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "schema"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,185 @@
+{
+  "name": "@graphql-markdown/docusaurus",
+  "homepage": "https://graphql-markdown.github.io",
+  "description": "Docusaurus plugin for generating Markdown documentation from a GraphQL schema.",
+  "bugs": {
+    "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
+  },
+  "version": "1.14.0",
+  "license": "MIT",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/graphql-markdown/graphql-markdown.git"
+  },
+  "keywords": [
+    "docusaurus",
+    "graphql",
+    "graphql-schema",
+    "documentation",
+    "plugin",
+    "markdown",
+    "graphql-markdown"
+  ],
+  "author": {
+    "name": "Gregory Heitz"
+  },
+  "contributors": [
+    {
+      "name": "jocrau"
+    },
+    {
+      "name": "mimo84"
+    },
+    {
+      "name": "coder2034"
+    },
+    {
+      "name": "lauzierj"
+    },
+    {
+      "name": "jineshshah36"
+    },
+    {
+      "name": "GuiHash"
+    },
+    {
+      "name": "davidyaha"
+    },
+    {
+      "name": "jlndk"
+    },
+    {
+      "name": "elias-pap"
+    }
+  ],
+  "scripts": {
+    "prettier": "prettier \"{src,tests,assets}/**/*.{js,json,md}\"",
+    "lint": "eslint \"{src,tests,assets}/**/*.js\"",
+    "test": "jest",
+    "test:unit": "jest --projects tests/unit",
+    "test:integration": "jest --projects tests/integration",
+    "test:smoke": "earthly +smoke-test",
+    "test:coverage": "sh ./scripts/coverage.sh",
+    "test:mutation": "stryker run --reporters progress,html",
+    "prepare": "husky install",
+    "prepack": "pinst --disable",
+    "postpack": "pinst --enable",
+    "stryker": "stryker"
+  },
+  "dependencies": {
+    "@graphql-inspector/core": "^3.3.0",
+    "@graphql-tools/graphql-file-loader": "^7.5.2",
+    "@graphql-tools/load": "^7.7.4"
+  },
+  "peerDependencies": {
+    "graphql": "^14.0 || ^15.0 || ^16.0",
+    "prettier": "^2.5"
+  },
+  "peerDependenciesMeta": {
+    "prettier": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "6.2.2",
+    "@stryker-mutator/jest-runner": "6.2.2",
+    "commitizen": "4.2.5",
+    "cz-emoji": "1.3.1",
+    "diff": "5.1.0",
+    "directory-tree": "3.3.1",
+    "eslint": "8.24.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-jest": "27.1.0",
+    "eslint-plugin-node": "11.1.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "graphql": "16.6.0",
+    "husky": "8.0.1",
+    "jest": "29.1.2",
+    "jest-file-snapshot": "0.5.0",
+    "lodash.filter": "4.6.0",
+    "mock-fs": "5.1.4",
+    "pinst": "3.0.0",
+    "prettier": "2.7.1"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "engines": {
+    "node": ">=16.14"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-emoji"
+    },
+    "cz-emoji": {
+      "skipQuestions": [
+        "scope",
+        "issues",
+        "breaking"
+      ],
+      "types": [
+        {
+          "emoji": "✨",
+          "code": ":sparkles:",
+          "description": "Add a new feature.",
+          "name": "feat"
+        },
+        {
+          "emoji": "🐛",
+          "code": ":bug:",
+          "description": "Fix a bug.",
+          "name": "fix"
+        },
+        {
+          "emoji": "📦️",
+          "code": ":package:",
+          "description": "Update dependencies.",
+          "name": "build"
+        },
+        {
+          "emoji": "🔧",
+          "code": ":wrench:",
+          "description": "Update configuration files.",
+          "name": "conf"
+        },
+        {
+          "emoji": "♻️",
+          "code": ":recycle:",
+          "description": "Refactor code.",
+          "name": "refactor"
+        },
+        {
+          "emoji": "🧪",
+          "code": ":test_tube:",
+          "description": "Update tests.",
+          "name": "test"
+        },
+        {
+          "emoji": "👷",
+          "code": ":construction_worker:",
+          "description": "Update CI.",
+          "name": "ci"
+        },
+        {
+          "emoji": "📝",
+          "code": ":memo:",
+          "description": "Update documentation.",
+          "name": "docs"
+        },
+        {
+          "emoji": "🔖",
+          "code": ":bookmark:",
+          "description": "Add a tag / release.",
+          "name": "tag"
+        },
+        {
+          "emoji": "🧑‍💻",
+          "code": ":technologist:",
+          "description": "Other changes.",
+          "name": "other"
+        }
+      ]
+    }
+  }
+}

package/src/config.js

@@ -0,0 +1,83 @@
+const { join } = require("path");
+const { tmpdir } = require("os");
+
+const { parseGroupByOption } = require("./lib/group-info");
+const { COMPARE_METHOD } = require("./lib/diff");
+
+const PACKAGE_NAME = "@graphql-markdown/docusaurus";
+const ASSETS_LOCATION = join(__dirname, "../assets/");
+
+const DEFAULT_OPTIONS = {
+  schema: "./schema.graphql",
+  rootPath: "./docs",
+  baseURL: "schema",
+  linkRoot: "/",
+  homepage: join(ASSETS_LOCATION, "generated.md"),
+  diffMethod: COMPARE_METHOD.DIFF,
+  tmpDir: join(tmpdir(), PACKAGE_NAME),
+  loaders: {},
+  pretty: false,
+  docOptions: {
+    pagination: true,
+    toc: true,
+    index: false,
+  },
+  printTypeOptions: {
+    parentTypePrefix: true,
+    relatedTypeSection: true,
+    typeBadges: true,
+  },
+};
+
+function buildConfig(configFileOpts, cliOpts) {
+  let config = DEFAULT_OPTIONS;
+
+  if (typeof configFileOpts != "undefined" && configFileOpts != null) {
+    config = { ...DEFAULT_OPTIONS, ...configFileOpts };
+  }
+
+  if (typeof cliOpts == "undefined" || cliOpts == null) {
+    cliOpts = {};
+  }
+
+  const baseURL = cliOpts.base ?? config.baseURL;
+
+  return {
+    baseURL,
+    schemaLocation: cliOpts.schema ?? config.schema,
+    outputDir: join(cliOpts.root ?? config.rootPath, baseURL),
+    linkRoot: cliOpts.link ?? config.linkRoot,
+    homepageLocation: cliOpts.homepage ?? config.homepage,
+    diffMethod: getDiffMethod(cliOpts.diff ?? config.diffMethod, cliOpts.force),
+    tmpDir: cliOpts.tmp ?? config.tmpDir,
+    loaders: config.loaders,
+    groupByDirective:
+      parseGroupByOption(cliOpts.groupByDirective) || config.groupByDirective,
+    prettify: cliOpts.pretty ?? config.pretty,
+    docOptions: getDocOptions(cliOpts, config.docOptions),
+    printTypeOptions: gePrintTypeOptions(cliOpts, config.printTypeOptions),
+  };
+}
+
+function getDiffMethod(diff, force) {
+  return force ? COMPARE_METHOD.FORCE : diff;
+}
+
+function getDocOptions(cliOpts, configOptions) {
+  return {
+    pagination: !cliOpts.noPagination && configOptions.pagination,
+    toc: !cliOpts.noToc && configOptions.toc,
+    index: cliOpts.index || configOptions.index,
+  };
+}
+
+function gePrintTypeOptions(cliOpts, configOptions) {
+  return {
+    parentTypePrefix: !cliOpts.noParentType && configOptions.parentTypePrefix,
+    relatedTypeSection:
+      !cliOpts.noRelatedType && configOptions.relatedTypeSection,
+    typeBadges: !cliOpts.noTypeBadges && configOptions.typeBadges,
+  };
+}
+
+module.exports = { buildConfig, DEFAULT_OPTIONS, ASSETS_LOCATION };

package/src/const/mdx.js

@@ -0,0 +1,7 @@
+module.exports = `
+export const Bullet = () => <><span style={{ fontWeight: 'normal', fontSize: '.5em', color: 'var(--ifm-color-secondary-darkest)' }}>&nbsp;●&nbsp;</span></>
+
+export const SpecifiedBy = (props) => <>Specification<a className="link" style={{ fontSize:'1.5em', paddingLeft:'4px' }} target="_blank" href={props.url} title={'Specified by ' + props.url}>⎘</a></>
+
+export const Badge = (props) => <><span class={'badge badge--' + props.class}>{props.text}</span></>
+`;

package/src/const/strings.js

@@ -0,0 +1,30 @@
+const ROOT_TYPE_LOCALE = {
+  QUERY: { singular: "query", plural: "queries" },
+  MUTATION: { singular: "mutation", plural: "mutations" },
+  SUBSCRIPTION: { singular: "subscription", plural: "subscriptions" },
+  TYPE: { singular: "object", plural: "objects" },
+  INTERFACE: { singular: "interface", plural: "interfaces" },
+  DIRECTIVE: { singular: "directive", plural: "directives" },
+  SCALAR: { singular: "scalar", plural: "scalars" },
+  ENUM: { singular: "enum", plural: "enums" },
+  OPERATION: { singular: "operation", plural: "operations" },
+  UNION: { singular: "union", plural: "unions" },
+  INPUT: { singular: "input", plural: "inputs" },
+};
+
+const HEADER_SECTION_LEVEL = "###";
+const HEADER_SECTION_SUB_LEVEL = "####";
+const HEADER_SECTION_ITEM_LEVEL = "#####";
+const NO_DESCRIPTION_TEXT = "No description";
+const MARKDOWN_EOL = "\n";
+const MARKDOWN_EOP = "\n\n";
+
+module.exports = {
+  ROOT_TYPE_LOCALE,
+  HEADER_SECTION_LEVEL,
+  HEADER_SECTION_SUB_LEVEL,
+  HEADER_SECTION_ITEM_LEVEL,
+  NO_DESCRIPTION_TEXT,
+  MARKDOWN_EOL,
+  MARKDOWN_EOP,
+};

package/src/index.js

@@ -0,0 +1,51 @@
+/* istanbul ignore file */
+const { buildConfig } = require("./config.js");
+const generateDocFromSchema = require("./lib/generator");
+
+const NAME = "docusaurus-graphql-doc-generator";
+const COMMAND = "graphql-to-doc";
+const DESCRIPTION = "Generate GraphQL Schema Documentation";
+const DEFAULT_ID = "default";
+
+module.exports = function pluginGraphQLDocGenerator(_, configOptions) {
+  const isDefaultId = configOptions.id === DEFAULT_ID;
+
+  const command = isDefaultId ? COMMAND : `${COMMAND}:${configOptions.id}`;
+  const description = isDefaultId
+    ? DESCRIPTION
+    : `${DESCRIPTION} for configuration with id ${configOptions.id}`;
+
+  return {
+    name: NAME,
+    extendCli(cli) {
+      cli
+        .command(command)
+        .description(description)
+        .option("-s, --schema <schema>", "Schema location")
+        .option("-r, --root <rootPath>", "Root folder for doc generation")
+        .option("-b, --base <baseURL>", "Base URL to be used by Docusaurus")
+        .option("-l, --link <linkRoot>", "Root for links in documentation")
+        .option(
+          "-h, --homepage <homepage>",
+          "File location for doc landing page",
+        )
+        .option("--noPagination", "Disable page navigation buttons")
+        .option("--noParentType", "Disable parent type name as field prefix")
+        .option("--noRelatedType", "Disable related types sections")
+        .option("--noToc", "Disable page table of content")
+        .option("--noTypeBadges", "Disable badges for types")
+        .option("--index", "Enable generated index for categories")
+        .option("-f, --force", "Force document generation")
+        .option("-d, --diff <diffMethod>", "Set diff method")
+        .option("-t, --tmp <tmpDir>", "Set temp dir for schema diff")
+        .option(
+          "-gbd, --groupByDirective <@directive(field|=fallback)>",
+          "Group documentation by directive",
+        )
+        .option("--pretty", "Prettify generated files")
+        .action(async (cliOptions) => {
+          await generateDocFromSchema(buildConfig(configOptions, cliOptions));
+        });
+    },
+  };
+};

package/src/lib/diff.js

@@ -0,0 +1,79 @@
+const path = require("path");
+const crypto = require("crypto");
+
+const { fileExists, readFile, saveFile } = require("../utils/helpers/fs");
+
+const { loadSchema, getDocumentLoaders, printSchema } = require("./graphql");
+const { diff } = require("@graphql-inspector/core");
+
+const SCHEMA_HASH_FILE = ".schema";
+const SCHEMA_REF = "schema.graphql";
+const COMPARE_METHOD = {
+  DIFF: "SCHEMA-DIFF",
+  HASH: "SCHEMA-HASH",
+  FORCE: "FORCE",
+};
+
+const defaultLoaders = {
+  GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
+};
+
+function getSchemaHash(schema) {
+  let printedSchema = printSchema(schema, { commentDescriptions: true });
+  let sum = crypto.createHash("sha256").update(printedSchema);
+  return sum.digest("hex");
+}
+
+async function getDiff(schemaNew, schemaOld) {
+  const schemaRef = await loadSchema(schemaOld, {
+    loaders: getDocumentLoaders(defaultLoaders).loaders,
+  });
+  return diff(schemaRef, schemaNew);
+}
+
+async function checkSchemaChanges(
+  schema,
+  outputDir,
+  method = COMPARE_METHOD.DIFF,
+) {
+  const hashFile = path.join(outputDir, SCHEMA_HASH_FILE);
+  const hashSchema = getSchemaHash(schema);
+  const schemaRef = path.join(outputDir, SCHEMA_REF);
+
+  if (method === COMPARE_METHOD.DIFF) {
+    if (await fileExists(schemaRef)) {
+      const schemaDiff = await getDiff(schema, schemaRef);
+      return schemaDiff.length > 0;
+    }
+  }
+
+  if (method === COMPARE_METHOD.HASH) {
+    if (await fileExists(hashFile)) {
+      const hash = await readFile(hashFile);
+      return hashSchema != hash;
+    }
+  }
+
+  return true;
+}
+
+async function saveSchemaFile(schema, outputDir) {
+  const schemaFile = path.join(outputDir, SCHEMA_REF);
+  const schemaPrint = printSchema(schema);
+  await saveFile(schemaFile, schemaPrint);
+}
+
+async function saveSchemaHash(schema, outputDir) {
+  const hashFile = path.join(outputDir, SCHEMA_HASH_FILE);
+  const hashSchema = getSchemaHash(schema);
+  await saveFile(hashFile, hashSchema);
+}
+
+module.exports = {
+  checkSchemaChanges,
+  saveSchemaHash,
+  saveSchemaFile,
+  COMPARE_METHOD,
+  SCHEMA_HASH_FILE,
+  SCHEMA_REF,
+};

package/src/lib/generator.js

@@ -0,0 +1,78 @@
+const { getSchemaMap, loadSchema, getDocumentLoaders } = require("./graphql");
+const { getGroups } = require("./group-info");
+const Renderer = require("./renderer");
+const Printer = require("./printer");
+const {
+  checkSchemaChanges,
+  saveSchemaHash,
+  saveSchemaFile,
+} = require("./diff");
+
+const time = process.hrtime();
+
+module.exports = async function generateDocFromSchema({
+  baseURL,
+  schemaLocation,
+  outputDir,
+  linkRoot,
+  homepageLocation,
+  diffMethod,
+  tmpDir,
+  loaders,
+  groupByDirective,
+  prettify,
+  docOptions,
+  printTypeOptions,
+}) {
+  const { loaders: documentLoaders, loaderOptions } =
+    getDocumentLoaders(loaders);
+  const schema = await loadSchema(schemaLocation, {
+    loaders: documentLoaders,
+    ...loaderOptions,
+  });
+
+  const hasChanged = await checkSchemaChanges(schema, tmpDir, diffMethod);
+
+  if (hasChanged) {
+    const rootTypes = getSchemaMap(schema);
+    const groups = new getGroups(rootTypes, groupByDirective);
+    const renderer = new Renderer(
+      new Printer(schema, baseURL, linkRoot, {
+        groups,
+        printTypeOptions,
+      }),
+      outputDir,
+      baseURL,
+      groups,
+      prettify,
+      docOptions,
+    );
+    const pages = await Promise.all(
+      Object.keys(rootTypes).map((typeName) =>
+        renderer.renderRootTypes(typeName, rootTypes[typeName]),
+      ),
+    );
+    await renderer.renderHomepage(homepageLocation);
+    const sidebarPath = await renderer.renderSidebar();
+
+    const [sec, msec] = process.hrtime(time);
+    const duration = (sec + msec / 1e9).toFixed(3);
+    console.info(
+      `Documentation successfully generated in "${outputDir}" with base URL "${baseURL}".`,
+    );
+    console.log(
+      `${
+        pages.flat().length
+      } pages generated in ${duration}s from schema "${schemaLocation}".`,
+    );
+    console.info(
+      `Remember to update your Docusaurus site's sidebars with "${sidebarPath}".`,
+    );
+
+    // create references for checkSchemaChanges
+    await saveSchemaHash(schema, tmpDir);
+    await saveSchemaFile(schema, tmpDir);
+  } else {
+    console.info(`No changes detected in schema "${schemaLocation}".`);
+  }
+};