feat: support pinning target by sha1 hash

Closes #26

Accept a new format to specify a target:

```
{owner}/{repository}@{sha1-hash}
```

Note that this commit must still be associated with a GitHub release
with an exact semantic version, because the release is the mechanism
of hosting pre-compiled binaries.

For example:

```yaml
- uses: EricCrosson/install-github-release-binary@v2
  with:
    targets: EricCrosson/hoverboard@7382f9a3ce14be1fd8b3656d262fc2c720c8f51c
```

Author: EricCrosson

README.md

@@ -47,26 +47,33 @@ Install multiple binaries:
     targets: |
       EricCrosson/flux-capacitor@v1
       EricCrosson/steam-locomotive@v7.5.3
+      EricCrosson/hoverboard@7382f9a3ce14be1fd8b3656d262fc2c720c8f51c
 ```
 
 ## Inputs
 
-| Input Parameter | Required | Description                                                                                                     |
-| :-------------: | :------: | --------------------------------------------------------------------------------------------------------------- |
-|     targets     |   true   | Whitespace separated list of target GitHub Releases in format `{owner}/{repository}@{tag}`. [Details](#targets) |
-|      token      |  false   | GitHub token for REST requests. Defaults to `${{ github.token }}`. [Details](#token)                            |
+| Input Parameter | Required | Description                                                                                                         |
+| :-------------: | :------: | ------------------------------------------------------------------------------------------------------------------- |
+|     targets     |   true   | Whitespace separated list of target GitHub Releases in format `{owner}/{repository}@{version}`. [Details](#targets) |
+|      token      |  false   | GitHub token for REST requests. Defaults to `${{ github.token }}`. [Details](#token)                                |
 
 #### targets
 
-Target repository slug and tag: `{owner}/{repository}@v{semantic-version}`.
-Example: `EricCrosson/flux-capacitor@v1`.
+Specify a whitespace-separated list of targets.
+
+Each target is specified by repo slug and a [semantic version number] or sha1 hash.
+
+Accepted formats:
+
+- `{owner}/{repository}@v{semantic-version}`
+- `{owner}/{repository}@{sha1-hash}`
 
-Tags are of the format `v{semantic-version}`, where `{semantic-version}` is a [semantic version number].
 Examples:
 
-- `v1`
-- `v1.2`
-- `v1.2.3`
+- `EricCrosson/flux-capacitor@v1`
+- `EricCrosson/flux-capacitor@v1.2`
+- `EricCrosson/flux-capacitor@v1.2.3`
+- `EricCrosson/flux-capacitor@aaebf5c572b64d17710f936905c1b35e1f58acc8`
 
 [semantic version number]: https://semver.org/
 

src/fetch.ts

@@ -6,12 +6,13 @@ import {
   ExactSemanticVersion,
   RepositorySlug,
   SemanticVersion,
-  Sha,
+  Sha1Hash,
   TargetTriple,
+  isSha1Hash,
 } from "./types";
 
 type Commit = {
-  sha: Sha;
+  sha: Sha1Hash;
 };
 
 // This type is only exported for testing.
@@ -22,6 +23,19 @@ export type Tag = {
 
 export type TagsResponse = ReadonlyArray<Tag>;
 
+// This function is only exported for testing.
+export function sha1HashReducer(
+  givenSha: Sha1Hash
+): (tag: Tag) => Option<ExactSemanticVersion> {
+  return function reducer(tag: Tag): Option<ExactSemanticVersion> {
+    const version = tag.name;
+    if (tag.commit.sha === givenSha && isExactSemanticVersion(version)) {
+      return some(version);
+    }
+    return none();
+  };
+}
+
 function containsExactTag(
   tags: readonly SemanticVersion[] | undefined
 ): ExactSemanticVersion | undefined {
@@ -32,9 +46,11 @@ function containsExactTag(
 }
 
 // This function is only exported for testing.
-export function exactSemanticVersionTagReducer(givenTag: SemanticVersion) {
-  const versionsBySha: Record<Sha, SemanticVersion[]> = {};
-  let givenTagSha: Option<Sha> = none();
+export function semanticVersionTagReducer(
+  givenTag: SemanticVersion
+): (tag: Tag) => Option<ExactSemanticVersion> {
+  const versionsBySha: Record<Sha1Hash, SemanticVersion[]> = {};
+  let givenTagSha: Option<Sha1Hash> = none();
 
   // Conditions for an exact match are -- we know both the:
   //
@@ -88,13 +104,15 @@ export function exactSemanticVersionTagReducer(givenTag: SemanticVersion) {
 export async function findExactSemanticVersionTag(
   octokit: Octokit,
   slug: RepositorySlug,
-  givenTag: SemanticVersion
+  target: SemanticVersion | Sha1Hash
 ): Promise<ExactSemanticVersion> {
-  if (isExactSemanticVersion(givenTag)) {
-    return givenTag;
+  if (isExactSemanticVersion(target)) {
+    return target;
   }
 
-  const reducer = exactSemanticVersionTagReducer(givenTag);
+  const reducer = isSha1Hash(target)
+    ? sha1HashReducer(target)
+    : semanticVersionTagReducer(target);
 
   for await (const response of octokit.paginate.iterator(
     octokit.rest.repos.listTags,
@@ -113,8 +131,12 @@ export async function findExactSemanticVersionTag(
     }
   }
 
+  const expected = isSha1Hash(target)
+    ? "a commit"
+    : "an exact semantic version tag";
+
   throw new Error(
-    `Expected to find an exact semantic version tag matching ${givenTag} for ${slug.owner}/${slug.repository}`
+    `Expected to find ${expected} matching ${target} for ${slug.owner}/${slug.repository}`
   );
 }
 

src/index.ts

@@ -12,14 +12,17 @@ import {
   parseEnvironmentVariable,
   parseTargetReleases,
   parseToken,
-  TargetRelease,
 } from "./parse";
 import { getTargetTriple } from "./platform";
 import {
   fetchReleaseAssetMetadataFromTag,
   findExactSemanticVersionTag,
 } from "./fetch";
-import type { ExactSemanticVersion, RepositorySlug } from "./types";
+import type {
+  ExactSemanticVersion,
+  RepositorySlug,
+  TargetRelease,
+} from "./types";
 
 function getDestinationDirectory(
   storageDirectory: string,

src/parse.ts

@@ -1,5 +1,15 @@
 import { Either, error, isOk, ok } from "./either";
-import type { RepositorySlug, SemanticVersion } from "./types";
+import type { SemanticVersion, Sha1Hash, TargetRelease } from "./types";
+
+const regexes = {
+  owner: /\S+/,
+  repository: /\S+/,
+  majorSemanticVersion: /v(0|[1-9]\d*)/,
+  majorMinorSemanticVersion: /v(0|[1-9]\d*)\.(0|[1-9]\d*)/,
+  exactSemanticVersion:
+    /v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?/,
+  sha1Hash: /[0-9a-f]{40}/,
+};
 
 export function parseEnvironmentVariable(envVarName: string): Either<string> {
   const value = process.env[envVarName];
@@ -23,49 +33,45 @@ export function parseToken(value: string): Either<string> {
   return ok(value);
 }
 
-export type TargetRelease = {
-  slug: RepositorySlug;
-  tag: SemanticVersion;
-};
-
-function parseTargetRelease(value: string): Either<TargetRelease> {
-  const errors: string[] = [];
-  const repo_regex = /^(\S+)\/(\S+)$/;
-  if (repo_regex.test(value) === null) {
-    errors.push(
-      "input.repo does not describe a GitHub repository -- expected {owner}/{repository}@{tag} format (example: EricCrosson/git-disjoint@v2)"
-    );
-  }
-  const tag_regex = /^(\S+)@v(\S+)$/;
-  if (tag_regex.test(value) === null) {
-    errors.push(
-      "input.repo does not describe a tag version -- expected {owner}/{repository}@{tag} format (example: EricCrosson/git-disjoint@v2)"
-    );
-  }
-  if (errors.length > 0) {
-    return error(errors);
-  }
-
-  const regex = /^(\S+)\/(\S+)@(v\S+)$/;
+function parseTargetReleaseVersion(value: string): Either<TargetRelease> {
+  const {
+    owner,
+    repository,
+    majorSemanticVersion,
+    majorMinorSemanticVersion,
+    exactSemanticVersion,
+    sha1Hash,
+  } = regexes;
+  const regex = new RegExp(
+    `^(${owner.source})/(${repository.source})@((${sha1Hash.source})|${majorSemanticVersion.source}|${majorMinorSemanticVersion.source}|${exactSemanticVersion.source})$`
+  );
   const match = value.match(regex);
-  if (match === null || match.length !== 4) {
-    return error([
-      "input.repo invalid -- expected {owner}/{repository}@{tag} format (example: EricCrosson/git-disjoint@v2)",
-    ]);
+  if (match === null) {
+    // This error message is never used
+    return error(["not a valid target release"]);
   }
-
   const target: TargetRelease = {
     slug: {
       owner: match[1] as string,
       repository: match[2] as string,
     },
-    // NOTE: we're not really parsing the content of this string,
-    // so this is an unlawful type assertion
-    tag: match[3] as SemanticVersion,
+    tag: match[3] as SemanticVersion | Sha1Hash,
   };
   return ok(target);
 }
 
+function parseTargetRelease(value: string): Either<TargetRelease> {
+  const maybeTargetRelease = parseTargetReleaseVersion(value);
+
+  if (isOk(maybeTargetRelease)) {
+    return ok(maybeTargetRelease.value);
+  }
+
+  return error([
+    `input.targetes invalid -- '${value}' does not match expected format '{owner}/{repository}@{tag}' (example: EricCrosson/git-disjoint@v2)`,
+  ]);
+}
+
 export function parseTargetReleases(value: string): Either<TargetRelease[]> {
   if (value.length === 0) {
     return error(["input.targets not defined"]);

src/types.ts

@@ -21,11 +21,21 @@ export function isExactSemanticVersion(
   return regex.test(value);
 }
 
-export type Sha = string & { readonly __tag: unique symbol };
+export type Sha1Hash = string & { readonly __tag: unique symbol };
+
+export function isSha1Hash(value: string): value is Sha1Hash {
+  const regex = /^[0-9a-f]{40}$/;
+  return regex.test(value);
+}
 
 export type RepositorySlug = {
   owner: string;
   repository: string;
 };
 
 export type TargetTriple = string & { readonly __tag: unique symbol };
+
+export type TargetRelease = {
+  slug: RepositorySlug;
+  tag: SemanticVersion | Sha1Hash;
+};

test/test-find-exact-semantic-version-tag.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import type { ExactSemanticVersion, SemanticVersion } from "../src/types";
-import { exactSemanticVersionTagReducer, Tag } from "../src/fetch";
+import { semanticVersionTagReducer, Tag } from "../src/fetch";
 import { isNone, isSome, none, Option, some } from "../src/option";
 
 import noReleaseCandidates from "./no-release-candidate-workflow.json";
@@ -13,9 +13,11 @@ function check(
   testData: readonly Tag[],
   expectedOutput: Option<ExactSemanticVersion>
 ) {
-  const reducer = exactSemanticVersionTagReducer(givenTag);
+  const reducer = semanticVersionTagReducer(givenTag);
+  // Take the first 'some'
   const actualOutput = testData.reduce<Option<ExactSemanticVersion>>(
-    (_previousResult, tag) => reducer(tag),
+    (previousResult, tag) =>
+      isNone(previousResult) ? reducer(tag) : previousResult,
     none()
   );
 

test/test-find-release-by-exact-semantic-version-tag.ts

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import type { ExactSemanticVersion, SemanticVersion } from "../src/types";
+import { semanticVersionTagReducer, Tag } from "../src/fetch";
+import { isNone, isSome, none, Option, some } from "../src/option";
+
+import noReleaseCandidates from "./no-release-candidate-workflow.json";
+import withReleaseCandidates from "./beta-workflow.json";
+
+function check(
+  givenTag: SemanticVersion,
+  testData: readonly Tag[],
+  expectedOutput: Option<ExactSemanticVersion>
+) {
+  const reducer = semanticVersionTagReducer(givenTag);
+  const actualOutput = testData.reduce<Option<ExactSemanticVersion>>(
+    (_previousResult, tag) => reducer(tag),
+    none()
+  );
+
+  // wrap in a thunk so we can pass it directly to `test`
+  return function () {
+    if (isSome(expectedOutput)) {
+      assert.deepEqual(actualOutput, expectedOutput);
+    } else {
+      // I don't care too much right now what the error is
+      assert(isNone(actualOutput));
+    }
+  };
+}
+
+test(
+  "should resolve an exact semantic tag when the upstream project does not use release candidates",
+  check(
+    "v1" as SemanticVersion,
+    noReleaseCandidates as unknown as Tag[],
+    some("v1.0.8" as ExactSemanticVersion)
+  )
+);
+
+test(
+  "should resolve an exact semantic tag when the upstream project use release candidates",
+  check(
+    "v1" as SemanticVersion,
+    withReleaseCandidates as unknown as Tag[],
+    some("v1.1.0-beta.1" as ExactSemanticVersion)
+  )
+);