@factorialco/gat 0.0.19 → 1.0.0

package/README.md

@@ -1,3 +1,92 @@
-# GitHub Actions Template Generator (aka GAT)
+# gat ![Build](https://github.com/factorialco/gat/actions/workflows/build.yml/badge.svg?branch=main) [![npm version](https://badge.fury.io/js/@factorialco%2Fgat.svg)](https://badge.fury.io/js/@factorialco%2Fgat)
+
+The `gat` project is a tool to **write your GitHub Actions workflows using TypeScript**.
+
+Maintaining YAML files is hard and if your project is big enough you will find yourself duplicating a lot of code between your workflows. With `gat` you can create reusable jobs and steps just using TypeScript objects and importing them in your workflow templates.
+
+_Why `gat`?_ The name is an acronym of "GitHub Actions Template Generator" without the last part because `gat` means "cat" in Catalan.
+
+## Installation
+
+Install the main package and its dependencies using the following command:
+
+```bash
+npm i -D @factorialco/gat typescript ts-node commander
+```
+
+## Usage
+
+### Writing a template
+
+The `gat` CLI assumes that your templates are inside `.github/templates`. Let's create our first template:
+
+```ts
+// .github/templates/my-first-workflow.ts
+import { Workflow } from "@factorialco/gat";
+
+new Workflow("My first workflow")
+  .on("push")
+  .addJob("test", {
+    steps: [
+      {
+        uses: "actions/checkout@v3",
+      },
+      {
+        uses: "actions/setup-node@v3",
+      },
+      {
+        run: "npm test",
+      },
+    ],
+  })
+  .compile();
+```
+
+Notice that you need to call the `compile()` method at the end.
+
+### Compiling your templates
+
+You can build your templates running this command in your root folder:
+
+```bash
+npx gat build
+```
+
+Alternatively you can also compile a single template:
+
+```bash
+npx gat build .github/templates/some-workflow.ts
+```
+
+Following the previous example, you should see now a file `.github/workflows/my-first-workflow.yml` like this:
+
+```yaml
+# Workflow automatically generated by gat
+# DO NOT CHANGE THIS FILE MANUALLY
+
+name: My first workflow
+on:
+  push: null
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm test
+```
+
+Notice that the job includes a few assumptions like the `runs-on` and `timeout-minutes` fields. You can change those when adding a new job.
+
+### Create your own workflow class
+
+TODO
+
+## Contributing
+
+TODO
+
+## License
 
 TODO

package/dist/cli.js

@@ -9,20 +9,22 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const commander_1 = require("commander");
 const util_1 = require("util");
+const debounce_1 = __importDefault(require("lodash/debounce"));
 const execPromise = (0, util_1.promisify)(child_process_1.exec);
 const writeFilePromise = (0, util_1.promisify)(fs_1.default.writeFile);
+const folder = path_1.default.join(process.cwd(), ".github", "templates");
 const parseFile = async (templateFile) => {
+    // NOTE: can we improve this using ts-node or typescript programatically?
     const { stdout } = await execPromise(`npx ts-node ${templateFile}`);
     await writeFilePromise(path_1.default.join(process.cwd(), ".github", "workflows", templateFile.split("/").at(-1).replace(".ts", ".yml")), stdout);
 };
 const cli = new commander_1.Command();
-cli.version("0.0.1").description("TODO");
+cli.version("1.0.0").description("Write your GitHub Actions workflows using TypeScript");
 cli
     .command("build")
-    .description("TODO")
-    .argument("[file]", "TODO")
+    .description("Transpile all Gat templates into GitHub Actions workflows.")
+    .argument("[file]", "(Optional) A Gat template file")
     .action(async (file) => {
-    const folder = path_1.default.join(process.cwd(), ".github", "templates");
     if (!fs_1.default.existsSync(path_1.default.join(folder, "..", "workflows"))) {
         fs_1.default.mkdirSync(path_1.default.join(folder, "..", "workflows"));
     }
@@ -38,4 +40,19 @@ cli
     }
     process.exit(0);
 });
+cli
+    .command("watch")
+    .description("Watch file changes in your Gat templates folder and transpile them automatically.")
+    .action(async () => {
+    const parseWatchedFile = (0, debounce_1.default)(async (fileName) => {
+        const start = process.hrtime.bigint();
+        process.stdout.write(`😸 Detected change on file ${fileName}. Transpiling... `);
+        await parseFile(path_1.default.join(folder, fileName.toString()));
+        console.log(`Done in ${((Number(process.hrtime.bigint() - start)) / 1000000).toFixed(2)}ms`);
+    }, 1000);
+    console.log(`😼 Watching file changes on ${folder}...`);
+    fs_1.default.watch(folder).on("change", (_eventName, fileName) => {
+        parseWatchedFile(fileName);
+    });
+});
 cli.parse(process.argv);

package/dist/workflow.d.ts

@@ -1,4 +1,4 @@
-import { Job, JobOptions } from "./job";
+import { ConcurrencyGroup, Job, JobOptions } from "./job";
 import type { Event, EventName, EventOptions } from "./event";
 import { BaseStep, Step } from "./step";
 declare const DEFAULT_RUNNERS: string[];
@@ -15,11 +15,13 @@ export declare class Workflow<JobStep extends BaseStep = Step, Runner = typeof D
     jobs: Array<Job<JobStep, Runner, JobName>>;
     defaultOptions: DefaultOptions | null;
     env: EnvVar[];
+    concurrencyGroup?: ConcurrencyGroup;
     constructor(name: string);
     on<T extends EventName>(name: T, options?: EventOptions<T>): this;
     addDefaults(options: DefaultOptions): this;
     addJob<T extends string>(name: T, options: JobOptions<JobStep, Runner, JobName>): Workflow<JobStep, Runner, JobName | T>;
     setEnv(name: string, value: string): this;
+    setConcurrencyGroup(concurrencyGroup: ConcurrencyGroup): this;
     defaultRunner(): string;
     private assignRunner;
     compile(): string;

package/dist/workflow.js

@@ -31,6 +31,10 @@ class Workflow {
         this.env = [...this.env, { name, value }];
         return this;
     }
+    setConcurrencyGroup(concurrencyGroup) {
+        this.concurrencyGroup = concurrencyGroup;
+        return this;
+    }
     defaultRunner() {
         return "ubuntu-22.04";
     }
@@ -43,6 +47,12 @@ class Workflow {
         const result = {
             name: this.name,
             on: Object.fromEntries(this.events.map(({ name, options }) => [name, options ? options : null])),
+            concurrency: this.concurrencyGroup
+                ? {
+                    group: this.concurrencyGroup.groupSuffix,
+                    "cancel-in-progress": this.concurrencyGroup.cancelPrevious,
+                }
+                : undefined,
             defaults: this.defaultOptions
                 ? {
                     run: {

package/dist/workflow.spec.js

@@ -226,4 +226,21 @@ exit 0`,
         });
         (0, vitest_1.expect)(workflow.compile()).toMatchSnapshot();
     });
+    (0, vitest_1.it)("allows concurrency groups at workflow level", () => {
+        const workflow = new workflow_1.Workflow("Concurrency at workflow level")
+            .on("push")
+            .setConcurrencyGroup({
+            groupSuffix: "${{ github.workflow }}-${{ github.ref }}",
+            cancelPrevious: true,
+        })
+            .addJob("job1", {
+            steps: [
+                {
+                    name: "Do something",
+                    run: "exit 0",
+                },
+            ],
+        });
+        (0, vitest_1.expect)(workflow.compile()).toMatchSnapshot();
+    });
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@factorialco/gat",
-  "version": "0.0.19",
-  "description": "TODO",
+  "version": "1.0.0",
+  "description": "Write your GitHub Actions workflows using TypeScript",
   "bin": {
     "gat": "dist/cli.js"
   },