Add first version of code, docs and tests

Author: gabmontes

.commitlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["bloq"]
+}

.eslintrc.json

@@ -0,0 +1,17 @@
+{
+  "extends": ["bloq", "bloq/node", "prettier"],
+  "overrides": [
+    {
+      "files": ["bin/*"],
+      "rules": {
+        "no-console": "off",
+        "no-process-exit": "off"
+      }
+    },
+    {
+      "extends": ["bloq/mocha", "prettier"],
+      "files": ["*.test.js"]
+    }
+  ],
+  "root": true
+}

.github/workflows/js-checks.yml

@@ -0,0 +1,15 @@
+name: JS Checks
+
+on:
+  pull_request:
+  push:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  run-checks-and-tests:
+    uses: bloq/actions/.github/workflows/js-checks.yml@v1
+    with:
+      node-versions: '["20","22","24"]'

.github/workflows/npm-publish.yml

@@ -0,0 +1,15 @@
+name: NPM Publish
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  publish-to-npm:
+    permissions:
+      contents: read
+      id-token: write
+    uses: bloq/actions/.github/workflows/npm-publish.yml@v1
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+.eslintcache
+node_modules

.husky/commit-msg

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+commitlint --edit $1

.husky/pre-commit

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+lint-staged

.husky/pre-push

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+npm test

.knip.json

@@ -0,0 +1,3 @@
+{
+  "ignoreDependencies": ["commitlint-config-bloq", "eslint-config-prettier"]
+}

.lintstagedrc.json

@@ -0,0 +1,8 @@
+{
+  "!(.github/workflows/*.yml|*.js|package.json)": [
+    "prettier --ignore-unknown --write"
+  ],
+  ".github/workflows/*.yml": ["npx .", "prettier --write"],
+  "*.js": ["eslint --cache --fix --quiet", "prettier --write"],
+  "package.json": ["better-sort-package-json", "prettier --write"]
+}

.nvmrc

@@ -0,0 +1 @@
+20

.prettierrc.json

@@ -0,0 +1 @@
+{}

README.md

@@ -0,0 +1,52 @@
+# better-sort-github-actions-files
+
+Sorts GitHub Actions workflow or composite action files following these rules:
+
+1. The known properties are sorted following the order in the [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) or [Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions).
+1. All other properties are sorted in alphabetical order.
+
+## Motivation and prior art
+
+Having a consistent properties order in the files helps with the readability and maintainability but following the exact order of the docs can be tricky when done manually. We resolved the same problem in the past for [package.json](https://github.com/hemilabs/better-sort-package-json) files and now was the turn of these YAML files.
+
+## CLI
+
+This package can be installed globally, then used to sort GitHub Actions files:
+
+```sh
+npm install --global better-sort-github-actions
+better-sort-github-actions <path-to-a-github-actions-file-to-sort>
+```
+
+In addition, it can be used without installing it:
+
+```sh
+npx better-sort-github-actions <path-to-a-github-actions-file-to-sort>
+```
+
+## API
+
+Install the package:
+
+```sh
+npm install better-sort-github-actions
+```
+
+Then use it to sort the contents of a YAML file:
+
+```js
+const fs = require("node:fs");
+const { sort } = require("better-sort-github-actions");
+
+fs.writeFileSync(path, sort(fs.readFileSync(path, "utf8")));
+```
+
+## Automatically sort on commit
+
+To let [`lint-staged`](https://github.com/lint-staged/lint-staged) take care of sorting the GitHub Actions files automatically use:
+
+```json
+{
+  ".github/workflows/*.yml": ["better-sort-github-actions"]
+}
+```

bin/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { readFileSync, writeFileSync } = require("node:fs");
+
+const { sort } = require("..");
+
+const files = process.argv.slice(2);
+if (!files.length) {
+  console.error("Usage: better-sort-github-actions <file> [<file>...]");
+  process.exit(1);
+}
+
+// TODO check how globs are handled
+
+try {
+  files.forEach(function (file) {
+    writeFileSync(file, sort(readFileSync(file, "utf8")));
+  });
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}