feat: add core tools

src/routes.ts

@@ -0,0 +1,181 @@
+/*
+ * Copyright (C) 2018 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {asyncPool} from 'async-pool-native/dist/async-pool';
+import humanizeString = require('humanize-string');
+import {ProjectReflection} from 'typedoc';
+import {logger, NodesWithMetaInformation, NodeWithMetaInformation} from './common';
+import {RouteWithMetaInformation} from './common';
+
+/**
+ * Gather relevant information of routes
+ *
+ * This gathers the information for all routes that implement the abstract class SCAbstractRoute.
+ * Furthermore it instantiates every route and adds it to the information.
+ *
+ * @param reflection Contents of the JSON representation which Typedoc generates
+ */
+export async function gatherRouteInformation(reflection: ProjectReflection): Promise<RouteWithMetaInformation[]> {
+  const routes: RouteWithMetaInformation[] = [];
+
+  await asyncPool(2, reflection.children, async (module: any) => {
+    if (Array.isArray(module.children) && module.children.length > 0) {
+      await asyncPool(2, module.children, (async (node: any) => {
+        if (Array.isArray(node.extendedTypes) && node.extendedTypes.length > 0) {
+          if (node.extendedTypes.some((extendedType: any) => {
+            return extendedType.name === 'SCAbstractRoute';
+          })) {
+            logger.info(`Found ${node.name} in ${module.originalName}.`);
+
+            const importedModule = await import(module.originalName);
+
+            const route = new importedModule[node.name]();
+
+            routes.push({description: node.comment, name: node.name, route});
+          }
+        }
+      }));
+    }
+  });
+
+  return routes;
+}
+
+/**
+ * Get a linked name for a node
+ *
+ * @param name Name of the node
+ * @param node Node itself
+ * @param humanize Whether to humanize the name or not
+ */
+export function getLinkedNameForNode(name: string, node: NodeWithMetaInformation, humanize: boolean = false): string {
+  let printableName = name;
+
+  if (humanize) {
+    printableName = humanizeString(name.substr(2));
+  }
+
+  let link = `[${printableName}]`;
+  link += `(${getLinkForNode(name, node)})`;
+  return link;
+}
+
+/**
+ * Get link for a node
+ *
+ * @param name Name of the node
+ * @param node Node itself
+ */
+export function getLinkForNode(name: string, node: NodeWithMetaInformation): string {
+  let link = 'https://openstapps.gitlab.io/core/';
+  const module = node.module.toLowerCase().split('/').join('_');
+
+  if (node.type === 'Type alias') {
+    link += 'modules/';
+    link += `_${module}_`;
+    link += `.html#${name.toLowerCase()}`;
+    return link;
+  }
+
+  let type = 'classes';
+  if (node.type !== 'Class') {
+    type = `${node.type.toLowerCase()}s`;
+  }
+
+  link += `${type}/`;
+  link += `_${module}_`;
+  link += `.${name.toLowerCase()}.html`;
+  return link;
+}
+
+/**
+ * Generate documentation snippet for one route
+ *
+ * @param routeWithInfo A route instance with its meta information
+ * @param nodes
+ */
+export function generateDocumentationForRoute(routeWithInfo: RouteWithMetaInformation,
+                                              nodes: NodesWithMetaInformation): string {
+  let output = '';
+
+  const route = routeWithInfo.route;
+
+  output += `## \`${route.method} ${route.urlFragment}\``;
+  output += ` ${getLinkedNameForNode(routeWithInfo.name, nodes[routeWithInfo.name], true)}\n\n`;
+
+  if (typeof routeWithInfo.description.shortText === 'string') {
+    output += `**${routeWithInfo.description.shortText}**\n\n`;
+  }
+
+  if (typeof routeWithInfo.description.text === 'string') {
+    output += `${routeWithInfo.description.text.replace('\n', '<br>')}\n\n`;
+  }
+
+  output += `### Definition
+
+| parameter | value |
+| --- | --- |
+| request | ${getLinkedNameForNode(route.requestBodyName, nodes[route.requestBodyName])} |
+| response | ${getLinkedNameForNode(route.responseBodyName, nodes[route.responseBodyName])} |
+| success code | ${route.statusCodeSuccess} |
+| errors | ${route.errorNames.map((errorName) => {
+    return getLinkedNameForNode(errorName, nodes[errorName]);
+  }).join('<br>')} |
+`;
+  if (typeof route.obligatoryParameters === 'object' && Object.keys(route.obligatoryParameters).length > 0) {
+    let parameterTable = '<table><tr><th>parameter</th><th>type</th></tr>';
+
+    Object.keys(route.obligatoryParameters).forEach((parameter) => {
+      let type = route.obligatoryParameters![parameter];
+
+      if (typeof nodes[type] !== 'undefined') {
+        type = getLinkedNameForNode(type, nodes[type]);
+      }
+
+      parameterTable += `<tr><td>${parameter}</td><td>${type}</td></tr>`;
+    });
+
+    parameterTable += '</table>';
+
+    output += `| obligatory parameters | ${parameterTable} |`;
+  }
+  output += '\n\n';
+
+  return output;
+}
+
+/**
+ * Get a map of nodes with their meta information
+ *
+ * @param projectReflection Reflection to get information from
+ */
+export function getNodeMetaInformationMap(projectReflection: ProjectReflection): NodesWithMetaInformation {
+  const nodes: NodesWithMetaInformation = {};
+
+  // iterate over modules
+  projectReflection.children.forEach((module: any) => {
+    if (Array.isArray(module.children) && module.children.length > 0) {
+      // iterate over types
+      module.children.forEach((node: any) => {
+        // add node with module and type
+        nodes[node.name] = {
+          module: module.name.substring(1, module.name.length - 1),
+          type: node.kindString,
+        };
+      });
+    }
+  });
+
+  return nodes;
+}