added generation of command documentation (#15)

Generates in the GitHub summary a list of all the available commands
with some information on their usage and (soon to be added) parameters.

Resolves #12

src/commander.ts

@@ -1,4 +1,6 @@
+import { summary } from "@actions/core";
 import { readFile } from "fs/promises";
+import { dirname } from "path";
 import { parse } from "yaml";
 
 import { ActionLogger } from "./github/types";
@@ -24,6 +26,7 @@ export class Commander {
     for (const file of files) {
       const content = await readFile(file, "utf-8");
       const command = parse(content) as Command;
+      command.location = dirname(file);
       this.logger.info(`Parsing ${file}`);
       validateConfig(command);
       commands.push(command);
@@ -32,4 +35,39 @@ export class Commander {
     this.commands = commands;
     return commands;
   }
+
+  async documentCommands(): Promise<typeof summary> {
+    this.logger.info("Generating documentation");
+    const commands = await this.getCommands();
+    let text = summary
+      .addHeading("Commands")
+      .addRaw(`There are ${commands.length} available commands`)
+      .addEOL();
+    for (const command of commands) {
+      text = text.addHeading(command.name, 2);
+      if (command.description) {
+        text = text.addRaw(command.description).addEOL();
+      }
+      text = text
+        .addEOL()
+        .addDetails("File location", `<code>${command.location}</code>`)
+        .addEOL();
+      if (command.machine) {
+        text = text.addHeading("Runs on").addList(command.machine);
+      }
+      if (command.timeout) {
+        text = text
+          .addHeading("Timeout", 4)
+          .addRaw(`${command.timeout} seconds`)
+          .addEOL();
+      }
+
+      text = text
+        .addHeading("Command that runs", 4)
+        .addCodeBlock(command.commandStart, "shell")
+        .addEOL();
+    }
+
+    return text;
+  }
 }

src/index.ts

@@ -34,13 +34,14 @@ const commander = new Commander(scripts, logger);
 if (context.eventName.includes("pull_request")) {
   commander
     .getCommands()
-    .then((commands) =>
+    .then(async (commands) => {
       logger.info(
         `Found ${commands.length} valid commands: ${commands
           .map(({ name }) => name)
           .join(", ")}`,
-      ),
-    )
+      );
+      await (await commander.documentCommands()).write();
+    })
     .catch(setFailed);
 }
 

src/schema/command.ts

@@ -1,5 +1,6 @@
 export interface Command {
   name: string;
+  location: string;
   description?: string;
   machine?: string[];
   timeout?: number;

src/test/validator.test.ts

@@ -5,6 +5,7 @@ test("test good command", () => {
   const goodCommand: Command = {
     name: "Hi",
     timeout: 10,
+    location: "",
     commandStart: "./bin",
   };
   validateConfig(goodCommand);