feat: add automatic mermaid update scripts for GQMs

Author: GitHub Actions Bot

.github/workflows/gqm_update.yml

@@ -0,0 +1,32 @@
+name: Update GQM
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'measuring/goals/**'
+      - 'measuring/questions/**'
+      - 'measuring/metrics/**'
+
+  workflow_dispatch:
+jobs:
+    generateDiagram:
+      name: Generate Diagram
+      runs-on: ubuntu-latest
+      steps:    
+        - name: Checkout
+          uses: actions/checkout@v4
+        - name: Use Node.js
+          uses: actions/setup-node@v3
+          with:
+            node-version: '21.x'
+        - run: npm install --prefix ./scripts/gqm_gen
+        - run: npm run coverage-report --prefix ./scripts/gqm_gen
+        - name: Report NYC coverage
+          uses: sidx1024/report-nyc-coverage-github-action@v1.2.7
+          with:
+            coverage_file: ".nyc_output/nyc-coverage-report/coverage-summary.json"
+        - run: npm run --silent start --prefix ./scripts/gqm_gen > ./new_gqm.md.tmp
+        - run: sh ./scripts/gqm_gen/gqm_update.sh ./new_gqm.md.tmp ./measuring/use_gqm.md > ./measuring/use_gqm.md.tmp
+        - run: rm -f ./new_gqm.md.tmp
+        - run: mv -f ./measuring/use_gqm.md.tmp ./measuring/use_gqm.md
+        - run: sh ./scripts/gqm_gen/gqm_commit.sh

scripts/gqm_gen/gqm_commit.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+if cmp -s ./measuring/use_gqm.md.tmp ./measuring/use_gqm.md; then
+    echo "No changes in GQM diagram"
+    exit 0
+fi
+
+git --version
+git config user.name "GitHub Actions Bot"
+git config user.email "<>"
+git add ./measuring/use_gqm.md
+git commit -m "feat: gqm diagram updated by GitHub Actions" 
+git push

scripts/gqm_gen/gqm_update.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Check if the correct number of arguments are provided
+if [ "$#" -ne 2 ]; then
+    echo "Usage: $0 <path-to-new-mermaid-markdown-file> <path-to-exising-use_gqm-markdown-file>"
+    exit 1
+fi
+
+# File paths
+NEW_MERMAID_MARKDOWN_FILE="$1"
+EXISTING_USE_GQM_MARKDOWN_FILE="$2"
+
+# Check if the new content file exists
+if [ ! -f "$NEW_MERMAID_MARKDOWN_FILE" ]; then
+    echo "Error: New mermaid markdown file not found at $NEW_MERMAID_MARKDOWN_FILE"
+    exit 1
+fi
+
+# Check if the markdown file exists
+if [ ! -f "$EXISTING_USE_GQM_MARKDOWN_FILE" ]; then
+    echo "Error: Existing use_gqm markdown file not found at $EXISTING_USE_GQM_MARKDOWN_FILE"
+    exit 1
+fi
+
+# The pattern to match the mermaid block
+START_PATTERN='```mermaid'
+END_PATTERN='```'
+
+# Replace the entire mermaid block including the delimiters
+sed -e "/$START_PATTERN/,/$END_PATTERN/{
+    /$START_PATTERN/{
+        r $NEW_MERMAID_MARKDOWN_FILE
+        d
+    }
+    /$END_PATTERN/d
+    d
+}" "$EXISTING_USE_GQM_MARKDOWN_FILE"

scripts/gqm_gen/index.test.ts

@@ -1,12 +1,13 @@
 import * as Commonmark from "commonmark";
+import * as fs from "fs";
 import test from "node:test";
 import assert from "node:assert";
 import { FileLink, Graph, LinkType } from "./types";
 import {
   getLinks,
   getFileLinks,
   generateMermaidDiagram,
-  getGQMFileLinks,
+  getGQMFileLinks
 } from "./index";
 
 test("can get links", () => {
@@ -29,13 +30,11 @@ test("can generate mermaid diagram", () => {
     edges: [],
   };
   const diagram = generateMermaidDiagram(graph);
-  assert(diagram.indexOf("graph TB") > 1);
+  assert(diagram.indexOf("graph LR") > 1);
 });
 
-test("can generate mermaid diagram from file", { only: true }, () => {
-  const graph = getGQMFileLinks();
-
+test("can generate mermaid diagram from file", () => {
+  const graph = getGQMFileLinks('../../measuring/');
   const diagram = generateMermaidDiagram(graph);
-  console.log(diagram);
   assert(diagram.indexOf("graph LR;") > 1);
 });

scripts/gqm_gen/index.ts

@@ -4,23 +4,25 @@ import * as path from "path";
 import { Node, Edge, Graph, Link, LinkType, NodeShape, ArrowType } from "./types";
 import { FileLink } from "./types";
 
-const graph = getGQMFileLinks();
+const mdFilePath = process.env.npm_config_markDownFilePath || "../../measuring";
+
+const graph = getGQMFileLinks(mdFilePath);
 
 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() {
+export function getGQMFileLinks(mdFilePath: string) {
   const graph: Graph = {
     nodes: [],
     edges: [],
   };
 
-  const goalsPath = "../../measuring/goals/";
-  const questionsPath = "../../measuring/questions/";
-  const metricsPath = "../../measuring/metrics/";
+  const goalsPath = `${mdFilePath}/goals/`;
+  const questionsPath = `${mdFilePath}/questions/`;
+  const metricsPath = `${mdFilePath}/metrics/`;
 
   const goalFileLinks: FileLink[] = getFileLinks(LinkType.GOAL, goalsPath);
   appendToGraph(graph, goalFileLinks);
@@ -144,8 +146,7 @@ export function generateMermaidDiagram(graph: Graph) {
   const nodes = graph.nodes;
   const edges = graph.edges;
 
-  let mermaidSyntax = `\`\`\`mermaid\n
-  graph LR;\n
+  let mermaidSyntax = `\`\`\`mermaid\ngraph LR;\n
     subgraph GQM[Goals, Questions, Metrics]\n
   `;
 
@@ -156,7 +157,7 @@ export function generateMermaidDiagram(graph: Graph) {
 
   edges.forEach((edge) => {
     const arrowSyntax: string = ArrowType.ARROW;
-    mermaidSyntax += `${edge.from}${arrowSyntax}${edge.to}\n`;
+    mermaidSyntax += `    ${edge.from}${arrowSyntax}${edge.to}\n`;
   });
 
   const goalsList = nodes.filter(n => n.type == LinkType.GOAL).map(n => `${n.id}`).join(',');