doc: report project metadata update time (#286)

README.md

@@ -190,10 +190,13 @@ Implementations of full algorithms:
 
 ## Adopters
 
-Popular projects using `avo`:
+Popular projects[^projects] using `avo`:
+
+[^projects]: Projects drawn from the `avo` third-party test suite. Popularity
+estimated from Github star count collected on May 9, 2022.
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fgolang.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [golang / **go**](https://github.com/golang/go)
-:star: 98.8k
+:star: 98.9k
 > The Go programming language
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fklauspost.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [klauspost / **compress**](https://github.com/klauspost/compress)
@@ -213,11 +216,11 @@ Popular projects using `avo`:
 > Go library providing algorithms optimized to leverage the characteristics of modern CPUs
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fcloudflare.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [cloudflare / **circl**](https://github.com/cloudflare/circl)
-:star: 616
+:star: 617
 > CIRCL: Cloudflare Interoperable Reusable Cryptographic Library
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fzeebo.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [zeebo / **blake3**](https://github.com/zeebo/blake3)
-:star: 288
+:star: 289
 > Pure Go implementation of BLAKE3 with AVX2 and SSE4.1 acceleration
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Flukechampine.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [lukechampine / **blake3**](https://github.com/lukechampine/blake3)
@@ -225,7 +228,7 @@ Popular projects using `avo`:
 > A pure-Go implementation of the BLAKE3 cryptographic hash function
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fzeebo.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [zeebo / **xxh3**](https://github.com/zeebo/xxh3)
-:star: 240
+:star: 241
 > XXH3 algorithm in Go
 
 <img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fminio.png&w=24" width="24" height="24" hspace="4" valign="middle" /> [minio / **md5-simd**](https://github.com/minio/md5-simd)

internal/cmd/docgen/templates/readme.tmpl

@@ -103,7 +103,10 @@ Implementations of full algorithms:
 
 ## Adopters
 
-Popular projects using `avo`:
+Popular projects[^projects] using `avo`:
+
+[^projects]: Projects drawn from the `avo` third-party test suite. Popularity
+estimated from Github star count collected on {{ .Suite.MetadataLastUpdate.Format "Jan 2, 2006" }}.
 
 {{ range .Suite.Projects.Top 10 -}}
 {{ if lt .Metadata.Stars 100 }}{{break}}{{ end -}}

tests/thirdparty/config.go

@@ -11,6 +11,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 )
 
 // GithubRepository specifies a repository on github.
@@ -355,7 +356,11 @@ func (p Projects) Top(n int) Projects {
 
 // Suite defines a third-party test suite.
 type Suite struct {
+	// Projects to test.
 	Projects Projects `json:"projects"`
+
+	// Time of the last update to project metadata.
+	MetadataLastUpdate time.Time `json:"metadata_last_update"`
 }
 
 func (s *Suite) defaults(set bool) {
@@ -364,7 +369,19 @@ func (s *Suite) defaults(set bool) {
 
 // Validate the test suite.
 func (s *Suite) Validate() error {
-	return s.Projects.Validate()
+	if s.MetadataLastUpdate.IsZero() {
+		return errors.New("empty metadata update time")
+	}
+
+	if s.MetadataLastUpdate.Location() != time.UTC {
+		return errors.New("metadata update time not in UTC")
+	}
+
+	if err := s.Projects.Validate(); err != nil {
+		return err
+	}
+
+	return nil
 }
 
 // LoadSuite loads a test suite from JSON format.

tests/thirdparty/metadata_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"flag"
 	"testing"
+	"time"
 
 	"github.com/mmcloughlin/avo/internal/github"
 	"github.com/mmcloughlin/avo/internal/test"
@@ -50,6 +51,10 @@ func TestSuiteFileMetadata(t *testing.T) {
 		}
 	}
 
+	if *update {
+		s.MetadataLastUpdate = time.Now().UTC()
+	}
+
 	if err := StoreSuiteFile("suite.json", s); err != nil {
 		t.Fatal(err)
 	}

tests/thirdparty/suite.json

@@ -7,7 +7,7 @@
             },
             "metadata": {
                 "description": "XXH3 algorithm in Go",
-                "stars": 240
+                "stars": 241
             },
             "default_branch": "master",
             "version": "v1.0.0-rc1",
@@ -145,7 +145,7 @@
             },
             "metadata": {
                 "description": "Pure Go implementation of BLAKE3 with AVX2 and SSE4.1 acceleration",
-                "stars": 288
+                "stars": 289
             },
             "default_branch": "master",
             "version": "25dba572f0e78ec108f0dd79c9c15288f542d7d9",
@@ -230,7 +230,7 @@
             },
             "metadata": {
                 "description": "Optimized Go Compression Packages",
-                "stars": 2894
+                "stars": 2896
             },
             "default_branch": "master",
             "version": "2f236383d7c2faa8ef7e354ccecb926a5b47a24d",
@@ -634,7 +634,7 @@
             "metadata": {
                 "description": "[mirror] Go supplementary cryptography libraries",
                 "homepage": "https://golang.org/x/crypto",
-                "stars": 2416
+                "stars": 2417
             },
             "default_branch": "master",
             "version": "089bfa5675191fd96a44247682f76ebca03d7916",
@@ -746,7 +746,7 @@
             "metadata": {
                 "description": "The Go programming language",
                 "homepage": "https://go.dev",
-                "stars": 98831
+                "stars": 98856
             },
             "default_branch": "master",
             "version": "go1.17.3",
@@ -788,7 +788,7 @@
             "metadata": {
                 "description": "CIRCL: Cloudflare Interoperable Reusable Cryptographic Library",
                 "homepage": "http://blog.cloudflare.com/introducing-circl",
-                "stars": 616
+                "stars": 617
             },
             "default_branch": "master",
             "version": "v1.1.0",
@@ -831,5 +831,6 @@
                 }
             ]
         }
-    ]
+    ],
+    "metadata_last_update": "2022-05-09T00:15:10.660584088Z"
 }