Merge pull request #55 from InnerSourceCommons/add-gqm-gen

feat: add gqm_gen script

Author: jeffabailey

measuring/questions/who-uses.md

@@ -1,6 +1,6 @@
 [⬑ back to the overall graph](../use_gqm.md)
 
-# Question: Who uses the InnerSource project?
+# **Question:** Who uses the InnerSource project?
 
 Depending on the InnerSource project, usage of the project could look something like:
 

package-lock.json

@@ -0,0 +1,47 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# TypeScript
+*.map
+*.js
+
+# Project generated files
+*.pdf
+*.xlsx
+slides/*.md

scripts/gqm_gen/.gitignore

@@ -0,0 +1,12 @@
+# Goal, Question, Metrics Generator
+
+Creates a Mermaid diagram from Goal, Question, Metrics (GQM) Markdown files.
+
+## Usage
+
+Builds the mermaid diagram and outputs it to stdout.
+
+```bash
+npm install
+npm run --silent start
+```

scripts/gqm_gen/README.md

@@ -0,0 +1,5 @@
+import * as Commonmark from 'commonmark';
+export declare function getLinks(parsed: Commonmark.Node): {
+    url: string | null;
+    text: string | null | undefined;
+}[];

scripts/gqm_gen/index.d.ts

@@ -0,0 +1,41 @@
+import * as Commonmark from "commonmark";
+import test from "node:test";
+import assert from "node:assert";
+import { FileLink, Graph, LinkType } from "./types";
+import {
+  getLinks,
+  getFileLinks,
+  generateMermaidDiagram,
+  getGQMFileLinks,
+} from "./index";
+
+test("can get links", () => {
+  const node = new Commonmark.Node("paragraph");
+  const links = getLinks(node);
+  assert(links.length === 0);
+});
+
+test("can get links from file", () => {
+  const fileLinks: FileLink[] = getFileLinks(
+    LinkType.GOAL,
+    "../../measuring/goals/"
+  );
+  assert(fileLinks.length > 0);
+});
+
+test("can generate mermaid diagram", () => {
+  const graph: Graph = {
+    nodes: [],
+    edges: [],
+  };
+  const diagram = generateMermaidDiagram(graph);
+  assert(diagram.indexOf("graph TB") > 1);
+});
+
+test("can generate mermaid diagram from file", { only: true }, () => {
+  const graph = getGQMFileLinks();
+
+  const diagram = generateMermaidDiagram(graph);
+  console.log(diagram);
+  assert(diagram.indexOf("graph LR;") > 1);
+});

scripts/gqm_gen/index.test.ts

@@ -0,0 +1,189 @@
+import * as Commonmark from "commonmark";
+import * as fs from "fs";
+import * as path from "path";
+import { Node, Edge, Graph, Link, LinkType, NodeShape, ArrowType } from "./types";
+import { FileLink } from "./types";
+
+const graph = getGQMFileLinks();
+
+export function getLinkUrl(linkType: LinkType, file: string) {
+  const measuringUrl = "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/";
+  const url = `${measuringUrl}/${linkType.toLowerCase()}s/${file}`
+  return url;
+}
+
+export function getGQMFileLinks() {
+  const graph: Graph = {
+    nodes: [],
+    edges: [],
+  };
+
+  const goalsPath = "../../measuring/goals/";
+  const questionsPath = "../../measuring/questions/";
+  const metricsPath = "../../measuring/metrics/";
+  
+  const goalFileLinks: FileLink[] = getFileLinks(LinkType.GOAL, goalsPath);
+  appendToGraph(graph, goalFileLinks);
+
+  const questionFileLinks: FileLink[] = getFileLinks(
+    LinkType.QUESTION,
+    questionsPath
+  );
+  appendToGraph(graph, questionFileLinks);
+
+  const metricFileLinks: FileLink[] = getFileLinks(LinkType.METRIC, metricsPath);
+  appendToGraph(graph, metricFileLinks);
+
+  return graph;
+}
+
+export function appendToGraph(graph: Graph, fileLinks: FileLink[]) {
+  fileLinks.forEach((fileLink) => {
+    const node: Node = {
+      id: fileLink.file,
+      type: fileLink.linkType,
+      shape: NodeShape.RECT,
+      label: fileLink.label,
+    };
+    if (node.label) {
+      graph.nodes.push(node);
+    }
+
+    fileLink.links.forEach((link) => {
+      const edge: Edge = {
+        from: fileLink.file,
+        to: link.name,
+        arrowType: "arrow",
+      };
+      if(edge.from && edge.to){
+        graph.edges.push(edge);
+      }
+    });
+  });
+  return graph
+}
+
+export function getFileLinks(linkType: LinkType, filePath: string) {
+  const parser = new Commonmark.Parser();
+
+  const goalFiles = fs.readdirSync(filePath);
+  let fileLinks: FileLink[] = [];
+  goalFiles.forEach((fileName) => {
+    if (fileName.endsWith("template.md")) return;
+    const data = fs.readFileSync(`${filePath}/${fileName}`, "utf-8");
+    const parsed = parser.parse(data);
+    const label = getHeading(parsed);
+    const links = getLinks(parsed);
+
+    const fileLink: FileLink = {
+      linkType: linkType,
+      file: fileName,
+      label: label,
+      links,
+    };
+    fileLinks.push(fileLink);
+  });
+  return fileLinks;
+}
+
+export function getHeading(parsed: Commonmark.Node) {
+  const walker = parsed.walker();
+  let event, node;
+  let heading: string = "No Heading";
+  while ((event = walker.next())) {
+    node = event.node;
+    if (event.entering && node.type === "heading") {
+      heading = node.lastChild?.literal as string;
+      break;
+    }
+  }
+  return heading.trim();
+}
+
+export function getLinks(parsed: Commonmark.Node) {
+  const walker = parsed.walker();
+  let event, node;
+  const links: Link[] = [];
+  while ((event = walker.next())) {
+    node = event.node;
+    if (event.entering && node.type === "link") {
+      const destination = node.destination as string;
+      const text = node.firstChild?.literal as string;
+      const link: Link = {
+        url: destination,
+        text: text,
+        name: path.parse(destination).base,
+      };
+
+      if (link.url.indexOf('.md') > -1 && link.url.indexOf('use_gqm') === -1) {
+        links.push(link);
+      }
+    }
+  }
+  return links;
+}
+
+export function getNodeShapeSyntax(node: Node) {
+  const nodeUrl = getLinkUrl(node.type, node.id)
+  const nodeLabel = `<a href='${nodeUrl}'>${node.label}</a>`;
+  switch (node.shape) {
+    case 'rect':
+      return `[${nodeLabel}]`;
+    case 'circ':
+      return `((${nodeLabel}))`;
+    case 'roundrect':
+      return `((${nodeLabel}))`;
+    case 'diamond':
+      return `{${nodeLabel}}`;
+    default:
+      return `[${nodeLabel}]`;
+  }
+}
+
+export function generateMermaidDiagram(graph: Graph) {
+  const nodes = graph.nodes;
+  const edges = graph.edges;
+
+  let mermaidSyntax = `\`\`\`mermaid\n
+  graph LR;\n
+    subgraph GQM[Goals, Questions, Metrics]\n
+  `;
+  
+  nodes.forEach((node) => {
+    const nodeSyntax = getNodeShapeSyntax(node)
+    mermaidSyntax += `    ${node.id}${nodeSyntax}\n`
+  });
+
+  edges.forEach((edge) => {
+    const arrowSyntax: string = ArrowType.ARROW;
+    mermaidSyntax += `${edge.from}${arrowSyntax}${edge.to}\n`;
+  });
+
+  const goalsList = nodes.filter(n => n.type == LinkType.GOAL).map(n => `${n.id}`).join(',');
+  const questionsList = nodes.filter(n => n.type == LinkType.QUESTION).map(n => `${n.id}`).join(',');
+  const metricsList = nodes.filter(n => n.type == LinkType.METRIC).map(n => `${n.id}`).join(',');
+  
+  mermaidSyntax += "  end";
+  mermaidSyntax += `
+      subgraph Legend
+        direction TB
+
+        goal[Goal]
+        question[Question]
+        metric[Metric]
+
+        classDef goals stroke:green,stroke-width:2px;
+        class goal,${goalsList} goals
+
+        classDef questions stroke:orange,stroke-width:2px;
+        class question,${questionsList} questions
+
+        classDef metrics stroke:purple,stroke-width:2px;
+        class metric,${metricsList} metrics
+      end  
+  `;
+  mermaidSyntax += "\n```";
+  return mermaidSyntax;
+}
+
+console.log(generateMermaidDiagram(graph))