ci: Add formatting pre-submit check (#3654)

# Summary

Adds a formatting pre-submit check that runs `make format` and checks
for file differences. The results of running `make format` are not
included in this PR for readability. So the pre-submit will depend on
#3655 and probably some more formatting before the check will pass.

Added a `make shfmt` formatting check for bash scripts.

`autogen` (for adding license headers) is now vendored in the
`third_party` directory for convenience sake.

`markdown-toc` and `autogen` are now run by `make format`. The
formatting pre-submit now runs these as well so they don't have separate
pre-submit jobs. We will need to adjust the required checks on branch
protection to remove "markdown-toc" and "autogen" jobs, and also add the
"formatting" job.

`CONTRIBUTING.md` was updated to include some more information about
coding style and conventions.

## Testing Process

1. Run `make format`
2. Verify the formatting results

## Checklist

- [x] Review the contributing
[guidelines](https://github.com/slsa-framework/slsa-github-generator/blob/main/CONTRIBUTING.md)
- [x] Add a reference to related issues in the PR description.
- [x] Update documentation if applicable.
- [x] Add unit tests if applicable.
- [x] Add changes to the
[CHANGELOG](https://github.com/slsa-framework/slsa-github-generator/blob/main/CHANGELOG.md)
if applicable.

---------

Signed-off-by: Ian Lewis <[email protected]>

Author: ianlewis

.github/actions/generate-builder/builder-fetch.sh

@@ -29,46 +29,46 @@ PREFIX="refs/tags/"
 
 # Extract version.
 if [[ "$BUILDER_REF" != "$PREFIX"* ]]; then
-    echo "Invalid ref: $BUILDER_REF. Expected ref of the form refs/tags/vX.Y.Z"
-    exit 2
+  echo "Invalid ref: $BUILDER_REF. Expected ref of the form refs/tags/vX.Y.Z"
+  exit 2
 fi
 
 builder_tag="${BUILDER_REF#"$PREFIX"}"
 
 if [[ "$builder_tag" == "$(echo -n "$builder_tag" | grep -P '^[a-f\d]{40}$')" ]]; then
-    echo "Builder referenced by hash: $builder_tag"
-    echo "Resolving..."
-
-    release_tag=""
-
-    # List the releases and find the corresponding hash.
-    release_list=$(gh release -R "$BUILDER_REPOSITORY" -L 50 list)
-    while read -r line; do
-        tag=$(echo "$line" | cut -f1)
-        branch=$(gh release -R "$BUILDER_REPOSITORY" view "$tag" --json targetCommitish --jq '.targetCommitish')
-        if [[ "$branch" != "main" ]]; then
-            continue
-        fi
-        commit=$(gh api /repos/"$BUILDER_REPOSITORY"/git/ref/tags/"$tag" | jq -r '.object.sha')
-        if [[ "$commit" == "$builder_tag" ]]; then
-            release_tag="$tag"
-            echo "Found tag $builder_tag match at tag $tag and commit $commit"
-            break
-        fi
-    done <<<"$release_list"
-
-    if [[ -z "$release_tag" ]]; then
-        echo "Tag not found for $builder_tag"
-        exit 3
+  echo "Builder referenced by hash: $builder_tag"
+  echo "Resolving..."
+
+  release_tag=""
+
+  # List the releases and find the corresponding hash.
+  release_list=$(gh release -R "$BUILDER_REPOSITORY" -L 50 list)
+  while read -r line; do
+    tag=$(echo "$line" | cut -f1)
+    branch=$(gh release -R "$BUILDER_REPOSITORY" view "$tag" --json targetCommitish --jq '.targetCommitish')
+    if [[ "$branch" != "main" ]]; then
+      continue
     fi
+    commit=$(gh api /repos/"$BUILDER_REPOSITORY"/git/ref/tags/"$tag" | jq -r '.object.sha')
+    if [[ "$commit" == "$builder_tag" ]]; then
+      release_tag="$tag"
+      echo "Found tag $builder_tag match at tag $tag and commit $commit"
+      break
+    fi
+  done <<<"$release_list"
+
+  if [[ -z "$release_tag" ]]; then
+    echo "Tag not found for $builder_tag"
+    exit 3
+  fi
 
-    builder_tag="$release_tag"
+  builder_tag="$release_tag"
 fi
 
 if [[ "$builder_tag" != "$(echo -n "$builder_tag" | grep -oe '^v[1-9]\+\.[0-9]\+\.[0-9]\+\(-rc\.[0-9]\+\)\?$')" ]]; then
-    echo "Invalid builder version: $builder_tag. Expected version of the form vX.Y.Z(-rc.A)"
-    echo "For details see https://github.com/slsa-framework/slsa-github-generator/blob/main/README.md#referencing-slsa-builders-and-generators"
-    exit 7
+  echo "Invalid builder version: $builder_tag. Expected version of the form vX.Y.Z(-rc.A)"
+  echo "For details see https://github.com/slsa-framework/slsa-github-generator/blob/main/README.md#referencing-slsa-builders-and-generators"
+  exit 7
 fi
 
 echo "Builder version: $builder_tag"
@@ -88,23 +88,23 @@ echo "verifier hash verification has passed"
 # If this is a pre-release, set SLSA_VERIFIER_TESTING
 pre_release=$(echo "${builder_tag#"v"}" | cut -s -d '-' -f2)
 if [ "${pre_release}" != "" ]; then
-    export SLSA_VERIFIER_TESTING="true"
+  export SLSA_VERIFIER_TESTING="true"
 fi
 
 # Verify the provenance of the builder.
 chmod a+x "$VERIFIER_RELEASE_BINARY"
 ./"$VERIFIER_RELEASE_BINARY" verify-artifact \
-    --source-branch "main" \
-    --source-tag "$builder_tag" \
-    --provenance-path "$BUILDER_RELEASE_BINARY.intoto.jsonl" \
-    --source-uri "github.com/$BUILDER_REPOSITORY" \
-    "$BUILDER_RELEASE_BINARY" || exit 6
+  --source-branch "main" \
+  --source-tag "$builder_tag" \
+  --provenance-path "$BUILDER_RELEASE_BINARY.intoto.jsonl" \
+  --source-uri "github.com/$BUILDER_REPOSITORY" \
+  "$BUILDER_RELEASE_BINARY" || exit 6
 
 builder_commit=$(gh api /repos/"$BUILDER_REPOSITORY"/git/ref/tags/"$builder_tag" | jq -r '.object.sha')
 provenance_commit=$(jq -r '.payload' <"$BUILDER_RELEASE_BINARY.intoto.jsonl" | base64 -d | jq -r '.predicate.materials[0].digest.sha1')
 if [[ "$builder_commit" != "$provenance_commit" ]]; then
-    echo "Builder commit sha $builder_commit != provenance material $provenance_commit"
-    exit 5
+  echo "Builder commit sha $builder_commit != provenance material $provenance_commit"
+  exit 5
 fi
 
 #TODO: verify the command

.github/actions/generate-builder/generate-builder.sh

@@ -17,25 +17,25 @@
 set -euo pipefail
 
 if [[ "$COMPILE_BUILDER" == true ]]; then
-    echo "Building the builder with ref: $BUILDER_REF"
+  echo "Building the builder with ref: $BUILDER_REF"
 
-    cd "$BUILDER_DIR"
-    git checkout "$BUILDER_REF"
+  cd "$BUILDER_DIR"
+  git checkout "$BUILDER_REF"
 
-    #TODO(reproducible)
-    go mod vendor
+  #TODO(reproducible)
+  go mod vendor
 
-    # https://go.dev/ref/mod#build-commands.
-    go build -mod=vendor -o "$BUILDER_RELEASE_BINARY"
+  # https://go.dev/ref/mod#build-commands.
+  go build -mod=vendor -o "$BUILDER_RELEASE_BINARY"
 
-    cd -
+  cd -
 
-    mv "$BUILDER_DIR/$BUILDER_RELEASE_BINARY" .
+  mv "$BUILDER_DIR/$BUILDER_RELEASE_BINARY" .
 
 else
-    echo "Fetching the builder with ref: $BUILDER_REF"
+  echo "Fetching the builder with ref: $BUILDER_REF"
 
-    ./__BUILDER_CHECKOUT_DIR__/.github/actions/generate-builder/builder-fetch.sh
+  ./__BUILDER_CHECKOUT_DIR__/.github/actions/generate-builder/builder-fetch.sh
 fi
 
 chmod u+x "$BUILDER_RELEASE_BINARY"

.github/workflows/pre-submit.lint.yml

@@ -28,26 +28,56 @@ permissions:
   contents: read
 
 jobs:
-  markdownlint:
+  formatting:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
-      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: actions/setup-go@cdcb36043654635271a94b9a6d1392de5bb323a7 # v5.0.1
+        with:
+          go-version: "1.22.3"
+      - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d # v3.8.1
         with:
           node-version: 20
-      - run: make markdownlint
 
-  markdown-toc:
-    name: markdown-toc
+      - name: Install gofumpt
+        run: go install mvdan.cc/[email protected]
+
+      - name: Install shfmt
+        env:
+          SHFMT_VERSION: "3.8.0"
+          SHFMT_CHECKSUM: "27b3c6f9d9592fc5b4856c341d1ff2c88856709b9e76469313642a1d7b558fe0"
+        run: |
+          set -euo pipefail
+
+          #Install golangci-lint
+          curl -sSLo shfmt "https://github.com/mvdan/sh/releases/download/v${SHFMT_VERSION}/shfmt_v${SHFMT_VERSION}_linux_amd64"
+          echo "shfmt checksum is $(sha256sum shfmt | awk '{ print $1 }')"
+          echo "expected checksum is ${SHFMT_CHECKSUM}"
+          echo "${SHFMT_CHECKSUM}  shfmt" | sha256sum --strict --check --status || exit 1
+          chmod +x shfmt
+          mv shfmt /usr/local/bin
+
+      - run: make format
+      - name: Check for unformatted files
+        id: diff
+        run: |
+          set -euo pipefail
+          if [ "$(git diff --ignore-space-at-eol . | wc -l)" -gt "0" ]; then
+            echo "Detected uncommitted changes after formatting."
+            echo "Run 'make format' to format files in your PR."
+            echo "See status below:"
+            git diff
+            exit 1
+          fi
+
+  markdownlint:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
       - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: 20
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
-      - run: make markdown-toc
-      - name: markdown-toc
-        run: ./.github/workflows/scripts/pre-submit.markdown/markdown-toc.sh
+      - run: make markdownlint
 
   golangci-lint:
     runs-on: ubuntu-latest
@@ -143,24 +173,3 @@ jobs:
         with:
           node-version: 20
       - run: make renovate-config-validator
-
-  autogen:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
-        with:
-          repository: mbrukman/autogen
-          ref: 9026b78e17573b5dda4bff79033c352443551dc5
-          path: autogen
-      - run: |
-          echo "${GITHUB_WORKSPACE}/autogen" >> "${GITHUB_PATH}"
-      - run: make autogen
-      - name: check diff
-        run: |
-          set -euo pipefail
-          if [ "$(GIT_PAGER="cat" git diff --ignore-space-at-eol | wc -l)" -gt "0" ]; then
-              echo "Detected license header changes.  See status below:"
-              GIT_PAGER="cat" git diff
-              exit 1
-          fi