Compute checksums for transitive Actions

Expand the initialization, updating, and verification to recursively
compute the checksums of transitive Actions. What are transitive
Actions? Those are the actions defined in an Action manifest using the
composite Action type [1]. To capture these, `ghasum` looks at every
Action repository it downloads from GitHub and sees if the manifest (at
the used path in that repository) uses any other actions. If it does, it
adds it to the list of actions to compute a checksum for.

--
1. https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action

Author: ericcornelissen

SPECIFICATION.md

@@ -6,42 +6,6 @@ The specification aims to clarify how `ghasum` operates. Any discrepancy with
 the implementation or ambiguity in the specification can be reported as a bug.
 There is no guarantee on whether the specification or implementation is correct.
 
-## Scope
-
-The scope of `ghasum` are reusable GitHub Actions used in the GitHub Actions
-Workflow of a repository. This excludes
-
-- Actions in the same repository as the workflow ("local actions"). Example:
-
-  ```yaml
-  steps:
-  - uses: ./.github/actions/hello-world-action
-  ```
-
-- Docker Hub Actions ([#216]). Examples:
-
-  ```yaml
-  steps:
-  - uses: docker://alpine:3.8
-  - uses: docker://ghcr.io/OWNER/IMAGE_NAME
-  - uses: docker://gcr.io/cloud-builders/gradle
-  ```
-
-- Reusable workflows ([#215]). Examples:
-
-  ```yaml
-  jobs:
-    call-workflow-1-in-local-repo:
-      uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
-    call-workflow-2-in-local-repo:
-      uses: ./.github/workflows/workflow-2.yml
-    call-workflow-in-another-repo:
-      uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
-  ```
-
-[#215]: https://github.com/chains-project/ghasum/issues/215
-[#216]: https://github.com/chains-project/ghasum/issues/216
-
 ## Actions
 
 ### `ghasum init`
@@ -54,10 +18,11 @@ immediately (it means either 1. the file has been created since it was checked
 and so is not owned by us, or 2. the file could not be created and so cannot be
 initialized).
 
-If the file lock is obtained, the process will compute checksums for all actions
-used in the repository (see [Computing Checksums]) using the best available
-hashing algorithm. Then it stores them in a sumfile (see [Storing Checksums])
-using the latest sumfile version and releases the lock.
+If the file lock is obtained, the process will compute checksums (see [Computing
+Checksums]) for all actions used in the repository (see [Collecting Actions])
+using the best available hashing algorithm. Then it stores them in a sumfile
+(see [Storing Checksums]) using the latest sumfile version. Finally the process
+will releases the lock on the file.
 
 If the process fails an attempt should be made to remove the created file (if
 removing fails the error is ignored).
@@ -74,14 +39,14 @@ by another process leading to an inconsistent state).
 If the file lock is obtained, the process shall first read it and parse it
 completely to extract the sumfile version. If this fails the process shall exit
 immediately unless the `-force` flag is used (see details below). Else it shall
-compute checksums for all new actions used in the repository (see [Computing
-Checksums]) using the best available hashing algorithm. Here, a new action also
-includes a new version of a previously used action. Additionally, it should
-remove any entry which is no longer in use. No existing checksum for a used
-action shall be updated unless the `-force` flag is used. It shall then store
-them in a sumfile (see [Storing Checksums]) using the same sumfile version as
-before and releases the lock. In short, updating will only add new and remove
-old checksums from an existing sumfile.
+compute checksums (see [Computing Checksums]) for all new actions used in the
+repository (see [Collecting Actions]) using the same hashing algorithm as was
+used for the existing checksums. New actions also include new versions of a
+previously used actions. Additionally, it should remove any entry which is no
+longer in use. No existing checksum for a used action shall be updated. It shall
+then store them in a sumfile (see [Storing Checksums]) using the same sumfile
+version as before and releases the lock. In short, updating will only add new
+and remove old checksums from an existing sumfile.
 
 With the `-force` flag the process will ignore errors in the sumfile and fix
 those while updating. It will also update existing checksums that are incorrect.
@@ -99,9 +64,9 @@ error.
 
 If the checksum file exists the process shall read and parse it fully. If this
 fails the process shall exit immediately. Else it shall recompute the checksums
-(see [Computing Checksums]) for all actions in the target using the same hashing
-algorithm as was used for the stored checksums. It shall compare the computed
-checksums against the stored checksums.
+(see [Computing Checksums]) for all actions in the target (see [Collecting
+Actions]) using the same hashing algorithm as was used for the stored checksums.
+It shall compare the computed checksums against the stored checksums.
 
 If any of the checksums does not match or is missing the process shall exit with
 a non-zero exit code, for usability all values should be compared (and all
@@ -117,6 +82,51 @@ Redundant checksums are ignored by this process.
 
 ## Procedures
 
+### Collecting Actions
+
+To determine the set of actions a target depends on, first find all `uses:`
+entries in the target. For a repository this covers all workflows in the
+workflows directory, otherwise it covers only the target.
+
+For each `uses:` value, excluding the list below, it is added to the set and the
+repository declared by the `uses:` value is fetched. The action manifest at the
+path specified in the `uses:` value is parsed for additional `uses:` values. For
+each of these transitive `uses:` values, this process is repeated.
+
+The following `uses:` values are to be excluded from the set of actions a
+repository depends on.
+
+- Actions in the same repository as the workflow ("local actions"). Example:
+
+  ```yaml
+  steps:
+  - uses: ./.github/actions/hello-world-action
+  ```
+
+- Docker Hub Actions ([#216]). Examples:
+
+  ```yaml
+  steps:
+  - uses: docker://alpine:3.8
+  - uses: docker://ghcr.io/OWNER/IMAGE_NAME
+  - uses: docker://gcr.io/cloud-builders/gradle
+  ```
+
+- Reusable workflows ([#215]). Examples:
+
+  ```yaml
+  jobs:
+    call-workflow-1-in-local-repo:
+      uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
+    call-workflow-2-in-local-repo:
+      uses: ./.github/workflows/workflow-2.yml
+    call-workflow-in-another-repo:
+      uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
+  ```
+
+[#215]: https://github.com/chains-project/ghasum/issues/215
+[#216]: https://github.com/chains-project/ghasum/issues/216
+
 ### Computing Checksums
 
 To compute checksums `ghasum` will pull the repository of an action, either at
@@ -181,8 +191,12 @@ version 1
 
 ## Definitions
 
+- _action manifest_ is the file `action.yml` or `action.yaml` (mutually
+  exclusive).
 - _checksum file_ is the file `.github/workflows/gha.sum`.
+- _workflows directory_ is the directory `.github/workflows`.
 
+[collecting actions]: #collecting-actions
 [computing checksums]: #computing-checksums
 [storing checksums]: #storing-checksums
 [sumfile versions]: #sumfile-versions

cmd/ghasum/version.go

@@ -1,4 +1,4 @@
-// Copyright 2024 Eric Cornelissen
+// Copyright 2024-2025 Eric Cornelissen
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

internal/gha/actions.go

@@ -19,45 +19,60 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"maps"
 	"path"
+	"path/filepath"
+	"slices"
 )
 
 type workflowFile struct {
 	path    string
 	content []byte
 }
 
+func actionsInManifest(manifest manifest) ([]GitHubAction, error) {
+	unique := make(map[string]GitHubAction, 0)
+	err := actionsInSteps(manifest.Runs.Steps, unique)
+	if err != nil {
+		return nil, err
+	}
+
+	return slices.Collect(maps.Values(unique)), nil
+}
+
 func actionsInWorkflows(workflows []workflow) ([]GitHubAction, error) {
 	unique := make(map[string]GitHubAction, 0)
 	for _, workflow := range workflows {
 		for _, job := range workflow.Jobs {
-			for _, step := range job.Steps {
-				uses := step.Uses
-				if uses == "" {
-					continue
-				}
-
-				action, err := parseUses(uses)
-				if errors.Is(err, ErrLocalAction) || errors.Is(err, ErrDockerUses) {
-					continue
-				} else if err != nil {
-					return nil, err
-				}
-
-				id := fmt.Sprintf("%s%s%s", action.Owner, action.Project, action.Ref)
-				unique[id] = action
+			err := actionsInSteps(job.Steps, unique)
+			if err != nil {
+				return nil, err
 			}
 		}
 	}
 
-	i := 0
-	actions := make([]GitHubAction, len(unique))
-	for _, action := range unique {
-		actions[i] = action
-		i++
+	return slices.Collect(maps.Values(unique)), nil
+}
+
+func actionsInSteps(steps []step, m map[string]GitHubAction) error {
+	for _, step := range steps {
+		uses := step.Uses
+		if uses == "" {
+			continue
+		}
+
+		action, err := parseUses(uses)
+		if errors.Is(err, ErrLocalAction) || errors.Is(err, ErrDockerUses) {
+			continue
+		} else if err != nil {
+			return err
+		}
+
+		id := fmt.Sprintf("%s%s%s%s", action.Owner, action.Project, action.Path, action.Ref)
+		m[id] = action
 	}
 
-	return actions, nil
+	return nil
 }
 
 func workflowsInRepo(repo fs.FS) ([]workflowFile, error) {
@@ -108,3 +123,17 @@ func workflowInRepo(repo fs.FS, path string) ([]byte, error) {
 	data, _ := io.ReadAll(file)
 	return data, nil
 }
+
+func manifestInRepo(repo fs.FS, dir string) ([]byte, error) {
+	path := filepath.Join(dir, "action.yml")
+	file, err := repo.Open(path)
+	if err != nil {
+		path = filepath.Join(dir, "action.yaml")
+		if file, err = repo.Open(path); err != nil {
+			return nil, fmt.Errorf("could not open manifest (action.yml or action.yaml) at %s: %v", dir, err)
+		}
+	}
+
+	data, _ := io.ReadAll(file)
+	return data, nil
+}