Add formatting/linting recipes to Justfile (#364)

* added 3 recipes to keep things consistent
 - clean: remove temp files used during formatting
 - format: uses `jq` to format the files
 - hooks: installs pre-commit hooks as a lint/formatting guard
 - lint: uses `jq` to verify *.json files

this also updates `schemas` which adds a verbose to see all the files
that'll be copied to `.schemas`, while also adding a lint/verify step to
ensure we have well-formed files

revised changelist
* chore: format all json files for consistency
* fix: add escaped slash for did path
* chore(hermit): add jq
* chore: add github actions for consistent json
* fix: add permissions to create issues
* fix: add repo permissions
* feat: add pre-commit hook to enforce local first

.github/workflows/format.yml

@@ -0,0 +1,62 @@
+name: format json files with `jq`
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  format-json:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v4
+
+      - uses: cashapp/activate-hermit@v1
+        name: setup hermit with `just` and `jq`
+        with:
+          cache: true
+
+      - name: format json files
+        id: format-json
+        run: |
+          if just format; then
+            echo "format_failed=false" >> $GITHUB_ENV
+          else
+            echo "format_failed=true" >> $GITHUB_ENV
+          fi
+
+      - name: check for changes
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changes_detected=true" >> $GITHUB_ENV
+          else
+            echo "changes_detected=false" >> $GITHUB_ENV
+          fi
+
+      - name: commit changes
+        if: env.changes_detected == 'true'
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add "**/*.json"
+          git commit --message "chore: format json files"
+          git push
+
+      - name: create issue if formatting failed
+        if: failure() && env.format_failed == 'true'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'JSON Formatting Failed',
+              body: 'The automatic JSON formatting job failed. Please check the logs and fix the issues manually.'
+            })

.github/workflows/lint.yml

@@ -0,0 +1,45 @@
+name: lint json files with `jq`
+on:
+  workflow_run:
+    workflows: ["run-linter"]
+    types:
+      - completed
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  lint-json:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v4
+
+      - uses: cashapp/activate-hermit@v1
+        name: setup hermit with `just` and `jq`
+        with:
+          cache: true
+
+      - name: lint json files
+        id: lint-json
+        run: |
+          if just lint; then
+            echo "lint_failed=false" >> $GITHUB_ENV
+          else
+            echo "lint_failed=true" >> $GITHUB_ENV
+          fi
+
+      - name: add a comment to the pull request
+        if: env.lint_failed == 'true'
+        uses: actions/github-script@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: "[error] linting failed. please fix the errors and push again."
+            })

.github/workflows/trigger-lint.yml

@@ -0,0 +1,19 @@
+name: run-linter
+
+on:
+  push:
+    branches:
+      - "**"
+
+jobs:
+  trigger-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "[trigger]: run lint workflow"
+        run: |
+          curl \
+            --request POST \
+            --user "${{ secrets.GITHUB_TOKEN }}" \
+            --header "Accept: application/vnd.github.v3+json" \
+            --url "https://api.github.com/repos/TBD54566975/tbdex/actions/workflows/lint.yml/dispatches" \
+            --data '{"ref": "main"}'

Justfile

@@ -1,16 +1,58 @@
-set positional-arguments
+set positional-arguments := true
 
 _help:
-  @just -l
-
-schemas:
-  #!/bin/bash
-  set -euo pipefail
-
-  source_dir="hosted/json-schemas" 
-  dest_dir=".schemas"
-
-  mkdir -p $dest_dir
-  rm -rf $dest_dir/*
-  cp -R $source_dir/* $dest_dir/
-  echo "Schema files successfully copied to $dest_dir/"
+    @just -l
+
+clean: install_hooks
+    #!/usr/bin/env bash
+    find hosted -type f -name "*.tmp" -delete
+
+install_hooks:
+    #!/usr/bin/env bash
+    cp hooks/pre-commit .git/hooks/pre-commit
+    chmod +x .git/hooks/pre-commit
+
+format: lint
+    #!/usr/bin/env bash
+    find hosted -type f -name "*.json" | while read file; do
+      jq --indent 2 . $file > $file.json.tmp
+      if ! diff --brief $file $file.json.tmp > /dev/null; then
+        mv $file.json.tmp $file
+        printf "formatted: %s\n" $file
+      else
+        rm $file.json.tmp
+      fi
+    done
+
+lint: clean
+    #!/usr/bin/env bash
+    if ! command -v jq &> /dev/null; then
+      echo "jq is not installed. Please install jq to format JSON files"
+      exit 1
+    fi
+
+    no_errors_found=true
+    for file in $(find hosted -type f -name "*.json"); do
+      if ! jq empty $file > /dev/null; then
+        printf "[error] %s is not a valid JSON file\n\n" $file
+        no_errors_found=false
+      fi
+    done
+
+    if [ "$no_errors_found" = true ]; then
+      echo "[success] All JSON files are valid"
+    else
+      exit 1
+    fi
+
+schemas: lint
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    source_dir="hosted/json-schemas"
+    dest_dir=".schemas"
+
+    rm -rf $dest_dir
+    mkdir -p $dest_dir
+    cp -vR $source_dir/* $dest_dir/
+    echo "Schema files successfully copied to $dest_dir/"

bin/.jq-1.7.1.pkg

@@ -0,0 +1 @@
+hermit

bin/jq

@@ -0,0 +1 @@
+.jq-1.7.1.pkg

hooks/pre-commit

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+if just lint; then
+  echo "[success] linting passed"
+else
+  echo "[error] linting failed"
+  exit 1
+fi

hosted/json-schemas/cancel.schema.json

@@ -1,11 +1,11 @@
 {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "$id": "https://tbdex.dev/cancel.schema.json",
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "reason": {
-        "type": "string"
-      }
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://tbdex.dev/cancel.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
     }
-  }
+  }
+}

hosted/json-schemas/close.schema.json

@@ -11,4 +11,4 @@
       "type": "boolean"
     }
   }
-}
+}

hosted/json-schemas/definitions.json

@@ -5,11 +5,11 @@
   "definitions": {
     "did": {
       "type": "string",
-      "pattern": "^did:([a-z0-9]+):((?:(?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))*:)*((?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))+))((;[a-zA-Z0-9_.:%-]+=[a-zA-Z0-9_.:%-]*)*)(\/[^#?]*)?([?][^#]*)?(#.*)?$"
+      "pattern": "^did:([a-z0-9]+):((?:(?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))*:)*((?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))+))((;[a-zA-Z0-9_.:%-]+=[a-zA-Z0-9_.:%-]*)*)(\\/[^#?]*)?([?][^#]*)?(#.*)?$"
     },
     "decimalString": {
       "type": "string",
       "pattern": "^([0-9]+(?:[.][0-9]+)?)$"
     }
   }
-}
+}

hosted/json-schemas/message.schema.json

@@ -16,7 +16,15 @@
         },
         "kind": {
           "type": "string",
-          "enum": ["rfq", "quote", "order", "orderstatus", "close", "cancel", "orderinstructions"],
+          "enum": [
+            "rfq",
+            "quote",
+            "order",
+            "orderstatus",
+            "close",
+            "cancel",
+            "orderinstructions"
+          ],
           "description": "The message kind (e.g. rfq, quote)"
         },
         "id": {
@@ -40,7 +48,15 @@
           "description": "Version of the protocol in use (x.x format)"
         }
       },
-      "required": ["from", "to", "kind", "id", "exchangeId", "createdAt", "protocol"]
+      "required": [
+        "from",
+        "to",
+        "kind",
+        "id",
+        "exchangeId",
+        "createdAt",
+        "protocol"
+      ]
     }
   },
   "type": "object",
@@ -62,5 +78,9 @@
     }
   },
   "additionalProperties": false,
-  "required": ["metadata", "data", "signature"]
+  "required": [
+    "metadata",
+    "data",
+    "signature"
+  ]
 }

hosted/json-schemas/offering.schema.json

@@ -63,11 +63,16 @@
                 "description": "Fee charged to use this payment method. Absence of this field implies that there is no _additional_ fee associated to the respective payment method."
               }
             },
-            "required": ["kind"]
+            "required": [
+              "kind"
+            ]
           }
         }
       },
-      "required": ["currencyCode", "methods"]
+      "required": [
+        "currencyCode",
+        "methods"
+      ]
     },
     "payout": {
       "type": "object",
@@ -129,11 +134,17 @@
                 "minimum": 0
               }
             },
-            "required": ["kind", "estimatedSettlementTime"]
+            "required": [
+              "kind",
+              "estimatedSettlementTime"
+            ]
           }
         }
       },
-      "required": ["currencyCode", "methods"]
+      "required": [
+        "currencyCode",
+        "methods"
+      ]
     },
     "payoutUnitsPerPayinUnit": {
       "type": "string",
@@ -159,7 +170,9 @@
           "description": "A human-readable description of the terms of cancellation in plaintext"
         }
       },
-      "required": ["enabled"]
+      "required": [
+        "enabled"
+      ]
     }
   },
   "required": [

hosted/json-schemas/order.schema.json

@@ -4,4 +4,4 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {}
-}
+}

hosted/json-schemas/orderinstructions.schema.json

@@ -27,5 +27,8 @@
       }
     }
   },
-  "required": ["payin", "payout"]
+  "required": [
+    "payin",
+    "payout"
+  ]
 }